BlueInk API v2 (2.2.4)

This document contains the detailed specification for version 2 of the BlueInk eSignature API. If just starting with the BlueInk API, you might want to checkout the Walkthroughs and Guides that supplement this API specification.

The BlueInk API uses semantic versioning. All minor and patch versions of the v2 API should be backwards compatible.

The latest version of the v2.X.X API is available at the path /api/v2/. Old minor and patch versions are not accessible.

The BlueInk API is only accessible via HTTPS.

The BlueInk API uses API keys to authenticate requests. You can view and manage your API keys in the BlueInk Dashboard, in the Apps section.

Be sure to keep your API key secret! An API key identifies your App and allows it to make calls to the BlueInk API on your behalf, including sending documents for eSignature. It should never be exposed publicly in client-side code (e.g. javascript source files that are downloaded to a browser) or committed into source control (e.g. a github repo).

If an API key is ever compromised or exposed publicly, you should immediately delete the compromised API key in the BlueInk Dashboard and generate a new one.

The BlueInk API v2 is RESTful and adheres to the typical meaning of HTTP requests methods:

• GET to retrieve (but not alter) a resource
• POST to create a resource
• PUT to update a resource
• PATCH to perform a partial update on a resource (where not all fields are included in the request)
• DELETE to delete a resource

Responses use HTTP status codes to indicate success and error conditions. The status codes returned by the API, and their meanings, are as follows:

2XX: Success

• 200: A successful request
• 201: A successful request that created a resource
• 204: A successful request that does not contain content

4XX: Client Errors

• 400: The request was bad and cannot be completed. An error object is included in the response body with more details. Typically this means there was a problem with a parameter of the request or the data in the request body. Authentication and authorization errors are handled with other status codes.
• 401: Not authenticated. The request was not authenticated with a valid token
• 403: Forbidden. While the request was authenticated, the API client does not have permission to access the requested resource.
• 404: Not found. The requested resource was not found.
• 405: Method not allowed. The HTTP method is not allowed on the requested resource.
• 409: Conflict. Server is in a conflicted state and cannot handle the request. This response is returned for select API calls (details below). You might also see a 409 status when a signer clicks on a signing link for a Bundle that is complete, or otherwise cannot be signed.
• 429: Too many requests. You have exceeded a rate limit for API requests.

5XX: Server Errors

• 500: Server error. An unexpected error occured in the processing of the request. These responses should not occur in regular use of the API. The content of the request body for these errors is undefined and should not be relied on.
• 503: Service not available. An unexpected error indicating that the request cannot be completed because part of the BlueInk infrastructure required to service the request is not available (or timed out). Typically these should not occur. If your client encounters a 503 error, you can retry the request. The content of the request body for these errors is undefined and should not be relied on.

Note that 401, 403, 429, 500 and 503 responses are not documented individually for each API endpoint. Those response status codes always have the meanings described above.

500 and 503 requests automatically trigger alerts that our engineering team investigates.

Bundle creation requests (e.g a POST to /bundles) are limited to 200 / hour.

Other API requests are limited to 2000 / hour.

If you need higher limits, we are happy to accommodate. Please contact our team at [email protected].

Lists of objects are returned as a flat list - that is, the objects are not wrapped in a container. For example, if you retrieve a list of Bundles, the response content will consist of:

[
    {
        ... First Bundle object ...
    },
    {
        ... Second Bundle object ...
    }
]

Most requests for a list of resources are paginated, typically returning 50 results per page. Pagination is implemented via a Link header. For example:

Link: <https://api.blueink.com/api/v2/bundles?search=Bob&page=5>; rel="next",
 <https://api.blueink.com/api/v2/bundles?search=Bob&page=11>; rel="last",
 <https://api.blueink.com/api/v2/bundles?search=Bob&page=1>; rel="first",
 <https://api.blueink.com/api/v2/bundles?search=Bob&page=3>; rel="prev"

Your client should use the URLs returned in the Link header to navigate through pages of results. However, while not recommended, paginated URLs can be constructed manually. Page numbers are 1-indexed (starting at 1, not 0). The pagination parameter in the querystring is 'page'. Many API endpoints also take a 'per_page' parameter that lets a client control how many results are returned per page. The maximum allowed value of per_page is typically 100.

For example:

https://api.blueink.com/api/v2/bundles?search=Bob&page=3&per_page=20

To make working with pagination easier, API responses with paginated results also include a custom HTTP header: X-BlueInk-Pagination. The format of this header value is like so:

