API Documentation

The API is used via HTTPS GET requests to https://api.blrt.com/1/<endpoint>. Your data is attached to the request as part of the query string.

Your public API key must be specified in each request, using the apiKey query variable. Otherwise, all request parameters and data should be placed into the data query variable as an encrypted, URL encoded JSON object. More details will follow.

The final result will be a URL that looks like https://api.blrt.com/1/conv/request?apiKey=hfa97SDU1behdUSYG&data=ufhha78Y....

The data query variable

Your data is always transmitted securely: over HTTPS and encrypted with your private key. It's very important that your private key remains private.

AES256 encryption is to be used as it's strong and easy to implement. You can find a node.js encryption example under Blrt's Runnable profile.

In summary, here are the steps to building the data query variable:

1. Build a JSON object with all of the information you want to send:
   

   {
       expirationTime: "Mon Nov 17 2014 11:37:13 GMT+1100 (EST)",
       name: "My first Blrt",
       requestee: "john@example.com",
       recipients: [
           "mary@example.com",
           "pablo@example.com"
       ]
   }

2. Apply AES256 encryption using your private key.
3. URL encode the encrypted string.
4. That's all, it can now be attached to the query string.

Data requirements

expirationTime

The expirationTime paramater is required in all API requests. It is a timestamp that must be between 0 and 15 minutes into the future. It is required to prevent URL spoofing and hoarding. It does not affect the result of the request.

A valid expirationTime timestamp is anything that can be successfully Date.parse()d with JavaScript:

• "Mon Nov 17 2014 11:48:52 GMT+1100 (EST)"
• 1416185332329
• "2014/11/17 11:48:52"
• "2014/11/17 11:48:52 GMT+1100"

Handling responses and webhook callbacks

All responses are in JSON, and will contain a success parameter. That will equal either true or false. If it failed, then a message paramater will be present describing the error which occurred.

Webhook callbacks will also provide data in JSON, as part of a POST body. Each webhook will contain a endpoint parameter describing which endpoint the callback originated from, allowing you to use the same webhook destination URL for multiple endpoints if you choose.

Otherwise, the contents of the responses and webhook callbacks depends on the endpoint. See the documentation below for details about each endpoint.

Endpoints

/conv/request

Running this endpoint will create a Blrt Request with the provided details (i.e., recipients, media, name) and return a standard Blrt Request link which should be forwarded to users, allowing them to open the Blrt application and respond to the request.

If a user successfully creates a Blrt after following the returned link and you have specified a "Request webhook URL", the webhook will be called with details of the created Blrt and an updated link so you can let users navigate directly to the created Blrt.

An ID is provided to you so you can track the status of the request. The same ID is used when the request is created and responded to.

Input

• requestee
  Optional
  The email address of the user who's intended to create this Blrt. This does not need to be an existing Blrt user. Unlike a standard Blrt request (generated from https://request.blrt.com/), requests generated from the Blrt API will not send an email to the requestee.
  
  You may send an email to the user with the generated link yourself if you deem it appropriate.
• name
  Optional
  The name of the Blrt. This is prefilled in the Blrt creation process. The user can change this value at their own discretion.
• media
  Optional
  An array of URLs to prefill media during Blrt creation. If a website is specified, the user will be navigated to the web capture screen and allowed to scroll about and choose what viewport to capture.
  
  A limit of 1 website and 1 PDF is in place for Blrt Requests. Although there is no limit on the number of images, users will have individual restrictions placed on them based on their account type.
  
  The creating user has the opportunity to modify the media before going into the Blrt canvas. They can remove the prefilled media, add their own, hide pages of a PDF and more.
• recipients
  Optional
  An array of email addresses to prefill recipients once the Blrt is created. The user will need to manually press the Send button and, like the name and media prefills, can modify the values before submitting it.

Example

{
    expirationTime: 1416185332329,
    requestee: "sgt.bilko@example.com",
    name: "Script changes for \"Latest Blockbuster Hit\"",
    media: [
        "www.imdb.com",
        "https://bitcoin.org/bitcoin.pdf"
    ],
    recipients: [
        "margaret@example.com",
        "patrick@example.com"
    ]
}

Returns

{
    success: true,
    url: "https://request.blrt.com/?req=FEB7y82fhId",
    id: "FEB7y82fhId"
}

Use the provided ID to do your own internal tracking. For instance, after your webhook triggers, update your tracked state of the request with this ID to ensure that you don't double up on emails or actions that you trigger in your webhook (if something was to go wrong and the webhook triggers twice).

Webhook callback

{
    endpoint: "/conv/request",
    title: "Script changes for \"Latest Blockbuster Hit\"",
    thumbnail: "http://.../....jpg",
    url: "https://m.blrt.co/conv/Dnda8d2Dy7",
    duration: 42,
    id: "FEB7y82fhId",
    authorName: "Sgt. Bilko Jnr",
    authorEmail: "sqrt-sgt.bilko@example.com"
}

Code links

• Timestamp parsing logic - provided timestamps need to be JavaScript Date.parse()able.
• Node.js HTTPS request encryption and sending guide
• PHP HTTPS request encryption and sending guide
• Java HTTPS request encryption and sending guide
• C# HTTPS request encryption and sending guide
• Python HTTPS request encryption and sending guide