Data API Documentation

Using the Data API

To use the Data API, you will need to have a Tierion account. If you do not have an account, please signup for an account before getting started. We welcome your feedback and suggestions.

Authentication

Accessing Tierion's Data API requires an API Key. You'll find your API key under the API tab of your Datastores.

You must include your Username and API Key in every request to the Data API. Username is the email address used to log into Tierion. Submit these credentials by adding the headers X-Username and X-Api-Key.

Every Data API request must contain the following headers:

X-Username: youremail@address.com
X-Api-Key: YourAPIKeyGoesHere

Requests

Tierion uses REST methodology for its APIs. All data included in requests to API methods must be JSON formatted or form-urlencoded.

Remember to set the content-type header to the format of your data.

Content-Type: application/x-www-form-urlencoded

or

Content-Type: application/json

All requests to the Data API must be made over HTTPS. Any request made over plain HTTP will fail and return a 403 Forbidden error response.

HTTPS is required for all requests.

Responses

All responses are JSON formatted.

If an error occurs when making an API request, an appropriate HTTP error status code is returned, along with a message describing the error. The following is an example of an error response.

Status: 404 Not Found
{
  "error": "Datastore with Id = 574564534 does not exist."
}

Datastores

Datastores are the main organizational objects within Tierion. Datastores contain collections of Records.

Methods

Method Description
Get All Datastores Return a list of all datastores in your Tierion account.
Get Datastore Return the details of a specific Datastore.
Create Datastore Create a new Datastore in your Tierion account.
Update Datastore Update the parameters of a specific Datastore.
Delete Datastore Delete the Datastore and all associated records.

Datastore Object

Name Description
id A unique numeric identifier for the datastore within the system.
key A unique identifier for the datastore used when submitting from HTML forms.
name The name of the datastore.
groupName The name of the group of which this datastore is a member.
redirectEnabled A boolean indicating whether or not the custom redirect URL is enabled.
redirectUrl The URL a user will be redirected to when submitting data from an HTML Form.
emailNotificationEnabled A boolean indicating whether or not the email notification is enabled.
emailNotificationAddress The recipient email address.
postDataEnabled A boolean indicating whether or not the POST data URL is enabled.
postDataUrl The URL that new record data will be POSTed to when received.
postReceiptEnabled A boolean indicating whether or not the POST receipt URL is enabled.
postReceiptUrl The URL that the blockchain receipt data will be POSTed to when generated.
timestamp The number of seconds elapsed since epoch when this Datastore was created.

Get All Datastores

This method returns a list of all datastores in your Tierion account.

GET https://api.tierion.com/v1/datastores

Request Sample

GET   https://api.tierion.com/v1/datastores

Response Sample

Status: 200 OK
[
  {  
    "id": 103,
    "key": "LpdF2vMBB022ea2lL1NxIQ",
    "name": "Website Contacts",
    "groupName": "",
    "redirectEnabled": false,
    "redirectUrl": null,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "pgibbons@initech.net",
    "postDataEnabled": true,
    "postDataUrl": "http://requestb.in/11ar0dj1",
    "postReceiptEnabled": false,
    "postReceiptUrl": null,
    "timestamp": 1433659054
  },
  {  
    "id":104,
    "key": "IxCYt5bJbU2cOcM1cG9rZg",
    "name": "TPS Reports",
    "groupName": "Important",
    "redirectEnabled": true,
    "redirectUrl": "http://www.initech.net/tps/received",
    "emailNotificationEnabled": false,
    "emailNotificationAddress": null,
    "postDataEnabled": false,
    "postDataUrl": null,
    "postReceiptEnabled": true,
    "postReceiptUrl": "http://requestb.in/54Mjdf34d",  
    "timestamp": 1433786283
  }
]

Get Datastore

This method returns the details of a specific datastore.

GET https://api.tierion.com/v1/datastores/<id>

Request Sample

GET   https://api.tierion.com/v1/datastores/103

Response Sample

Status: 200 OK
{  
  "id": 103,
  "key": "LpdF2vMBB022ea2lL1NxIQ",
  "name": "Website Contacts",
  "groupName": "",
  "redirectEnabled": false,
  "redirectUrl": null,
  "emailNotificationEnabled": true,
  "emailNotificationAddress": "pgibbons@initech.net",
  "postDataEnabled": true,
  "postDataUrl": "http://requestb.in/11ar0dj1",
  "postReceiptEnabled": true,
  "postReceiptUrl": "http://requestb.in/54Mjdf34d",     
  "timestamp": 1433659054
}

Create Datastore

This method creates a new Datastore in your Tierion account.

POST https://api.tierion.com/v1/datastores

Parameters

Name Description
name The name of the datastore. [Required]
groupName The name of the group of which this datastore is a member.
redirectEnabled A boolean indicating whether or not the custom redirect URL is enabled.
redirectUrl The URL a user will be redirected to when submitting data from an HTML Form. [Required if redirectEnabled = true]
emailNotificationEnabled A boolean indicating whether or not the email notification is enabled.
emailNotificationAddress The recipient email address.
postDataEnabled A boolean indicating whether or not the POST data URL is enabled.
postDataUrl The URL that new record data will be POSTed to when received. [Required if postDataEnabled = true]
postReceiptEnabled A boolean indicating whether or not the POST receipt URL is enabled.
postReceiptUrl The URL that the blockchain receipt data will be POSTed to when generated. [Required if postReceiptEnabled = true]

Request Sample

POST   https://api.tierion.com/v1/datastores
{
  "name": "Employee Records",
  "redirectEnabled": false,
  "emailNotificationEnabled": true,
  "emailNotificationAddress": "mbolton@initrode.net",
  "postDataEnabled": true,
  "postDataUrl": "http://requestb.in/54ahed56h"
}

Response Sample

Status: 201 Created Location: https://api.tierion.com/v1/datastores/153
{
  "id": 153,
  "key": "QyRmiQtEMhyNGGf72c64YA",
  "name": "Employee Records",
  "groupName": "",
  "redirectEnabled": false,
  "redirectUrl": null,
  "emailNotificationEnabled": true,
  "emailNotificationAddress": "mbolton@initrode.net",
  "postDataEnabled": true,
  "postDataUrl": "http://requestb.in/54ahed56h",
  "postReceiptEnabled": false,
  "postReceiptUrl": null,   
  "timestamp": 1438479043
}

Update Datastore

This method will update parameters of an existing Datastore.

PUT https://api.tierion.com/v1/datastores/<id>

Parameters

Only include the parameters you wish to update. All others will remain unchanged.

Name Description
name The name of the datastore.
groupName The name of the group of which this datastore is a member.
redirectEnabled A boolean indicating whether or not the custom redirect URL is enabled.
redirectUrl The URL a user will be redirected to when submitting data from an HTML Form. [Required if redirectEnabled = true]
emailNotificationEnabled A boolean indicating whether or not the email notification is enabled.
emailNotificationAddress The recipient email address.
postDataEnabled A boolean indicating whether or not the POST data URL is enabled.
postDataUrl The URL that new record data will be POSTed to when received. [Required if postDataEnabled = true]
postReceiptEnabled A boolean indicating whether or not the POST receipt URL is enabled.
postReceiptUrl The URL that the blockchain receipt data will be POSTed to when generated. [Required if postReceiptEnabled = true]

Request Sample

PUT   https://api.tierion.com/v1/datastores/153
{
  "groupName": "Important",
  "redirectEnabled": true,
  "redirectUrl": "https://www.initech.net/emp/records.php?t=emprec",
  "emailNotificationEnabled": false,
  "emailNotificationAddress": null,
  "postDataEnabled": false,
  "postDataUrl": null,
  "postReceiptEnabled": true,
  "postReceiptUrl": "http://requestb.in/54Mjdf34d"
}

Response Sample