X-BlueInk-Pagination: <current page number>,<total pages count>,<results per page>,<total results count>

For example, if the response was for page 2 out of 4, with 50 results per page and 176 total results, the header would be as follows.

X-BlueInk-Pagination: 2,4,50,176

All reference client libraries include convenience methods to work with paged results.

This section introduces BlueInk terminology and concepts to help you better navigate the BlueInk API.

Bundles

In the BlueInk platform, a Bundle represents one of more documents sent to one or more signers.

When a BlueInk user in the dashboard (not via the API) prepares documents to send to signers, the first step is that the BlueInk service, under the hood, creates a Bundle. The user then adds documents to that Bundle (either templates, or newly uploaded documents), configures signers on the Bundle, adds fields to the documents, etc. All of those are actions on the Bundle. When the Bundle is ready, the user clicks “send” and the BlueInk service then delivers the Bundle to the signers and otherwise manages the document review process.

When creating a new Bundle via the API, all of the configuration of signers, documents, document fields, delivery options, etc, happens in a single REST request.

Once a Bundle is sent (aka “launched”), the actions you can perform on a Bundle via the API are limited. These include:

• Cancelling the Bundle
• Adding or removing Tags from the Bundle
• Retrieving the Bundle to check it’s status,
• Retrieving Documents associated with the Bundle.
• Retrieving the audit events associated with the Bundle
• Retrieving the data entered by signers in the Bundle, including any Attachments uploaded during the signing process (see below)

Documents

The documents associated with a Bundle can either be one-off documents uploaded for the Bundle, or can be reusable Document Templates. A Document uploaded (or specified by URL) in a Bundle Create request needs to have fields associated with it. Those fields can be placed on the document by specifying the width, height and x, y coordinates of the field. See the Document Coordinate system for additional details.

When using a Document Template, that Template must be pre-configured in the BlueInk system. The easiest way to setup a Template is by logging into your BlueInk account and adding a Template. You can then view the API related information for that Template and use that to setup your Bundle Create request in code.

When using a Document Template via the API, you cannot add or remove fields on the template. However, you can populate the Template fields with initial values.

Attachments

Attachments are implemented in BlueInk as Fields on a Document. Treating Attachments as a kind of Field:

• Allows Attachments to be associated with a Document Template, and reused
• Allows Attachments to be required conditionally based on the values of other fields, assigned to multiple signers, etc.

A single Attachment field can have multiple uploaded files associated with it. This enables Signers to, for example, upload an image for each page of a document from their smart phone as the “Attachment”, as opposed to having to combine those images into a single file.

Since Attachments are a kind of Field, they are retrieved like other fields, with a GET call to /bundles/{bundleSlug}/data/. The field data returned for an Attachment looks like:

[
    // ... other fields
    {
        "doc_key": "tmpl-01",
        "field_key": "inp001-O6V3N",
        "label": "An Attachment Field",
        "kind": "att",
        "value": null,
        "attachments": [
            {
                "url": "https://blueink-production.s3.amazonaws.com/media/val/2019/12/some-uploaded-file_H7oL55ryaK.png?AWSAccessKeyId=xyz&Signature=xyz%3D&Expires=1587162674",
                "name": "some-uploaded-file_H7oL55ryaK.png", "size": 15290,
                "num": 1,
                "ext": ".png",
                "is_image": true
            }
        ],
        "filled_by": "manager-1",
        "packet_id": "vMpwKRSHDi"
    },
    // ... more fields
]

Packets

A Packet represents a signer who is associated with a Bundle, along with additional configuration data. The additional configuration held in a Packet includes data like:

• Authentication methods required for the signer (selfie, SMS pin, etc)
• Delivery options for the signer (via email, via SMS or via embedded signing)
• Status: whether the signer has started the signing process, completed it etc.

The signer associated with a Packet is a Person. The Person object lets BlueInk associate multiple Bundles with a single Signer, giving BlueInk some light-weight CRM-like functionality.

Person

A Person represents a person who reviews / signs documents in BlueInk. A Person has a name and one or more “Contact Channels”, which are emails or phone numbers associated with that signer.

When creating a Bundle via the API, you specify who needs to review / sign the documents in the Bundle. Under the hood, BlueInk attempts to intelligently match this signer data to an existing Person in the system. Most of the time, it just works (as long as you use consistent names and emails / phone numbers for your signers). However, if you need more control, you can retrieve the Person ID for a given Person, and use that in your Bundle Create request to make sure the Bundle is associated with the correct Person.

