Skip to main content

Blueink OpenAPI Specfication

API docs by Redocly

BlueInk API v2 (2.2.4)

Download OpenAPI specification:Download

Overview

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.

Versioning

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.

HTTPS

The BlueInk API is only accessible via HTTPS.

Authentication

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.

RESTful Requests and Responses

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.

Rate Limits

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].

Pagination

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.

BlueInk Objects and Concepts

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.

Webhooks

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.

Version History

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

Bundles

List Bundles

Returns a paginated list of Bundles in your Account, ordered by created date (from most recent to least recent). Pagination can be controlled via Pagination paramaters (see Overview->Pagination). Querystring filters paramaters can be combined, e.g. /bundles/?search=Gibbons&status__in=se,co&tag=needs-attention. When combining filters, only Bundles matching ALL the filters are returned.

query Parameters
search
string

A search query. Only bundles matching the search will be returned. The following data in the the Bundle is searched:

  • bundle slug
  • bundle label
  • bundle custom_key
  • signer name
  • signer email
  • signer phones

E.g. /bundles/[email protected]

status
string
Enum: "dr" "se" "st" "co" "ca" "ex" "fa"

Limit bundles to those with the specified status.

  • dr: Draft - the Bundle has not yet been sent
  • se: Sent - the Bundle has been sent, but not yet started by any Signers
  • st: Started - at least one Signer has started reviewing the document(s)
  • co: Complete - all Signers have completed reviewing / signing
  • ca: Cancelled - the Bundle was cancelled
  • ex: Expired - the Bundle expired before it was Complete
  • fa: Failed - an error occurred and the Bundle could not be created or completed

E.g. /bundles/?status=co

status__in
string
Enum: "dr" "se" "st" "co" "ca" "ex" "fa"

Limit bundles to those with one of the specified statuses. Statuses should be comma separated. E.g. /bundles/?status=co,se,st

tag
string

Return Bundles that have the given tag. E.g. /bundles/?tag=some-tag

tag__in
string

Return Bundles that have at least one of the given tags. Tags should be comma separated. E.g. /bundles/?tag=some-tag,another-tag

ordering
string
Enum: "created" "sent" "completed_at"

Control the sort order of Bundles. Prefix with "-" to reverse the sort order. By default Bundles are sorted by "-created", ie the Bundle creation date from most to least recent.

created
string <date-time>

Retrieve Bundles created within a specified date range Note: Dates are expressed as YYYY-MM-DD format.

E.g. /bundles/?created_after=2024-10-01&created_before=2024-10-08

sent
string <date-time>

E.g. /bundles/?sent_after=2024-10-01&sent_before=2024-10-08

completed
string <date-time>

E.g. /bundles/?completed_after=2024-10-01&completed_before=2024-10-08

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Bundle

Request Body schema:
label
string

A label to help you identify this Bundle

in_order
boolean
Default: false

If true, Signers are required to sign in order, and a signing message (email or SMS) is sent to a Signer when previous signers have signed.

email_subject
string

A custom email subject that will be included in the email sent to each Signer.

email_message
string

A custom message that will be included in the email sent to each Signers via email. A message set on the individual PacketRequest takes precedence.

sms_message
string

A custom message that will be included in the SMS sent to each Signers. A message set on the individual PacketRequest takes precedence.

requester_name
string

The name of the requester. Defaults to the value configured for the Account (or Team).

requester_email
string <email>

The email address of the requester. Defaults to the value configured for the Account (or Team).

cc_emails
Array of strings <email> [ items <email > ]

An array of email addresses that should be cc'd when the documents are complete

custom_key
string <= 200 characters

An optional, unique custom key you can use to identify and retrieve this Bundle (e.g via search)

team
string <uuid>

A team ID, if teams are activated for your Account and you want to assign this Bundle to a particular team.

is_test
boolean

Set to True if this a test bundle. Test Bundles do not count against any account usage limits and cannot be used to create legally binding eSignatures. This should always be set to true while you App or integration is under development.

status
string
Enum: "" "dr"

Leave blank to send a bundle normally. Set to "dr" to create a draft bundle that is not sent automatically