Status: 200 OK
{
  "id": 153,
  "key": "QyRmiQtEMhyNGGf72c64YA",
  "name": "Employee Records",
  "groupName": "Important",
  "redirectEnabled": true,
  "redirectUrl": "https://www.initech.net/emp/records.php?t=emprec",
  "emailNotificationEnabled": false,
  "emailNotificationAddress": null,
  "postDataEnabled": false,
  "postDataUrl": null,
  "postReceiptEnabled": true,
  "postReceiptUrl": "http://requestb.in/54Mjdf34d",   
  "timestamp": 1438479043
}

Delete Datastore

This method will delete the Datastore. All associated data including the Datastore's records will be deleted as well.

DELETE https://api.tierion.com/v1/datastores/<id>

Request Sample

DELETE   https://api.tierion.com/v1/datastores/153

Response Sample

Status: 200 OK
{
  "id": 153,
  "key": "QyRmiQtEMhyNGGf72c64YA",
  "name": "Employee Records",
  "groupName": "Important",
  "redirectEnabled": true,
  "redirectUrl": "https://www.initech.net/emp/records.php?t=emprec",
  "emailNotificationEnabled": false,
  "emailNotificationAddress": null,
  "postDataEnabled": false,
  "postDataUrl": null,
  "postReceiptEnabled": true,
  "postReceiptUrl": "http://requestb.in/54Mjdf34d",   
  "timestamp": 1438479043
}

Records

Records represent the individual sets of data. Every Record is a member of a Datastore.

Methods

Method Description
Get Records Return a filtered summary of Records from a specific Datastore.
Get Record Return the details of a specific Record.
Create Record Queue a new Record for creation in a Datastore.
Delete Record Delete a Record.

Record Object

Name Description
id A unique identifier for the record within the system.
accountId A unique numeric identifier for the Account associated with this Record.
datastoreId A unique numeric identifier for the Datastore associated with this Record.
status Indiciates the current state of this Record.
  • queued - The Record has been received, but has not yet been processed.
  • unpublished - The Record has been processed, but not yet published to the blockchain.
  • complete - The Record has been processed and the blockchain receipt is available.
data A dynamic collection of key/value pairs representing the custom data received for this Record.
json The JSON string representation of the data received for this Record.
sha256 The SHA256 hash of the JSON string representation of the data received.
timestamp The number of seconds elapsed since epoch when this Record was received.
blockchain_receipt A Blockchain Receipt object for this record, if one exists.
insights An Insights object for this record, if one exists.

Get Records

This method will return a filtered summary of Records from a specific Datastore.

GET https://api.tierion.com/v1/records?datastoreId=<datastoreId>

Parameters

Name Description
datastoreId A unique numeric identifier for the Datastore from which Records are being requested. [Required]
page The page number of the Record results to view. If not specified, page will default to 1.
pageSize The number of Records to include in the Record results, between 1 and 10000. If not specified, pageSize will default to 100.
startDate A timestamp representing the start of the requested date range for the Record results. If not specified, startDate will default to creation date and time of the Datastore.
endDate A timestamp representing the end of the requested date range for the Record results. If not specified, endDate will default to the current date and time.

All API methods express date and time values as Unix timestamps, the number of seconds elapsed since midnight UTC of January 1st, 1970.

Request Sample

GET   https://api.tierion.com/v1/records?datastoreId=95&pageSize=5&page=10&startDate=1430955005&endDate=1444559468

Response Sample