If your App or integration does not care about keeping track of Persons in BlueInk, you can safely ignore this advanced functionality.

With Webhooks, your App / Integration can be notified when certain events occur in your BlueInk API Account. When the event you are interested in occurs, the BlueInk Platform will make an HTTP request to a URL that you specify. The HTTP Request includes information about the event.

Events Available via Webhooks

The events you can be notified about via Webhooks are as follows:

• **Bundle Launched:**​ occurs when a Bundle is created and successfully sent to a signer or signers.
• **Bundle Complete:**​ occurs when all signers have completed reviewing / signing the documents in a Bundle. Note that when this event occurs, the signed documents associated with the Bundle are not necessarily ready to download yet (see Bundle Docs Ready).
• **Bundle Docs Ready:**​ occurs after a Bundle is complete when the final signed documents (and Certificates of Evidence) are generated and ready for download.
• **Bundle Cancelled:**​ occurs when a Bundle is cancelled.
• **Packet Complete:**​ occurs when a signer finishes reviewing / signing documents.
• **Packet Viewed:**​ occurs when a signer opens a signing session, e.g. by clicking on the signing link they receive via email or SMS.

Webhook Payload

The request sent by BlueInk to your webhook URL includes a JSON encoded request body with the following format:

• event_id: a UUID uniquely identifying the event.
• event_type: A string indicating the type of the event that occurred. Possible event types are:
  • bundle_sent
  • bundle_complete
  • bundle_docs_ready
  • bundle_error
  • bundle_cancelled
  • packet_viewed
  • packet_complete
• event_date: the date at which the event occurred, as an ISO8601 formatted string. E.g. 2020-07-01T06:35:40Z.
• account_id: UUID of the account sending the Webhook. This will typically always be your account ID
• payload: an object with additional details about the event.
  • For bundle_* events, it will contain a single field:
    • bundle_id: the unique ID of the Bundle, as a string.
  • For packet_* events, the payload will contain 2 fields:
    • bundle_id: a string with the unique ID of the Bundle.
    • packet_id: a string with the unique ID of the Packet.

Here is an example request body for a Bundle Complete event:

{
    "event_id": "8g847e0b-422f-9c4c-9bc6-d58b1dc6b2f9",
    "event_type": "bundle_complete",
    "event_date": "2020-07-01T06:35:40Z",
    "account_id": "7e0e8v92-2d3f-4b84-bf9a-52b9ddc18621",
    "payload": {
        "bundle_id": "Ti950noXb8"
    }
}

The request body does not include much data describing the objects affected by the event. Your App should use the Bundle ID (and / or Packet ID) provided in the request payload to retrieve the Bundle (or Packet) for additional details.

Setting up Webhooks

You can configure Webhooks via the BlueInk API dashboard. To do so, you will click “Add Webhook” and will specify the URL that should receive HTTP Requests from BlueInk. For a given URL, you can specify one or more event types that should be sent to that URL. In addition, you can specify additional HTTP headers that will be included in the HTTP Request, in case your Webhook receiver needs to do any filtering or processing based on those headers. A common use of extra HTTP headers is to allow ingress through a firewall.

Webhooks cannot be configured via the API at this time.

Receiving Webhooks

Upon receiving a Webhook HTTP Request from BlueInk, your Webhook receiver should return an HTTP Response with a status of 200, 201, 202 or 204 to indicate successful receipt of the webhook. If any other status code is returned, or if no response is received within 10 seconds, the HTTP Request is deemed to have failed.

After an initial failed request, BlueInk will retry the request with exponential backoff, on the following schedule:

• 4 minutes
• 12 minutes
• 36 minutes
• 108 minutes
• 324 minutes

If any of the retry attempts results in a status of 200, 201, 202 or 204, the webhook event is deemed to have been successfully delivered, and no additional delivery attempts are made.

2.0.0 (2020-06-12)

• Adding Webhooks documentation. Removing /apps endpoint.

2.0.0-beta.3

• Modifying available error codes for Error objects

2.0.0-beta.2

• Removing DocumentTemplate.account from responses
• Adding DocumentTemplate.is_shared to responses
• Added support for reading / updating person metadata
• Adding /bundles/{bundleId}/data/ endpoint to retrieve Bundle data

2.0.0-beta

Initial beta release of APIv2