required
Array of objects (PacketRequest)
required
Array of DocumentRequest (object) or TemplateRequest (object)

Responses

Request samples

Content type
{
  • "label": "string",
  • "in_order": false,
  • "email_subject": "string",
  • "email_message": "string",
  • "sms_message": "string",
  • "requester_name": "string",
  • "requester_email": "[email protected]",
  • "cc_emails": [],
  • "custom_key": "string",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "is_test": true,
  • "status": "",
  • "packets": [
    ],
  • "documents": [
    ]
}

Response samples

Content type
application/json
{
  • "label": "string",
  • "in_order": false,
  • "email_subject": "string",
  • "email_message": "string",
  • "sms_message": "string",
  • "requester_name": "string",
  • "requester_email": "[email protected]",
  • "cc_emails": [],
  • "custom_key": "string",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "is_test": true,
  • "status": "dr",
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "docs_ready": true,
  • "errors": [
    ],
  • "packets": [
    ],
  • "documents": [
    ],
  • "tags": [
    ],
  • "data": [
    ]
}

Retrieve a Bundle

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "in_order": false,
  • "email_subject": "string",
  • "email_message": "string",
  • "sms_message": "string",
  • "requester_name": "string",
  • "requester_email": "[email protected]",
  • "cc_emails": [],
  • "custom_key": "string",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "is_test": true,
  • "status": "dr",
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "docs_ready": true,
  • "errors": [
    ],
  • "packets": [
    ],
  • "documents": [
    ],
  • "tags": [
    ],
  • "data": [
    ]
}

Cancel a Bundle

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "in_order": false,
  • "email_subject": "string",
  • "email_message": "string",
  • "sms_message": "string",
  • "requester_name": "string",
  • "requester_email": "[email protected]",
  • "cc_emails": [],
  • "custom_key": "string",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "is_test": true,
  • "status": "dr",
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "docs_ready": true,
  • "errors": [
    ],
  • "packets": [
    ],
  • "documents": [
    ],
  • "tags": [
    ],
  • "data": [
    ]
}

List Bundle Events

Get a list of Events that are associated with the Bundle

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve Bundle Files

Get downloadable files for a completed Bundle

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Generate Interim Bundle Files

Trigger generation of interim files. The Bundle cannot have a terminal status (Complete, Expired, etc). The files are generated asynchronously. You can poll the /bundles/{bundleSlug}/files/ endpoint with a GET request to retrieve the generated files. Note that the ability to generate interim files is not active for all API-enabled accounts. Check with Blueink support with any questions.

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "string",
  • "errors": [
    ]
}

Retrieve Bundle Data

Get data entered into fields for a completed Bundle

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Tags to a bundle

Add additional tags to a Bundle. No existing tags on the Bundle are removed. The result of this call is that Bundle.tags is the union of the set of previous tags with the set of new tags. Duplicate tags are ignored.

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Request Body schema: application/json
tags
Array of strings (Tags)

An array of tags

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "label": "string",
  • "in_order": false,
  • "email_subject": "string",
  • "email_message": "string",
  • "sms_message": "string",
  • "requester_name": "string",
  • "requester_email": "[email protected]",
  • "cc_emails": [],
  • "custom_key": "string",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "is_test": true,
  • "status": "dr",
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "docs_ready": true,
  • "errors": [
    ],
  • "packets": [
    ],
  • "documents": [
    ],
  • "tags": [
    ],
  • "data": [
    ]
}

Remove Tags from a bundle

Remove tags from a Bundle. If a tag in the request does not exist on the Bundle, it is ignored.

path Parameters
bundleSlug
required
string

The slug that uniquely identifies the Bundle

Request Body schema: application/json
tags
Array of strings (Tags)

An array of tags

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "label": "string",
  • "in_order": false,
  • "email_subject": "string",
  • "email_message": "string",
  • "sms_message": "string",
  • "requester_name": "string",
  • "requester_email": "[email protected]",
  • "cc_emails": [],
  • "custom_key": "string",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "is_test": true,
  • "status": "dr",
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "docs_ready": true,
  • "errors": [
    ],
  • "packets": [
    ],
  • "documents": [
    ],
  • "tags": [
    ],
  • "data": [
    ]
}