Status: 200 OK
{
  "accountId": 1,
  "datastoreId": 95,
  "page": 10,
  "pageCount": 13,
  "pageSize": 5,
  "recordCount": 64,
  "startDate": 1430955005,
  "endDate": 1444559468,
  "records": [
    {
      "id": "jjhqI0BtdkaM7Tn_5eBJgg",
      "label": "Peter Gibbons",
      "timestamp": 1438462739
    },
    {
      "id": "byQHJEcJu0K_G1r7bJmQMA",
      "label": "Michael Bolton",
      "timestamp": 1438454103
    },
    {
      "id": "MgnsWcX6L0aFeNV6Kgn3eQ",
      "label": "Samir Nagheenanajar",
      "timestamp": 1438450111
    },
    {
      "id": "SQfgE7nqxUa7FT3oP-nPag",
      "label": "Bill Lumbergh",
      "timestamp": 1438450099
    },
    {
      "id": "i2gIt46MLkq3x6hmrtzovg",
      "label": "Tom Smykowski",
      "timestamp": 1438450076
    }
  ]
}

Tierion calculates the label field value automatically based on name data embedded in the Record as defined in the Contacts section. If no name data exists, the id value is used.

Get Record

This method will return the details of a specific Record.

GET https://api.tierion.com/v1/records/<id>

Request Sample

GET   https://api.tierion.com/v1/records/2V5cdzUJOU27DGOZCVkW5g

Response Sample

Status: 200 OK
{
  "id": "2V5cdzUJOU27DGOZCVkW5g",
  "accountId": 1,
  "datastoreId": 683,
  "status": "complete",
  "data": {
    "firstname": "Milton",
    "lastname": "Waddams",
    "emailaddress": "mwaddams@initech.net",
    "companyname": "Initech",
    "employment status": "Not Found",
    "department": "Basement",
    "likes": "Red Swingline Staplers"
  },
  "json": "{\"firstname\":\"Milton\",\"lastname\":\"Waddams\",\"emailaddress\":\"mwaddams@initech.net\",\"companyname\":\"Initech\",\"employment status\":\"Not Found\",\"department\":\"Basement\",\"likes\":\"Red Swingline Staplers\"}",
  "sha256": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2",
  "timestamp": 1468947472,
  "blockchain_receipt": {
    "@context": "https://w3id.org/chainpoint/v2",
    "type": "ChainpointSHA256v2",
    "targetHash": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2",
    "merkleRoot": "51296468ea48ddbcc546abb85b935c73058fd8acdb0b953da6aa1ae966581a7a",
    "proof": [
      {
        "left": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2"
      },
      {
        "left": "cb0dbbedb5ec5363e39be9fc43f56f321e1572cfcf304d26fc67cb6ea2e49faf"
      },
      {
        "right": "cb0dbbedb5ec5363e39be9fc43f56f321e1572cfcf304d26fc67cb6ea2e49faf"
      }
    ],
    "anchors": [
      {
        "type": "BTCOpReturn",
        "sourceId": "f3be82fe1b5d8f18e009cb9a491781289d2e01678311fe2b2e4e84381aafadee"
      }
    ]
  },
  "insights": null
}

Create Record

This method will queue a new Record for creation in a Datastore.

POST https://api.tierion.com/v1/records

The maximum allowed size for a record is 64k. API requests attempting to create a Record above this limit will receive an error result.

Parameters

Name Description
datastoreId A unique numeric identifier for the Datastore associated with this Record. [Required]
Include any other key/value pairs for the Records's data. If you are handling contact related information, we suggest using these field names.

Request Sample

POST   https://api.tierion.com/v1/records
{
  "datastoreId": 683,
  "firstname": "Milton",
  "lastname": "Waddams",
  "emailaddress": "mwaddams@initech.net",
  "companyname": "Initech",
  "employment status": "Not Found",
  "department": "Basement",
  "likes": "Red Swingline Staplers"
}

Response Sample

Status: 200 OK
{
  "id": "2V5cdzUJOU27DGOZCVkW5g",
  "accountId": 1,
  "datastoreId": 683,
  "status": "queued",
  "data": {
    "firstname": "Milton",
    "lastname": "Waddams",
    "emailaddress": "mwaddams@initech.net",
    "companyname": "Initech",
    "employment status": "Not Found",
    "department": "Basement",
    "likes": "Red Swingline Staplers"
  },
  "json": "{\"firstname\":\"Milton\",\"lastname\":\"Waddams\",\"emailaddress\":\"mwaddams@initech.net\",\"companyname\":\"Initech\",\"employment status\":\"Not Found\",\"department\":\"Basement\",\"likes\":\"Red Swingline Staplers\"}",
  "sha256": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2",
  "timestamp": 1468947474
}

