Documentation

Getting Started

Tierion makes it easy to create applications that record any data or business process in the blockchain. We want to build a platform that customers love. Please send us your feedback and suggestions. To get started, you'll need to signup for an account.

Hash API

Tierion’s Hash API lets you anchor data to the blockchain while keeping your data private. This API operates independently from the main Tierion application and the Data API. Use of the Hash API is free up to 3 records per second or 1,000 records per hour.

View Hash API Docs

Data API

The Data API is your primary API for collecting data, and managing Datastores and Records in your account. This API also offers tools to validate Blockchain Receipts.

View Data API Docs

Explorer API

The Explorer API allows you to publish data. Datastores within Tierion can be made publicly accessible through the Explorer API. This API allows you to retrieve this public data as well as the Blockchain Receipt for validating that data.

View Explorer Docs

HTML Forms - Create Record

In addition to using the Data API to create a Record, you also have the option to submit an HTML form directly to Tierion. If your data is coming from a web site, this method is the easiest to implement. If you choose to create Records this way, you can have basic web analytics data appended to the Record using Insights.

Submit your HTML forms directly to the following URL.

POST https://tierion.com/form/submit

The maximum allowed size for a record is 64k. HTML form submissions attempting to create a Record above this limit will fail silently.

Parameters

Name Description
_key The key value of the Datastore in which the new Record will be created. [Required]
_redirecturl After successful Record creation, the client will be redirected to this URL. This value will override the default setting for the Datastore, if one is set. If no redirect URL value is set here or in the Datastore settings, a default Record Created page is displayed. It is highly recommended a redirect URL be used for all HTML form submissions. [Optional]
_nobots This is helpful for reducing common HTML form SPAM. Use this with an input field that is hidden from the user through CSS. Users will not add data to this field, but some automated scripts may do so. If this parameter is present and has a non-empty value, the form submission will appear to succeed, but not be saved. [Optional]
Include any other key/value pairs for the Records's data. If you are handling contact related information, we suggest using these field names.

HTML Form Sample

<form method="post" action="https://tierion.com/form/submit">
    <input name="_key" type="hidden" value="QyRmiQtEMhyNGGf72c64YA">
    <input name="_redirecturl" type="hidden" value="http://tps.net/contact/thankyou">
    <input name="firstname" type="text">
    <input name="lastname" type="text">
    <input name="emailaddress" type="text">
    <input name="companyname" type="text">
    <input name="employment status" type="text">
    <input name="department" type="text">
    <input name="likes" type="text">
    <button type="submit">Submit</button>
</form>

Slingshot

Slingshot automatically sends your data to other applications. You'll find Slingshot under the Extras tab for each Datastore. Slingshot is triggered when a new record is created and/or when a new blockchain receipt is generated.

Parameters

Name Description
tierion_record_id A unique identifier for the record within the system.
blockchain_receipt A Blockchain Receipt object for this record.

New Record

When a new Record is added to a Datastore, the data received will be sent immediately via HTTP POST to the supplied URL. The tierion_record_id will be appended to that data.

New Receipt

When a Record's blockchain receipt is generated, tierion_record_id and blockchain_receipt will be sent via HTTP POST to the supplied URL.

Insights

Insights lets you capture web analytics when you collect data from an HTML form. This is particularly useful when using Tierion to capture leads, event registrations, etc.

Setup

You'll find your Insights tracking file under the Extras tab of each datastore.

  1. Download tierion.insights.min.js
  2. Open the file and change the domain variable for your site.
  3. To track your domain and all subdomains, use the format '.yourdomainname.com'.
  4. To track one subdomain, use the format 'subdomain.yourdomainname.com.'
  5. Add the insights tracking file to every page of your web site.

Example

<script src="tierion.insights.min.js">

Tracking Parameters

Name Description
utmSource The UTM Source parameter used on first page view of the current visit.
utmMedium The UTM Medium parameter used on first page view of the current visit.
utmTerm The UTM Term parameter used on first page view of the current visit.
utmContent The UTM Content parameter used on first page view of the current visit.
utmCampaign The UTM Campaign parameter used on first page view of the current visit.
userAgent The User Agent string of the visitor.
language The language in use by the visitor.
referringUrl The source URL for this visitor.
pageViewCount The number of page views for this visitor during the current visit.
visitCount The number of times this visitor has visited the site.
timeOnSiteSeconds The number of seconds elapsed for the current visit.
firstVisitUtc The date and time of the visitor's first visit to the site in UTC.

Contacts

Tierion has no enforced schema and allows you to submit any fields to your Datastores. If you are collecting contact information, we recommend using the fields defined below. While not required, using these fields lets Tierion improve how your records are displayed in the app and email notifications. Future updates may provide additional benefits to those who use these field names.