Packet

Update a Packet

Update a Packet (aka signer) with a new email, phone number, name or authentication options

The updated packet must still be deliverable. For instance, if you specify a deliver_via value of 'phone', but there was no phone number set in the original PacketRequest, then this request must include a phone as well, or an error will be returned.

You can change a Packet that was originally configured for embedded signing (that is, deliver_via was 'embed') to be delivered via email or SMS. However, no signing notifications or reminders will be automatically sent. You must call /packet/{packetId}/remind/ to send a signing notification email (or SMS).

If this Signer is associated with a Person, the person will be updated as well - the Person name will be changed (if provided) and any new email or phone number will be added.

path Parameters
packetId
required
string

The slug that uniquely identifies the Packet

Request Body schema: application/json
name
string

The name of the signer

email
string <email>

The email address of the signer

phone
string <phone>

The phone number of the signer. Required if SMS Pin authentication is used.

auth_sms
boolean

True if you would like to require SMS pin authentication before a signer can sign the documents in this Bundle

auth_selfie
boolean

True if you would like to require Selfie authentication before a signer can sign the documents in this Bundle

auth_id
boolean

True if you would like to require ID authentication before a signer can sign the documents in this Bundle

deliver_via
string
Enum: "email" "phone"

Note that "embed" is not an option

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "[email protected]",
  • "phone": "string",
  • "auth_sms": true,
  • "auth_selfie": true,
  • "auth_id": true,
  • "deliver_via": "email"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "email": "[email protected]",
  • "phone": "string",
  • "auth_sms": true,
  • "auth_selfie": true,
  • "auth_id": true,
  • "id": "string",
  • "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
  • "status": "ne",
  • "deliver_via": "email",
  • "completed_at": "string",
  • "last_accessed_at": "string",
  • "order": 0
}

Create an Embedded Signing URL

Create a URL which can be used for embedded signing

path Parameters
packetId
required
string

The slug that uniquely identifies the Packet

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "expires": "2019-08-24T14:15:22Z"
}

Send a Reminder

Send a Reminder email or SMS to a Signer. A reminder can only be sent once every hour. The reminder will be sent via the delivery method (email or SMS) and to the email address (or phone number) previously designated for this Packet.

path Parameters
packetId
required
string

The slug that uniquely identifies the Packet

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "email": "[email protected]",
  • "phone": "string",
  • "auth_sms": true,
  • "auth_selfie": true,
  • "auth_id": true,
  • "id": "string",
  • "person_id": "087e858e-473c-4f50-b5b0-c1df6c021550",
  • "status": "ne",
  • "deliver_via": "email",
  • "completed_at": "string",
  • "last_accessed_at": "string",
  • "order": 0
}

Retrieve Packet Certificate of Evidence

Get a link and checksum of the Certificate of Evidence for this Packet

path Parameters
packetId
required
string

The slug that uniquely identifies the Packet

Responses

Response samples

Content type
application/json
{
  • "file_url": "string",
  • "expires": "string",
  • "sha256": "string"
}

Templates

List Document Templates

Responses

Response samples

Content type
application/json
{
  • "is_shared": true,
  • "name": "string",
  • "file_url": "string",
  • "roles": [
    ],
  • "fields": [
    ]
}

Retrieve a Document Template

path Parameters
templateId
required
string <uuid>

The ID that uniquely identifies the Template

Responses

Response samples

Content type
application/json
{
  • "is_shared": true,
  • "name": "string",
  • "file_url": "string",
  • "roles": [
    ],
  • "fields": [
    ]
}

Person

List Persons

query Parameters
search
string

A search query.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Person

Request Body schema: application/json
name
string

The name of the person

metadata
object

Metadata to associate with this person. Metadata can be used in SmartFill to automatically populate documents. See SmartFill documentation for details.

Array of objects (ContactChannel)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_user": true,
  • "channels": [
    ]
}

Retrieve a Person

path Parameters
personId
required
string <uuid>

The ID that uniquely identifies the Person

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_user": true,
  • "channels": [
    ]
}

Update a Person

Update the Person with new data. NOTE that any contact channels that are omitted from this request will be DELETED. If you don't want to replace all data on the Person, you probably want to use PATCH instead.

path Parameters
personId
required
string <uuid>

The ID that uniquely identifies the Person

Request Body schema: application/json
name
string

The name of the person

metadata
object

Metadata to associate with this person. Metadata can be used in SmartFill to automatically populate documents. See SmartFill documentation for details.

Array of objects (ContactChannel)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_user": true,
  • "channels": [
    ]
}

Partially update a Person

Partially update the Person with new data.

To add a new email or phone to the Person, include a ContactChannel in the 'channels' array without an 'id'.

To update an existing ContactChannel associated with the Person, include an 'id'. That existing ContactChannel will be updated with the new email or phone. This will update any live Bundles associated with the Person that are sending to that email (or phone).

If a ContactChannel does not include an 'id', but the email (or phone) matches an existing ContactChannel, then that ContactChannel will not be changed.

path Parameters
personId
required
string <uuid>

The ID that uniquely identifies the Person

Request Body schema: application/json
name
string

The name of the person

metadata
object

Metadata to associate with this person. Metadata can be used in SmartFill to automatically populate documents. See SmartFill documentation for details.

Array of objects (ContactChannel)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "is_user": true,
  • "channels": [
    ]
}

Delete a Person

path Parameters
personId
required
string <uuid>

The ID that uniquely identifies the Person

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "string",
  • "errors": [
    ]
}

Webhook

List Webhooks

query Parameters
enabled
boolean

Only Webhooks matching the selected 'enabled' state will be returned.

E.g. /webhooks/?enabled=true

event_type
string
Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

Only Webhooks matching the selected event_type or event_types will be returned.

E.g. /webhooks/?event_type=bundle_sent E.g. /webhooks/?event_type__in=bundle_error,bundle_cancelled

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Webhook

Request Body schema: application/json
id
string <uuid>
url
string <url>

should be the full URL, including http/https

enabled
boolean
Default: true
json
boolean
Default: true
event_types
Array of strings
Items Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

types of events that will fire the webhook

Array of objects (WebhookExtraHeader)

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Retrieve a Webhook

path Parameters
webhookId
required
string <uuid>

The ID that uniquely identifies the Webhook

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Update a Webhook

Update the Webhook with new data. NOTE that any subscriptions that are omitted from this request will be DELETED. If you don't want to replace all data on the Webhook, you probably want to use PATCH instead.

path Parameters
webhookId
required
string <uuid>

The ID that uniquely identifies the Webhook

Request Body schema: application/json
id
string <uuid>
url
string <url>

should be the full URL, including http/https

enabled
boolean
Default: true
json
boolean
Default: true
event_types
Array of strings
Items Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

types of events that will fire the webhook

Array of objects (WebhookExtraHeader)

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Partially update a Webhook

Partially update the Webhook with new data.

path Parameters
webhookId
required
string <uuid>

The ID that uniquely identifies the Webhook

Request Body schema: application/json
id
string <uuid>
url
string <url>

should be the full URL, including http/https

enabled
boolean
Default: true
json
boolean
Default: true
event_types
Array of strings
Items Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

types of events that will fire the webhook

Array of objects (WebhookExtraHeader)

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "url": "string",
  • "enabled": true,
  • "json": true,
  • "event_types": [
    ],
  • "extra_headers": [
    ]
}

Delete a Webhook

path Parameters
webhookId
required
string <uuid>

The ID that uniquely identifies the Webhook

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "string",
  • "errors": [
    ]
}

Retrieve a WebhookExtraHeader

path Parameters
webhookExtraHeaderId
required
string <uuid>

The ID that uniquely identifies the WebhookExtraHeader

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

WebhookExtraHeader

List WebhookExtraHeaders

query Parameters
webhook
string <uuid>

Only WebhookExtraHeaders matching the selected webhook ID will be returned.

E.g. /webhooks/headers/?webhook=a053644f-e371-4883-ac17-534445993346

event_type
string
Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

Only WebhookExtraHeaders with webhooks matching the selected event_type or event_types will be returned.

E.g. /webhooks/headers/?event_type=bundle_sent E.g. /webhooks/headers/?event_type__in=bundle_error,bundle_cancelled

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a WebhookExtraHeader

Request Body schema: application/json
id
string <uuid>
webhook
string <uuid>
name
string <= 80 characters

must adhere to RFC 7230

value
string <= 240 characters

must adhere to RFC 7230

order
integer
Default: 1

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

Update a WebhookExtraHeader

Update the WebhookExtraHeader with new data

path Parameters
webhookExtraHeaderId
required
string <uuid>

The ID that uniquely identifies the WebhookExtraHeader

Request Body schema: application/json
id
string <uuid>
webhook
string <uuid>
name
string <= 80 characters

must adhere to RFC 7230

value
string <= 240 characters

must adhere to RFC 7230

order
integer
Default: 1

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

Partially update a WebhookExtraHeader

Partially update the WebhookExtraHeader with new data.

path Parameters
webhookExtraHeaderId
required
string <uuid>

The ID that uniquely identifies the WebhookExtraHeader

Request Body schema: application/json
id
string <uuid>
webhook
string <uuid>
name
string <= 80 characters

must adhere to RFC 7230

value
string <= 240 characters

must adhere to RFC 7230

order
integer
Default: 1

Responses

Request samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "webhook": "34cff408-bf77-4bc5-b31b-e3f4b806d7e8",
  • "name": "string",
  • "value": "string",
  • "order": 1
}

Delete a WebhookExtraHeader

path Parameters
webhookExtraHeaderId
required
string <uuid>

The ID that uniquely identifies the WebhookExtraHeader

Responses

Response samples

Content type
application/json
{
  • "code": "authentication_failed",
  • "message": "string",
  • "errors": [
    ]
}

WebhookEvent

List WebhookEvents

query Parameters
webhook
string <uuid>

Only WebhookEvents matching the selected webhook ID will be returned.

E.g. /webhooks/events/?webhook=a053644f-e371-4883-ac17-534445993346

event_type
string
Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

Only WebhookEvents with webhooks matching the selected event_type or event_types will be returned.

E.g. /webhooks/events/?event_type=bundle_sent E.g. /webhooks/events/?event_type__in=bundle_error,bundle_cancelled

status
integer

Only WebhookEvents matching the selected status will be returned.

E.g. /webhooks/events/?status=1 E.g. /webhooks/events/?status__in=0,1,2

success
boolean

Only WebhookEvents matching the selected success status will be returned.

E.g. /webhooks/events/?success=true

date
string <date-time>

Only WebhookEvents occurring between a date range will be returned. Note: Dates are expressed as YYYY-MM-DD format.

E.g. /webhooks/events/?date_after=2022-10-01&date_before=2022-10-31

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List WebhookEvents

query Parameters
webhook
string <uuid>

Only WebhookDeliveries matching the selected webhook ID will be returned.

E.g. /webhooks/deliveries/?webhook=a053644f-e371-4883-ac17-534445993346

webhook_event
string <uuid>

Only WebhookDeliveries matching the selected webhook_event ID will be returned.

E.g. /webhooks/deliveries/?webhook_event=a053644f-e371-4883-ac17-534445993346

event_type
string
Enum: "bundle_sent" "bundle_complete" "bundle_docs_ready" "bundle_error" "bundle_cancelled" "packet_viewed" "packet_complete"

Only WebhookDeliveries with webhooks matching the selected event_type or event_types will be returned.

E.g. /webhooks/deliveries/?event_type=bundle_sent E.g. /webhooks/deliveries/?event_type__in=bundle_error,bundle_cancelled

status
integer

Only WebhookDeliveries matching the selected status will be returned.

E.g. /webhooks/deliveries/?status=1 E.g. /webhooks/deliveries/?status__in=0,1,2

date
string <date-time>

Only WebhookDeliveries occurring between a date range will be returned. Note: Dates are expressed as YYYY-MM-DD format.

E.g. /webhooks/deliveries/?date_after=2022-10-01&date_before=2022-10-31

Responses

Response samples

Content type
application/json
[
  • {
    }
]

WebhookSecret

Get Webhook Shared Secret

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "create_date": "2019-08-24T14:15:22Z"
}

Regenerate Webhook Shared Secret

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "create_date": "2019-08-24T14:15:22Z"
}