Delete Record

This method will delete the Record.

DELETE https://api.tierion.com/v1/records/<id>

Request Sample

DELETE   https://api.tierion.com/v1/records/2V5cdzUJOU27DGOZCVkW5g

Response Sample

Status: 200 OK
{
  "id": "2V5cdzUJOU27DGOZCVkW5g",
  "accountId": 1,
  "datastoreId": 683,
  "status": "complete",
  "data": {
    "firstname": "Milton",
    "lastname": "Waddams",
    "emailaddress": "mwaddams@initech.net",
    "companyname": "Initech",
    "employment status": "Not Found",
    "department": "Basement",
    "likes": "Red Swingline Staplers"
  },
  "json": "{\"firstname\":\"Milton\",\"lastname\":\"Waddams\",\"emailaddress\":\"mwaddams@initech.net\",\"companyname\":\"Initech\",\"employment status\":\"Not Found\",\"department\":\"Basement\",\"likes\":\"Red Swingline Staplers\"}",
  "sha256": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2",
  "timestamp": 1468947472,
  "blockchain_receipt": {
    "@context": "https://w3id.org/chainpoint/v2",
    "type": "ChainpointSHA256v2",
    "targetHash": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2",
    "merkleRoot": "51296468ea48ddbcc546abb85b935c73058fd8acdb0b953da6aa1ae966581a7a",
    "proof": [
      {
        "left": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2"
      },
      {
        "left": "cb0dbbedb5ec5363e39be9fc43f56f321e1572cfcf304d26fc67cb6ea2e49faf"
      },
      {
        "right": "cb0dbbedb5ec5363e39be9fc43f56f321e1572cfcf304d26fc67cb6ea2e49faf"
      }
    ],
    "anchors": [
      {
        "type": "BTCOpReturn",
        "sourceId": "f3be82fe1b5d8f18e009cb9a491781289d2e01678311fe2b2e4e84381aafadee"
      }
    ]
  },
  "insights": null
}

Tools

Tools are used to perform various tasks with Tierion data.

Methods

Method Description
Validate Receipt Validate a receipt's format and confirm existance in the blockchain.

Validate Receipt

This method will validate the format and contents of a blockchain receipt, and will confirm that the merkle root is stored in the blockchain.

POST https://api.tierion.com/v1/validatereceipt

Parameters

Name Description
blockchain_receipt A Blockchain Receipt object to be verified. [Required]

Request Sample

POST   https://api.tierion.com/v1/validatereceipt
{
  "blockchain_receipt": {
    "@context": "https://w3id.org/chainpoint/v2",
    "type": "ChainpointSHA256v2",
    "targetHash": "ea34398af3d67245a8bfd607e886ad319d14b94fa9125ce0a1dd3dde6be5148e",
    "merkleRoot": "2d21167d2f2f73e309d5ac00ab9faaf8b530478c5b64dcd5755511c8a3eccfa3",
    "proof": [
      {
        "left": "f5a1219a1411822736eb68da2bcde1169760a3e7a79262b01d8083d3b2828af2"
      },
      {
        "left": "22c28e5f06104615b3790a3cf64a1844b7e2983889afe026c70cdd8ca9fd41f4"
      },
      {
        "right": "67b7ced55a4db4bb0fbaf2036901888a08ab7d8126556431258017652cf62092"
      }
    ],
    "anchors": [
      {
        "type": "BTCOpReturn",
        "sourceId": "33884d525ca1cc54313fa2f27be4cf3442b35314866851cc7fc5ec3973d80250"
      }
    ]
  },
}

Response Sample

Status: 200 OK
{
  "success": "Receipt is valid."
}