Name Data Address Data Phone Data Company Data
salutation emailaddress phone companyname
firstname address daytimephone department
middlename address2 eveningphone title
lastname city homephone
suffix region workphone
fullname postalcode mobilephone
country fax

If a value for fullname is set, Tierion will use that value for display purposes over any other name data that may have been received.

Zapier

Zapier connects Tierion to over five hundred online services such as Salesforce, Mailchimp, Gmail, Slack, Google Sheets, and many others. Collect data with Tierion and send it to other apps, or use Zapier to send data from your other apps to Tierion.

Explore Zapier's App Directory

Blockchain Receipt

Tierion records data in the Bitcoin blockchain in accordance with the Chainpoint standard. Tierion generates a blockchain receipt for each record. This receipt provides irrefutable proof that your data was recorded at a specific time. Each receipt contains the following elements:

Name Description
@context the JSON-LD context for the receipt
type receipt type definition specifying hash method and version
targetHash hash value being anchored to the blockchain
merkleRoot merkle tree root value that is anchored to the blockchain
proof merkle proof establishing link from the targetHash to the merkleRoot
anchors
type anchor type definition specifying anchoring method
sourceId identifier, such as a transaction id, used to locate anchored data

Example

{
  "@context": "https://w3id.org/chainpoint/v2",
  "type": "ChainpointSHA256v2",
  "targetHash": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2",
  "merkleRoot": "51296468ea48ddbcc546abb85b935c73058fd8acdb0b953da6aa1ae966581a7a",
  "proof": [
    {
      "left": "bdf8c9bdf076d6aff0292a1c9448691d2ae283f2ce41b045355e2c8cb8e85ef2"
    },
    {
      "left": "cb0dbbedb5ec5363e39be9fc43f56f321e1572cfcf304d26fc67cb6ea2e49faf"
    },
    {
      "right": "cb0dbbedb5ec5363e39be9fc43f56f321e1572cfcf304d26fc67cb6ea2e49faf"
    }
  ],
  "anchors": [
    {
      "type": "BTCOpReturn",
      "sourceId": "f3be82fe1b5d8f18e009cb9a491781289d2e01678311fe2b2e4e84381aafadee"
    }
  ]
}
Name Description
Header
chainpoint_version version of the Chainpoint standard
hash_type hashing algorithm used to encrypt target data (sha­256)
merkle_root root of the Merkle Tree that is published in the blockchain
tx_id blockchain transaction id
timestamp non­authoritative Unix timestamp of the target
Target
target_hash hash of the target that is being recorded in the blockchain
target_proof Merkle proof used to prove target_hash is part of Merkle tree
target_URI (optional) path to the target
Extra
custom (optional) array of user defined key value pairs

Example

{
  "header": {
    "chainpoint_version": "1.1",
    "hash_type": "SHA-256",
    "merkle_root": "8dbd52c5ff89b70711b06c143520ef4eb295c51040757c7a4ab56303f0f6b68f",
    "tx_id": "77d93bce0f0ff76f1a52424f9c0aeb165990dc37a5e3aaf85031a2f6ab2967d1",
    "timestamp": 1438317621
  },
  "target": {
    "target_hash": "a64f10ca86a880115cc271232dc8577606dc6223cf009a4dd1290cd55b2d6a28",
    "target_uri ": "https://www.someurl.com/target/id",
    "target_proof": [
      {
        "parent": "ee32ac6eb702c289ba2a932e6562b2c45070121cacb26cabdee433a6cf2086cd",
        "left": "a64f10ca86a880115cc271232dc8577606dc6223cf009a4dd1290cd55b2d6a28",
        "right": "f07934733450ba14972b8fbea4c39ac05b0b8e2d8a45ddde9dbe03bb70942b6a"
      },
      {
        "parent": "8dbd52c5ff89b70711b06c143520ef4eb295c51040757c7a4ab56303f0f6b68f",
        "left": "ee32ac6eb702c289ba2a932e6562b2c45070121cacb26cabdee433a6cf2086cd",
        "right": "07084efda9cf5488ef9d4f9ad8bca8521581aaa32331b62aeb2fe3e132e62d1a"
      }
    ]
  },
  "extra": [
    {
      "custom_key_1": "value_1"
    },
    {
      "custom_key_2": "value_2"
    }
  ]
}

Validating Receipts

Receipt validation confirms that a receipt's content is valid and true. The validation process will confirm that:

  • the receipt is a well formatted JSON document

  • all required fields are present

  • the targetHash, merkleRoot, and proof values are valid

  • the merkleRoot value is anchored at the specified location(s)

Tierion provides tools to validate your receipts, both within the application and available as open source components for use in your applications. They include: