Introduction

The SnapSign API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

API Endpoint:

https://api.gosnapsign.com

HTTP Verbs

The SnapSign API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PUT`	Used to update an existing resource, including partial updates
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

HTTP Status Codes

The SnapSign API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

Status code	Usage
`200 OK`	The request completed successfully.
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s. `Location` header
`204 No Content`	An update to an existing resource has been applied successfully.
`400 Bad Request`	The request was unacceptable, often due to missing a required parameter. The response body will include an error providing further information.
`404 Not Found`	The requested resource did not exist.
`401 Unauthorized`	No valid API key provided.
`403 Forbidden`	User was authenticated correctly, but does not access permission on the requested resource.
`429 Too Many Requests`	Too many requests hit the API too quickly.

200 OK

The request completed successfully.

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s. Location header

204 No Content

An update to an existing resource has been applied successfully.

400 Bad Request

The request was unacceptable, often due to missing a required parameter. The response body will include an error providing further information.

404 Not Found

The requested resource did not exist.

401 Unauthorized

No valid API key provided.

403 Forbidden

User was authenticated correctly, but does not access permission on the requested resource.

429 Too Many Requests

Too many requests hit the API too quickly.

Hypermedia

The SnapSign API uses hypermedia and resources include links to other resources in their responses. Links can be found beneath the links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate.

Authentication

The SnapSign API requires two headers to be included in API requests to authenticate your account. The integration token is generated as part of the integration setup. The user token uniquely identifies the user the API will run under for the duration of the call.

You can manage your API tokens in the Integrations section of SnapSign. Your API tokens carry many privileges, so be sure to keep them secure!

Authentication to the API is performed via custom headers, for example:

curl https://api.gosnapsign.com/documents/{id}    \
 -H "X-SnapSign-Int-App" : [integration token]    \
 -H "X-SnapSign-Authentication" : [user token]

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

The SnapSign API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required field was omitted). See HTTP Status Codes for more information.

Some '4xx' errors that could be handled programmatically include a list of error details that briefly explains the error reported.

Sample Error Response

{
  "message" : "The request is invalid",
  "path" : "/documents/template",
  "status" : 400,
  "errorCount" : 1,
  "details" : [ "If a sender is specified, it must contain an id or email" ]
}

Table 1. Error Response Fields
Path	Type	Description
`message`	`String`	The error message.
`path`	`String`	The path of the request which caused the error.
`status`	`Number`	The status code of the response.
`errorCount`	`Number`	The number of errors.
`details`	`Array`	List of error condition details.

Get Templates

Get a paged list of Templates accessible to the authorized user token

https://api.gosnapsign.com/templates

Sample Request

GET /templates?page=0&size=3 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 2. Fields
Parameter	Description
`page`	The zero-based page index. Optional. Defaults to 0.
`size`	The size of the page to be returned. Optional. Defaults to 20.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1487

{
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.gosnapsign.com/templates?page=0&size=3"
  }, {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/templates?page=0&size=3"
  }, {
    "rel" : "next",
    "href" : "https://api.gosnapsign.com/templates?page=1&size=3"
  }, {
    "rel" : "last",
    "href" : "https://api.gosnapsign.com/templates?page=3&size=3"
  } ],
  "content" : [ {
    "url" : "https://api.gosnapsign.com/templates/123456789",
    "name" : "My Template",
    "message" : "Please review and sign this document",
    "priority" : "LOW",
    "tags" : [ "HR Onboarding" ],
    "participants" : [ {
      "role" : "Employee",
      "action" : "SIGN",
      "order" : 100
    }, {
      "role" : "HR Manager",
      "action" : "APPROVE",
      "order" : 100
    } ],
    "forms" : [ {
      "url" : "https://api.gosnapsign.com/templateforms/1111111",
      "name" : "My Form",
      "links" : [ {
        "rel" : "self",
        "href" : "https://api.gosnapsign.com/templateforms/1111111"
      } ],
      "id" : "1111111",
      "mime_type" : "PDF"
    } ],
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.gosnapsign.com/templates/123456789"
    }, {
      "rel" : "owner",
      "href" : "https://api.gosnapsign.com/users/1001"
    } ],
    "id" : "123456789",
    "owner_id" : "1001",
    "created_date" : 1525366598088
  } ],
  "page" : {
    "size" : 3,
    "totalElements" : 10,
    "totalPages" : 4,
    "number" : 0
  }
}

Table 3. Fields
Path	Type	Description
`links`	`Array`	Pagination links for additional template pages.
`page`	`Object`	Properties which describe the requested page of templates.
`page.size`	`Number`	The size of the page returned.
`page.totalElements`	`Number`	The total number of templates.
`page.totalPages`	`Number`	The total number of template pages.
`page.number`	`Number`	The zero-based page index.
`content`	`Array`	The content of the page.
`content[].id`	`String`	The id of the requested template.
`content[].name`	`String`	The name of the template.
`content[].message`	`String`	The message to convey to participants of the document.
`content[].created_date`	`Number`	The date the document was created. Measured in milliseconds since the Unix epoch.
`content[].tags`	`Array`	List of tags associated with the template.
`content[].participants`	`Array`	The participants. Refer to Participant for more information.
`content[].forms`	`Array`	The forms contained within this template. Refer to Template Summary Form for more information.
`content[].links`	`Array`	The links associated with this request.

Table 4. Links
Relation	Description
`first`	Link to the first template page.
`self`	Link to the requested template page.
`next`	Link to the next template page.
`last`	Link to the last template page.

Get Template

Get a SnapSign template

https://api.gosnapsign.com/templates/{id}

Sample Request

GET /templates/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 5. /templates/{id}
Parameter	Description
`id`	The id of the template.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1448

{
  "url" : "https://api.gosnapsign.com/templates/123456789",
  "name" : "My Template",
  "message" : "Please review and sign this document",
  "priority" : "LOW",
  "tags" : [ "HR Onboarding" ],
  "participants" : [ {
    "role" : "Employee",
    "action" : "SIGN",
    "order" : 100
  }, {
    "role" : "HR Manager",
    "action" : "APPROVE",
    "order" : 100
  } ],
  "forms" : [ {
    "url" : "https://api.gosnapsign.com/templateforms/1111111",
    "name" : "My Form",
    "fields" : [ {
      "id" : "field_1",
      "internalId" : "field-123",
      "label" : "Please Sign Here",
      "page_number" : 0,
      "assignee_role" : "Employee",
      "data_type" : "STRING",
      "source_keys" : [ ],
      "default_value" : null
    }, {
      "id" : "field_2",
      "internalId" : "field-128",
      "label" : "Balance",
      "page_number" : 0,
      "assignee_role" : "Employee",
      "data_type" : "DOUBLE",
      "source_keys" : [ "AccountBalance" ],
      "default_value" : "[AccountBalance]"
    } ],
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.gosnapsign.com/templateforms/1111111"
    } ],
    "id" : "1111111",
    "mime_type" : "PDF"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/templates/123456789"
  }, {
    "rel" : "owner",
    "href" : "https://api.gosnapsign.com/users/1001"
  } ],
  "id" : "123456789",
  "owner_id" : "1001",
  "created_date" : 1525366598088
}

Table 6. Fields
Path	Type	Description
`id`	`String`	The id of the requested template.
`name`	`String`	The name of the template.
`message`	`String`	The message to convey to participants of the template.
`owner_id`	`String`	The id of the owner of the template.
`created_date`	`Number`	The date the template was created. Measured in milliseconds since the Unix epoch.
`tags`	`Array`	The tags of the template.
`priority`	`String`	The priority of the template. The available values are `high`, `regular` and `low`. Optional. If none is specified, `regular` is assumed.
`participants`	`Array`	The participants. Refer to Participant for more information.
`forms`	`Array`	The forms contained within this template. Refer to Template Form for more information.
`links`	`Array`	The links associated with this request.

Table 7. Links
Relation	Description
`self`	Link to the template resource.
`owner`	Link to the owner of the template.

Send Document with Template

Use a pre-existing SnapSign template to initiate a new document

https://api.gosnapsign.com/documents/template

Sample Request

POST /documents/template HTTP/1.1
Content-Type: application/json
Content-Length: 1288
Host: api.gosnapsign.com

{
  "title" : "My Document",
  "message" : "Please review and sign this document",
  "sender" : {
    "url" : "/users/1",
    "email" : "sender@example.com",
    "id" : "1",
    "first_name" : "Alice",
    "last_name" : "Ramey"
  },
  "profile" : "Compliance Department",
  "participants" : [ {
    "id" : "456",
    "email" : "bob@example.com",
    "role" : "Employee",
    "first_name" : "Bob",
    "last_name" : "Simpson",
    "host_id" : "678",
    "host_email" : "host@example.com",
    "message_directive" : "SUBSET",
    "message_config" : {
      "commented" : true,
      "approved" : true,
      "rejected" : true,
      "manual_reminder" : true,
      "resent_link" : true,
      "expired_reminder" : true,
      "expired" : true,
      "deleted" : false,
      "assigned" : true,
      "reassigned" : true,
      "reminder" : true,
      "invited" : true,
      "completed" : true,
      "past_due" : true
    }
  } ],
  "properties" : [ {
    "name" : "foo",
    "value" : "bar"
  } ],
  "external_key" : "MyBusinessKey",
  "template_id" : "123",
  "additional_form_ids" : [ ],
  "apply_forms_to_template_rule" : "",
  "apply_tags_to_form_rule" : "",
  "expiration_date" : 1525366598113,
  "due_date" : 1525366598101,
  "reminder_days" : 3,
  "reminder_recurrence_days" : 4
}

Table 8. Fields
Path	Type	Description	Constraints
title	String	Optional title of the document. If none is specified, the title from the template is used.
message	String	Optional message to convey to participants of the document. If none is specified, the message from the template is used.
profile	String	Optional name of the profile to use when sending this document. If none is specified, the account-wide settings are used.
external_key	String	The business key of an external object to associate to the document, used to lookup relationships to objects in external systems. Optional.
template_id	String	The id of the template to use to initiate the document request.	Must not be null.
participants[].id	String	The id of the participant to map into the template to create the document. Optional. If id is not specified, email is required to uniquely identify the participant or the role must be mapped to a participant alias.
participants[].role	String	The role of the participant to map into the template to create the document.
participants[].email	String	The email of the participant to map into the template to create the document.
participants[].first_name	String	The first name of the participant to map into the template to create the document.
participants[].last_name	String	The last name of the participant to map into the template to create the document.
participants[].host_id	String	The id of the host to map into the template to create the document. Optional. If id is not specified, `host_email` is required to uniquely identify the host of this participant if the role is specified as Sign In Person.
participants[].host_email	String	The email of the host to map into the template to create the document. Optional. If email is not specified, `host_id` is required to uniquely identify the host of this participant if the role is specified as Sign In Person.
participants[].message_directive	String	An optional directive to send `ALL`, `NONE` or a `SUBSET` of messages to this participant. Default is `ALL`. Refer to Participant Message Directive for more information.	Additional licensing is required to configure participant messaging.
participants[].message_config	Object	A configuration object specifying which messages shoud be sent to this participant. This is required if the Message directive is set to `SUBSET`. Refer to Participant Message Config for more information.	Additional licensing is required to configure participant messaging.
properties	Array	List of key/value pairs of properties to apply to the requested document. These properties will map to `#property` formulas in the resulting fields.
properties[].name	String	The name of the property to map into field tags using the `#property` formula.
properties[].value	String	The value of the property to map into field tags. The value will become the label and default value of the field.
additional_form_ids	Array	Optional list of form ids returned from SnapSign Form Upload API to be applied to the template.
apply_forms_to_template_rule	String	Optional rule which specifies how the forms listed in `additional_form_ids` is to be applied to the template. Valid values are `NONE`, `REPLACE_FIRST` and `REPLACE_ALL`. See Merging Forms to Templates for more information.	If a rule is specified, it must be of one of the supported types [NONE, REPLACE_FIRST, REPLACE_ALL].
apply_tags_to_form_rule	String	Optional rule which specifies how the existing tags on the template will be applied to the forms listed in `additional_form_ids`. Valid values are `NONE` and `ALL_PAGES`. See Merging Forms to Templates for more information.	If a rule is specified, it must be of one of the supported types [NONE, ALL_PAGES].
expiration_date	Number	The date the document will expire and no longer be accessible if it is not complete. Measured in milliseconds since the Unix epoch.
due_date	Number	The date the document is due to be completed. Measured in milliseconds since the Unix epoch.
reminder_days	Number	The number of days after an action is assigned on the document to send a reminder if not completed. Use this property instead of `reminder_recurrence_days` to send only one reminder. If none is specified, and a template with a reminder date value is specified, the template’s value will be used.
reminder_recurrence_days	Number	The number of days after an action is assigned on the document to send a recurring reminder if not completed. Use this property instead of `reminder_days` to schedule recurring reminders. If none is specified, and a template with a reminder date value is specified, the template’s value will be used.
sender	Object	The sender. If none is specified, the initiator of the API is assumed to be the sender. Refer to Sender for more information.	If a sender is specified, it must contain an id or email.

Sample Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 653

{
  "sender" : {
    "url" : "https://api.gosnapsign.com/users/1",
    "email" : "sender@example.com",
    "id" : "1",
    "first_name" : "Alice",
    "last_name" : "Ramey"
  },
  "status" : "CREATED",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/123456789"
  }, {
    "rel" : "sender",
    "href" : "https://api.gosnapsign.com/users"
  }, {
    "rel" : "initiator",
    "href" : "https://api.gosnapsign.com/users"
  }, {
    "rel" : "employee",
    "href" : "https://api.gosnapsign.com/users/456"
  } ],
  "document_id" : "123456789",
  "initiator_id" : null,
  "created_date" : null,
  "external_key" : null
}

Table 9. Fields
Path	Type	Description
`document_id`	`String`	The id of the newly created document.
`status`	`String`	The status of the document. For newly initiated documents, the status will be `CREATED`. Refer to Document Status for more information.
`initiator_id`	`Null`	The id of the initiator of the document
`created_date`	`Null`	The date the request was created
`external_key`	`Null`	The business key of an external object to associate to the document, used to lookup relationships to objects in external systems. Optional.
`sender`	`Object`	The sender. Refer to Sender for more information.
`links`	`Array`	The links associated with this document request.

Table 10. Links
Relation	Description
`self`	Link to the created document resource.
`sender`	Link to the sender of the document request.
`initiator`	Link to the initiator of the document request.
`employee`	Link to the user assigned to the `employee` role of the document. The name of the rel is the name of the role in the document.

Document Status

Get the status of any SnapSign document

https://api.gosnapsign.com/documents/status/{id}

Sample Request

GET /documents/status/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 11. /documents/status/{id}
Parameter	Description
`id`	The id of the document.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 250

{
  "status" : "SENT",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/status/123456789"
  }, {
    "rel" : "document",
    "href" : "https://api.gosnapsign.com/documents/123456789"
  } ],
  "id" : "123456789"
}

Table 12. Fields
Path	Type	Description
`id`	`String`	The id of the requested document.
`status`	`String`	The status of the document. Refer to Document Status for more information.
`links`	`Array`	The links associated with this request.

Table 13. Links
Relation	Description
`self`	Link to the document status resource.
`document`	Link to the document resource.

Get Document

Get a SnapSign document

https://api.gosnapsign.com/documents/{id}

Sample Request

GET /documents/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 14. /documents/{id}
Parameter	Description
`id`	The id of the document.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 3742

{
  "url" : "https://api.gosnapsign.com/documents/123456789",
  "title" : "My Document",
  "message" : "Please review and sign this document",
  "sender" : {
    "url" : "https://api.gosnapsign.com/users/1",
    "email" : "sender@example.com",
    "id" : "1",
    "first_name" : "Alice",
    "last_name" : "Ramey"
  },
  "participants" : [ {
    "url" : "https://api.gosnapsign.com/users/456",
    "order" : 100,
    "email" : "bob@example.com",
    "action" : "SIGN",
    "role" : "Employee",
    "hosted" : false,
    "id" : "456",
    "first_name" : "Bob",
    "last_name" : "Simpson",
    "opened_document" : false
  } ],
  "priority" : "HIGH",
  "status" : "COMPLETED",
  "properties" : [ {
    "name" : "foo",
    "value" : "bar"
  } ],
  "forms" : [ {
    "url" : "https://api.gosnapsign.com/forms/1111111",
    "name" : "My Form",
    "fields" : [ {
      "id" : "field_1",
      "internalId" : "field-123",
      "assignee" : "456",
      "label" : "Please Sign Here",
      "value" : "signature-123",
      "page_number" : 0,
      "assignee_role" : null,
      "assignee_url" : "https://api.gosnapsign.com/users/456",
      "data_type" : "STRING",
      "data_value" : "signature-123"
    }, {
      "id" : "field_2",
      "internalId" : "field-456",
      "assignee" : "456",
      "label" : "BirthDate",
      "value" : "2/5/1980",
      "page_number" : 0,
      "assignee_role" : null,
      "assignee_url" : "https://api.gosnapsign.com/users/456",
      "data_type" : "STRING",
      "data_value" : null
    }, {
      "id" : "field_3",
      "internalId" : "field-789",
      "assignee" : "456",
      "label" : "Attach File",
      "value" : "My Attachment.txt",
      "page_number" : 0,
      "assignee_role" : null,
      "assignee_url" : "https://api.gosnapsign.com/users/456",
      "data_type" : "FILE",
      "data_value" : "My Attachment.txt"
    } ],
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.gosnapsign.com/forms/1111111"
    }, {
      "rel" : "download",
      "href" : "https://api.gosnapsign.com/forms/download/1111111"
    }, {
      "rel" : "download-certificate",
      "href" : "https://api.gosnapsign.com/certificates/download/1111111"
    } ],
    "id" : "1111111",
    "mime_type" : "PDF",
    "status" : "COMPLETED"
  } ],
  "attachments" : [ {
    "url" : "https://api.gosnapsign.com/attachments/123456789/2222222",
    "name" : "My Attachment.txt",
    "required" : true,
    "assignee" : "456",
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.gosnapsign.com/attachments/123456789/2222222"
    }, {
      "rel" : "assignee",
      "href" : "https://api.gosnapsign.com/users/456"
    }, {
      "rel" : "download",
      "href" : "https://api.gosnapsign.com/attachments/download/123456789/2222222"
    } ],
    "id" : "2222222",
    "mime_type" : "text/plain",
    "tag_id" : "field-789",
    "added_by_signer" : false,
    "uploaded_date" : 1525366598101
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/123456789"
  }, {
    "rel" : "sender",
    "href" : "https://api.gosnapsign.com/users/1"
  }, {
    "rel" : "initiator",
    "href" : "https://api.gosnapsign.com/users/1001"
  }, {
    "rel" : "template",
    "href" : "https://api.gosnapsign.com/templates/12345Template"
  } ],
  "id" : "123456789",
  "initiator_id" : "1001",
  "template_id" : "12345Template",
  "created_date" : 1525366598088,
  "outstanding_participants" : [ {
    "url" : "https://api.gosnapsign.com/users/456",
    "action" : "SIGN",
    "id" : "456"
  } ],
  "sent_date" : 1525366598099,
  "completed_date" : 1525366598113,
  "expiration_date" : null,
  "due_date" : null,
  "reminder_days" : 0,
  "external_key" : "MyBusinessKey"
}

Table 15. Fields
Path	Type	Description
`id`	`String`	The id of the requested document.
`title`	`String`	The title of the document
`message`	`String`	The message to convey to participants of the document.
`initiator_id`	`String`	The id of the initiator of the document.
`created_date`	`Number`	The date the document was created. Measured in milliseconds since the Unix epoch.
`sent_date`	`Number`	The date the document was sent. Measured in milliseconds since the Unix epoch.
`completed_date`	`Number`	The date the document was completed. Measured in milliseconds since the Unix epoch.
`due_date`	`Null`	The date the document is due to be completed. Measured in milliseconds since the Unix epoch.
`expiration_date`	`Null`	The date the document will expire and no longer be accessible if it is not complete. Measured in milliseconds since the Unix epoch.
`reminder_days`	`Number`	The number of days after an action is assigned on the document to send a reminder if not completed.
`external_key`	`String`	The business key of an external object to associate to the document, used to lookup relationships to objects in external systems. Optional.
`template_id`	`String`	The internal id of the SnapSign Template which originated the document, if applicable. Optional.
`status`	`String`	The status of the document. Refer to Document Status for more information.
`properties`	`Array`	List of key/value pairs of properties to apply to the requested document. These properties will map to `#property` formulas in the resulting fields.
`properties[].name`	`String`	The name of the property to map into field tags using the `#property` formula.
`properties[].value`	`String`	The value of the property to map into field tags. The value will become the label and default value of the field.
`priority`	`String`	The priority of the document. The available values are `high`, `regular` and `low`. Optional. If none is specified, `regular` is assumed.
`sender`	`Object`	The sender. Refer to SenderConstraint for more information.
`participants`	`Array`	The participants. Refer to Participant for more information.
`outstanding_participants`	`Array`	The participants who have yet to interact, Sign or Approve, the document
`forms`	`Array`	The forms contained within this document. Refer to Form for more information.
`attachments`	`Array`	The attachments contained within this document. Refer to Attachment for more information.
`links`	`Array`	The links associated with this request.

Table 16. Links
Relation	Description
`self`	Link to the document resource.
`sender`	Link to the sender of the document.
`initiator`	Link to the initiator of the document.
`template`	Link to the template which originated the document, if applicable.

Get Document Sign Links

Get the SnapSign application links to load into a browser for participants to sign the document. Please note that additional licensing may be required. Only documents which are In Process and are not hosted to sign in person can provide SnapSign application links.

https://api.gosnapsign.com/documents/signlinks/{id}

Sample Request

GET /documents/signlinks/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 17. /documents/signlinks/{id}
Parameter	Description
`id`	The id of the document.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 751

{
  "participants" : [ {
    "url" : "https://app.gosnapsign.com/sign/123456789?u=456",
    "order" : 0,
    "email" : "bob@example.com",
    "action" : "SIGN",
    "role" : "Employee",
    "hosted" : false,
    "id" : "456",
    "first_name" : "Bob",
    "last_name" : "Simpson",
    "opened_document" : false
  }, {
    "url" : "https://app.gosnapsign.com/sign/123456789?u=789",
    "order" : 1,
    "email" : "carl@example.com",
    "action" : "APPROVE",
    "role" : "Manager",
    "hosted" : false,
    "id" : "789",
    "first_name" : "Carl",
    "last_name" : "Rogers",
    "opened_document" : false
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/signlinks/123456789"
  } ],
  "id" : "123456789"
}

Table 18. Fields
Path	Type	Description
`id`	`String`	The id of the requested document.
`participants`	`Array`	List of participants of the document.
`participants[].url`	`String`	The SnapSign Application url to be loaded in a browser in order for the participant to sign the document.
`participants[].email`	`String`	The email of the participant.
`participants[].action`	`String`	The action of the participant in the document. Refer to Actions for more information.
`participants[].role`	`String`	The role of the participant in the document. This is mapped to the document template definition, if applicable. May be null.
`participants[].id`	`String`	The id of the participant in SnapSign.
`participants[].first_name`	`String`	The first name of the participant.
`participants[].last_name`	`String`	The last name of the participant.
`links`	`Array`	The links associated with this request.

Table 19. Links
Relation	Description
`self`	Link to the document status resource.

Send Reminder for Document

Send a reminder for a SnapSign document that is in process

https://api.gosnapsign.com/documents/reminder

Sample Request

POST /documents/reminder HTTP/1.1
Content-Type: application/json
Content-Length: 73
Host: api.gosnapsign.com

{
  "recipients" : [ "bob@example.com" ],
  "document_id" : "123456789"
}

Path	Type	Description	Constraints
document_id	String	The id of the document.	Must not be null.
recipients	Array	Optional list of recipients of the reminder as email addresses. The recipients must be participants of the document. If none is specified, the reminder will be sent to all the participants of the document.

Path

Type

Description

Constraints

document_id

String

The id of the document.

Must not be null.

recipients

Array

Optional list of recipients of the reminder as email addresses. The recipients must be participants of the document. If none is specified, the reminder will be sent to all the participants of the document.

Sample Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 182

{
  "recipients" : [ "bob@example.com" ],
  "links" : [ {
    "rel" : "document",
    "href" : "https://api.gosnapsign.com/documents/123456789"
  } ],
  "document_id" : "123456789"
}

Table 20. Fields
Path	Type	Description
`document_id`	`String`	The id of the document.
`recipients`	`Array`	The list of recipients as email addresses to which the reminder was sent.
`links`	`Array`	The links associated with this reminder request.

Table 21. Links
Relation	Description
`document`	Link to the document for which the reminder was sent.

Reassign the Current Task for a Document

Reassigns the current task for a document. The document must be in process and the current task must be assigned to the authorized API token user. Additional licensing may be required.

https://api.gosnapsign.com/documents/reassign

Sample Request

PUT /documents/reassign HTTP/1.1
Content-Type: application/json
Content-Length: 136
Host: api.gosnapsign.com

{
  "email" : "bob@example.com",
  "name" : "Bob Simpson",
  "action" : "SIGN",
  "document_id" : "123456789",
  "clear_fields" : true
}

Path Type Description Constraints

Path	Type	Description	Constraints
document_id	String	The id of the document.	Must not be null.
name	String	The name of the person to reassign the current task.	Must not be null.
email	String	The email of the person to reassign the current task.	Must not be null.
action	String	The action of the current user to reassign. Optional unless the current user is assigned more than one task on a document. Defaults to `SIGN`.
clear_fields	Boolean	A flag indicating if any filled in fields should be cleared prior to reassignment. Note: Signatures and Initials will always be cleared as part of reassignment. Defaults to `false`.

document_id

String

The id of the document.

Must not be null.

name

String

The name of the person to reassign the current task.

Must not be null.

String

The email of the person to reassign the current task.

Must not be null.

action

String

The action of the current user to reassign. Optional unless the current user is assigned more than one task on a document. Defaults to SIGN.

clear_fields

Boolean

A flag indicating if any filled in fields should be cleared prior to reassignment. Note: Signatures and Initials will always be cleared as part of reassignment. Defaults to false.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 231

{
  "links" : [ {
    "rel" : "document",
    "href" : "https://api.gosnapsign.com/123456789"
  }, {
    "rel" : "assignee",
    "href" : "https://api.gosnapsign.com/users/456"
  } ],
  "document_id" : "123456789",
  "id" : "456"
}

Table 22. Fields
Path	Type	Description
`document_id`	`String`	The id of the document.
`id`	`String`	The id of user to which the current task was assigned.
`links`	`Array`	The links associated with this reassignment request.

Table 23. Links
Relation	Description
`document`	Link to the document which was reassigned.
`assignee`	Link to the user which is now assigned to the current task.

Add or Update Document Properties

Add or updates a document properties. If the property name is found on the document, the property value will be updated. Otherwise, the property will be added to the document. Additional licensing may be required.

https://api.gosnapsign.com/documents/properties

Sample Request

POST /documents/properties HTTP/1.1
Content-Type: application/json
Content-Length: 155
Host: api.gosnapsign.com

{
  "properties" : [ {
    "name" : "foo",
    "value" : "bar"
  }, {
    "name" : "senderName",
    "value" : "Bob"
  } ],
  "document_id" : "123456789"
}

Path	Type	Description	Constraints
document_id	String	The id of the document.	Must not be null.
properties	Array	The properties to update or add on the document.
properties[].name	String	The name of the property.	Must not be null.
properties[].value	String	The value of the property.

Path

Type

Description

Constraints

document_id

String

The id of the document.

Must not be null.

properties

Array

The properties to update or add on the document.

properties[].name

String

The name of the property.

Must not be null.

properties[].value

String

The value of the property.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 304

{
  "properties" : [ {
    "name" : "foo",
    "value" : "bar",
    "action" : "ADDED"
  }, {
    "name" : "senderName",
    "value" : "Bob",
    "action" : "UPDATED"
  } ],
  "links" : [ {
    "rel" : "document",
    "href" : "https://api.gosnapsign.com/123456789"
  } ],
  "document_id" : "123456789"
}

Table 24. Fields
Path	Type	Description
`document_id`	`String`	The id of the document.
`properties`	`Array`	The properties to update or add on the document.
`properties[].name`	`String`	The name of the property.
`properties[].value`	`String`	The value of the property.
`properties[].action`	`String`	A flag indicating if the property was `ADDED` or `UPDATED` on the document.
`links`	`Array`	The links associated with this reassignment request.

Table 25. Links
Relation	Description
`document`	Link to the document which was reassigned.

Delete Document

Delete a SnapSign document

https://api.gosnapsign.com/documents/{id}

Sample Request

DELETE /documents/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 26. /documents/{id}
Parameter	Description
`id`	The id of the document.

Sample Response

A successful deletion will return a response code of 204 - No Content.

HTTP/1.1 204 No Content

Form Create

Prepare SnapSign for a new form you are going to upload

https://api.gosnapsign.com/forms/

Sample Request

POST /forms/upload HTTP/1.1
Content-Type: application/json
Content-Length: 46
Host: api.gosnapsign.com

{
  "name" : "MyForm",
  "mime_type" : "PDF"
}

Table 27. Fields
Path	Type	Description	Constraints
name	String	Name of the form.	Value may not be null or empty.
mime_type	String	The mime type of the form.	Mime Type must not be empty or null, and must be of one of the supported types [PDF, PNG, JPG].

Sample Response

HTTP/1.1 201 Created
Location: https://api.gosnapsign.com/forms/upload/123456789
Content-Type: application/json
Content-Length: 267

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "MyForm",
  "fields" : [ ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "CREATED"
}

Table 28. Headers
Name	Description
`Location`	The url to use to upload the binary data for this newly created form.

Table 29. Fields
Path	Type	Description
`id`	`String`	The id of the newly created form.
`url`	`String`	Resource locator of the newly created form resource.
`status`	`String`	The status of the form. For newly uploaded forms, the status will be `CREATED`. Refer to Form Status for more information.
`name`	`String`	The name of the form.
`mime_type`	`String`	The mime type of the form. Refer to Supported Mime Types for valid values.
`fields`	`Array`	The fields of the form. For a newly create form, this property will be an empty array.
`links`	`Array`	The links associated with this document request.

Table 30. Links
Relation	Description
`self`	Link to the created form resource.

Form Upload

Upload a new form to SnapSign

https://api.gosnapsign.com/forms/{id}

Sample Request

Example http

POST /forms/upload/123456789 HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: api.gosnapsign.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=filename.pdf
Content-Type: application/pdf

some content
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Example curl

curl -X POST -F "file=@SampleForm.pdf;type=application/pdf"   \
 -H "X-SnapSign-Int-App: [integration token]"                 \
 -H "X-SnapSign-Authentication: [user token]"                 \
 -v https://api.gosnapsign.com/forms/upload/{id}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 269

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "My Form",
  "fields" : [ ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "UPLOADED"
}

Table 31. Fields
Path	Type	Description
`id`	`String`	The id of the newly created form.
`url`	`String`	Resource locator of the newly created form resource.
`status`	`String`	The status of the form. After a successful upload of binary data, the status will be `UPLOADED`. Refer to Form Status for more information.
`name`	`String`	The name of the form.
`mime_type`	`String`	The mime type of the form. Refer to Supported Mime Types for valid values.
`fields`	`Array`	The fields of the form. For a newly uploaded form, this property will be an empty array.
`links`	`Array`	The links associated with this document request.

Table 32. Links
Relation	Description
`self`	Link to the created form resource.

Uploading a Form without a MultiPart request

Some client libraries, such as SuiteScript 1.0 from NetSuite, do not support a MultiPart request. In that case, the file can be Base64 encoded and submitted as a string. In order to upload a form in this way, make sure to use the correct content type header of application/x-www-form-urlencoded and pass the encoded string as the file parameter in the request body.

Example Http

POST /forms/upload/123456789 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: 35
Host: api.gosnapsign.com

file=Pz8%2FPz8%2FPz8%2FPz8%2FPz8%3D

Get Form

Get details about a specific form from a SnapSign document

https://api.gosnapsign.com/forms/{id}

Sample Request

GET /forms/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Table 33. /forms/{id}
Parameter	Description
`id`	The id of the form.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1432

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "My Form",
  "fields" : [ {
    "id" : "field_3",
    "internalId" : "field-128",
    "assignee" : "456",
    "label" : "Balance",
    "value" : "15.50",
    "page_number" : 0,
    "assignee_role" : null,
    "assignee_url" : "https://api.gosnapsign.com/users/456",
    "data_type" : "DOUBLE",
    "data_value" : 15.5
  }, {
    "id" : "field_1",
    "internalId" : "field-123",
    "assignee" : "456",
    "label" : "Please Sign Here",
    "value" : "signature-123",
    "page_number" : 0,
    "assignee_role" : null,
    "assignee_url" : "https://api.gosnapsign.com/users/456",
    "data_type" : "STRING",
    "data_value" : "signature-123"
  }, {
    "id" : "field_2",
    "internalId" : "field-789",
    "assignee" : "456",
    "label" : "Attach File",
    "value" : "My Attachment.txt",
    "page_number" : 0,
    "assignee_role" : null,
    "assignee_url" : "https://api.gosnapsign.com/users/456",
    "data_type" : "FILE",
    "data_value" : "My Attachment.txt"
  } ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  }, {
    "rel" : "download",
    "href" : "https://api.gosnapsign.com/forms/download/123456789"
  }, {
    "rel" : "download-certificate",
    "href" : "https://api.gosnapsign.com/certificates/download/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "COMPLETED"
}

Table 34. Fields
Path	Type	Description
`id`	`String`	The id of the form.
`name`	`String`	The name of the form.
`mime_type`	`String`	The mime-type of the form.
`status`	`String`	The status of the form.
`fields`	`Array`	The list of fields associated with this form.
`fields[].id`	`String`	The unique identifier of this field, as determined by the Sender, for addressing during integrations.
`fields[].internalId`	`String`	The unique identifier of this field
`fields[].assignee`	`String`	The id of the participant assigned to the field.
`fields[].assignee_role`	`Null`	The role of the participant assigned to the field, if applicable.
`fields[].assignee_url`	`String`	The url to the participant resource assigned to the field.
`fields[].label`	`String`	The label of the field.
`fields[].data_type`	`String`	The data type of the value of the field. Refer to Field Data Type for more information.
`fields[].value`	`String`	The value of the field.
`fields[].data_value`	`Varies`	The strongly-typed data value of the field.
`fields[].page_number`	`Number`	The page number of the form on which the field resides. Starts with `0` for the first page.
`links`	`Array`	The links associated with this form.

Table 35. Links
Relation	Description
`self`	Link to the form resource.
`download`	Link to download the completed form content as bytes.
`download-certificate`	Link to download the completed form’s certificate as bytes.

Download Form

Download the content of a completed form from a SnapSign document. Please note that additional licensing is required to download In Process forms.

https://api.gosnapsign.com/forms/download/{id}

Sample Request

GET /forms/download/123456789 HTTP/1.1
Accept: application/pdf
Host: api.gosnapsign.com

Table 36. /forms/download/{id}
Parameter	Description
`id`	The id of the form.

Response

This resource is only available once a Document has been completed. With additional licensing, In Process forms are available for download. The response will return an array of bytes of the content of the form.

HTTP/1.1 200 OK
Content-Disposition: attachment; filename=MyForm.pdf
Content-Length: 33
Content-Type: application/pdf
Accept-Ranges: bytes

ZCBlbnZpcm9ubWVudCBhcyBhbiBhZA...

Base 64 Encoded String

The Download Form endpoint can also provide the contents of the PDF as a Base64 Encoded string if the Accept header is set to text/plain. This Accept header should only be used to support legacy systems, since Base64 Encoding will likely increase the body size.

GET /forms/download/123456789 HTTP/1.1
Accept: text/plain
Host: api.gosnapsign.com

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 45

JVBERi0xLjMKJfbk/N8KMSAwIG9iago8PAovVHlwZS...

Merge Form into Template

The SnapSign API provides the ability for automated processes to merge generated forms into an existing template and send it out for signatures. The basic high level steps are as follows:

Using SnapSign UI, create a template with tags in the desired location using a similar form.
Via the API, create the metadata of the form to merge with the template.
Upload the form using the returned location header from the Form Create API.
Wait for the form to be processed.
Call the Send Document API with the new form Id and rules for how to merge the form into the template.
Wait for the new document to be sent.

Each step is discussed in more detail below.

Create a Template

Using the SnapSign UI, log in and create a Template using a similar form. Apply tags to the template which will be merged onto the generated form during the Send Document with Template process. After saving the template, use the Template action menu to view the Template Details. Note the Template ID. This will be used in step 3.

See the User Guide for more information on creating Templates.

Form Creation and Upload

The SnapSign API uses the concept of Resumable Uploads to allow API users to specify both metadata and binary content for a form, such as a PDF. Using the Form Create endpoint, the metadata is stored first and a form Id is generated.

Form Create

Then the HTTP response of the Form Create API contains a Location header with a URL for the binary upload endpoint. It also will contain the generated Form Id and a form status of CREATED.

Sample Request

POST /forms/upload HTTP/1.1
Content-Type: application/json
Content-Length: 46
Host: api.gosnapsign.com

{
  "name" : "MyForm",
  "mime_type" : "PDF"
}

Sample Response

HTTP/1.1 201 Created
Location: https://api.gosnapsign.com/forms/upload/123456789
Content-Type: application/json
Content-Length: 267

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "MyForm",
  "fields" : [ ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "CREATED"
}

Table 37. Sample Headers
Name	Description
`Location`	The url to use to upload the binary data for this newly created form.

Using the provided Location url, call the Form Upload endpoint with a standard multi part request.

Form Upload

Sample Request

POST /forms/upload/123456789 HTTP/1.1
Content-Type: multipart/form-data; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Host: api.gosnapsign.com

--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm
Content-Disposition: form-data; name=file; filename=filename.pdf
Content-Type: application/pdf

some content
--6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm--

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 269

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "My Form",
  "fields" : [ ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "UPLOADED"
}

Note: The authentication tokens must be passed in the headers for both the Form Creation API and the Form Upload API and they must match.

The HTTP response will contain a form status of UPLOADED and will initiate the form processing service.

Form Processing

Once the form is uploaded, it is submitted to SnapSign form processing service. Form processing can include tasks such as virus scan. While the form is being processed, its status will change to PROCESSING. Form processing is an asynchronous process and can take several seconds to complete, depending on file size, number of pages in the form and graphic intensity of the file.

Use the Form endpoint, to retrieve the form status while it is being processed. To void hitting the throttle limit, checking every few seconds is the official recommendation. Once the status is changed to PROCESSED, the form is ready to be merged into a template.

Sample Request

GET /forms/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Sample Response While Processing

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 271

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "My Form",
  "fields" : [ ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "PROCESSING"
}

Sample Response of Processed Form

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 270

{
  "url" : "https://api.gosnapsign.com/forms/123456789",
  "name" : "My Form",
  "fields" : [ ],
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/forms/123456789"
  } ],
  "id" : "123456789",
  "mime_type" : "PDF",
  "status" : "PROCESSED"
}

Send Document

With the Template Id from step 1 and the Form Id from step 2, use the Send Document with Template endpoint to merge the form into the template. Three fields in the Send Document with Template request dictate file merge behavior.

Field Description

Field	Description
`additional_form_ids`	An array of form ids to merge into the template, derived from the form creation and upload endoints above.
`apply_forms_to_template_rule`	A rule indicator of how the form should be merged into the template. Valid values are `NONE`, `REPLACE_FIRST` and `REPLACE_ALL`. Refer to Form To Template Rule for more information.
`apply_tags_to_form_rule`	A rule indicator of how the existing tags on the template will be applied to the forms listed . Valid values are `NONE` and `ALL_PAGES`. Refer to Tags To Form Rule for more information.

additional_form_ids

An array of form ids to merge into the template, derived from the form creation and upload endoints above.

apply_forms_to_template_rule

A rule indicator of how the form should be merged into the template. Valid values are NONE, REPLACE_FIRST and REPLACE_ALL. Refer to Form To Template Rule for more information.

apply_tags_to_form_rule

A rule indicator of how the existing tags on the template will be applied to the forms listed . Valid values are NONE and ALL_PAGES. Refer to Tags To Form Rule for more information.

Sample Request

POST /documents/template HTTP/1.1
Content-Type: application/json
Content-Length: 909
Host: api.gosnapsign.com

{
  "title" : "My Document",
  "message" : "Please review and sign this document",
  "sender" : {
    "url" : "/users/1",
    "email" : "sender@example.com",
    "id" : "1",
    "first_name" : "Alice",
    "last_name" : "Ramey"
  },
  "profile" : null,
  "participants" : [ {
    "id" : "456",
    "email" : "bob@example.com",
    "role" : "Employee",
    "first_name" : "Bob",
    "last_name" : "Simpson",
    "host_id" : null,
    "host_email" : null,
    "message_directive" : null,
    "message_config" : null
  } ],
  "properties" : [ {
    "name" : "foo",
    "value" : "bar"
  } ],
  "external_key" : "MyBusinessKey",
  "template_id" : "Template1234",
  "additional_form_ids" : [ "123456789" ],
  "apply_forms_to_template_rule" : "REPLACE_FIRST",
  "apply_tags_to_form_rule" : "ALL_PAGES",
  "expiration_date" : null,
  "due_date" : null,
  "reminder_days" : null,
  "reminder_recurrence_days" : null
}

Sample Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 647

{
  "sender" : {
    "url" : "https://api.gosnapsign.com/users/1",
    "email" : "sender@example.com",
    "id" : "1",
    "first_name" : "Alice",
    "last_name" : "Ramey"
  },
  "status" : "CREATED",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/567890"
  }, {
    "rel" : "sender",
    "href" : "https://api.gosnapsign.com/users"
  }, {
    "rel" : "initiator",
    "href" : "https://api.gosnapsign.com/users"
  }, {
    "rel" : "employee",
    "href" : "https://api.gosnapsign.com/users/456"
  } ],
  "document_id" : "567890",
  "initiator_id" : null,
  "created_date" : null,
  "external_key" : null
}

Table 38. Form To Template Merge Rule
Directive	Description
`NONE`	Default directive. Do not apply forms to templates. The form Ids specified in `additional_form_ids` will be ignored.
`REPLACE_FIRST`	Replace only the first form in the template with the first form Ids specified in `additional_form_ids`. If additional form Ids are specified, they will be ignored.
`REPLACE_ALL`	Replace all the forms in the template with the specified forms, one for one. That is, the first form Id will replace the first form in the template. The second form Id will replace the second form in the template, etc.

Table 39. Tag to Form Merge Rule
Directive	Description
`NONE`	Default directive. Do not apply copy tags to specified forms.
`ALL_PAGES`	Copy all tags on all pages to the corresponding page of the specified forms.

Document Send Processing

Once the document is sent, it is submitted to SnapSign document processing service. Document processing can include tasks such notifying participants and assigning workflow. While the document is being processed, its status will change to PENDING. Document processing is an asynchronous process and can take several seconds to complete.

Use the Document Status endpoint, to retrieve the document status while it is being processed. To void hitting the throttle limit, checking every few seconds is the official recommendation. Once the status is changed to SENT, the document has on its way to the participants and no further action is required.

Sample Request

GET /documents/status/123456789 HTTP/1.1
Content-Type: application/json
Host: api.gosnapsign.com

Sample Response While Processing

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 253

{
  "status" : "PENDING",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/status/123456789"
  }, {
    "rel" : "document",
    "href" : "https://api.gosnapsign.com/documents/123456789"
  } ],
  "id" : "123456789"
}

Sample Response of Sent Document

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 250

{
  "status" : "SENT",
  "links" : [ {
    "rel" : "self",
    "href" : "https://api.gosnapsign.com/documents/status/123456789"
  }, {
    "rel" : "document",
    "href" : "https://api.gosnapsign.com/documents/123456789"
  } ],
  "id" : "123456789"
}

Additional Information

Webhook Callbacks

SnapSign will POST events back to your application via your configured webhook callback URL.

All document events, across the document lifecycle, are posted to your webhook callback URL. This would include events such as when a document has been signed and is completed.

Webhook Callback Response Format

SnapSign events that are posted to your callback URL will be formatted as a JSON string. SnapSign accepts a response from your callback URL with a content type of application/json.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2079

{
  "id" : "event1234",
  "type" : "document.rejected",
  "data" : {
    "url" : "https://api.gosnapsign.com/documents/123456789",
    "title" : "My Document",
    "message" : "Please review and sign this document",
    "sender" : {
      "url" : "https://api.gosnapsign.com/users/1",
      "email" : "sender@example.com",
      "id" : "1",
      "first_name" : "Alice",
      "last_name" : "Ramey"
    },
    "participants" : [ {
      "url" : "https://api.gosnapsign.com/users/456",
      "order" : 100,
      "email" : "bob@example.com",
      "action" : "SIGN",
      "role" : "Employee",
      "hosted" : false,
      "id" : "456",
      "first_name" : "Bob",
      "last_name" : "Simpson",
      "opened_document" : false
    } ],
    "priority" : "LOW",
    "status" : "REJECTED",
    "properties" : [ {
      "name" : "foo",
      "value" : "bar"
    } ],
    "forms" : [ {
      "url" : "https://api.gosnapsign.com/forms/form-12345",
      "name" : null,
      "fields" : [ ],
      "links" : [ {
        "rel" : "self",
        "href" : "https://api.gosnapsign.com/forms/form-12345"
      } ],
      "id" : "form-12345",
      "mime_type" : null,
      "status" : "CREATED"
    } ],
    "attachments" : [ ],
    "comment" : "Please provide more information.",
    "links" : [ {
      "rel" : "self",
      "href" : "https://api.gosnapsign.com/documents/123456789"
    }, {
      "rel" : "sender",
      "href" : "https://api.gosnapsign.com/users/1"
    }, {
      "rel" : "initiator",
      "href" : "https://api.gosnapsign.com/users/1001"
    }, {
      "rel" : "template",
      "href" : "https://api.gosnapsign.com/templates/12345Template"
    } ],
    "id" : "123456789",
    "initiator_id" : "1001",
    "template_id" : "12345Template",
    "created_date" : 1718713273095,
    "outstanding_participants" : [ ],
    "sent_date" : 1525366598099,
    "completed_date" : 1525366598113,
    "expiration_date" : null,
    "due_date" : null,
    "reminder_days" : 0,
    "external_key" : "MyBusinessKey"
  },
  "created_date" : 1525366598113,
  "api_version" : "2018.1"
}

Table 40. Fields
Path	Type	Description
`id`	`String`	The id of the webhook event.
`type`	`String`	The type of the webhook event.
`api_version`	`String`	The version of the payload of the event.
`created_date`	`Number`	The date the event was created. Measured in milliseconds since the Unix epoch.
`data`	`Object`	The payload data. For document-based events, the payload is a document resource that might be returned from Get Document. Additionally, for `document.rejected` events, the rejecter’s comment will be included in the payload.

Sender

Table 41. Sender Fields
Path	Type	Description
`first_name`	`String`	The first name of the sender.
`last_name`	`String`	The last name of the sender.
`email`	`String`	The email of the sender.
`id`	`String`	The id of the sender.

Participant

Table 42. Participant Fields
Path	Type	Description
`id`	`String`	The id of the participant in SnapSign.
`first_name`	`String`	The first name of the participant.
`last_name`	`String`	The last name of the participant.
`email`	`String`	The email of the participant.
`action`	`String`	The action of the participant in the document. Refer to Actions for more information.
`order`	`Number`	The order of the participant in the interactions with the document. Lower orders go first.
`role`	`String`	The role of the participant in the document. This is mapped to the document template definition, if applicable. May be null.
`opened_document`	`Boolean`	A flag indicating if the participant has opened the document at least once.

Table 43. Participant Actions
Action	Description
`SIGN`	The participant is assigned to fill in fields and sign the document.
`APPROVE`	The participant is assigned to approve or reject the document.
`REVIEW`	The participant is a reviewer of the document.

Table 44. Participant Message Directive
Field	Description
`ALL`	Directs SnapSign to send all application messages to the participant for the lifecycle of the document.
`NONE`	Directs SnapSign to send no application messages to the participant for the lifecycle of the document.
`SUBSET`	Directs SnapSign to send a specific subset of messages to the participant for the lifecycle of the document. If the message directive is set to `SUBSET` then the Participant Message Config object is required.

Table 45. Participant Message Configuration
Path	Type	Description
invited	Boolean	Specifies to send the document invitation. Defaults to `true`.
assigned	Boolean	Specifies to send the document is now assigned. Defaults to `true`.
commented	Boolean	Specifies to send the document commented message. Defaults to `true`.
reassigned	Boolean	Specifies to send the document is reassigned message. Defaults to `true`.
approved	Boolean	Specifies to send the document is approved message. Defaults to `true`.
rejected	Boolean	Specifies to send the document is rejected message. Defaults to `true`.
resent_link	Boolean	Specifies to send the document link message. Defaults to `true`.
deleted	Boolean	Specifies to send the document deleted message. Defaults to `true`.
completed	Boolean	Specifies to send the document completed. Defaults to `true`.
past_due	Boolean	Specifies to send the document is past due message. Defaults to `true`.
expired_reminder	Boolean	Specifies to send the document will expire soon message. Defaults to `true`.
expired	Boolean	Specifies to send the document is expired message. Defaults to `true`.
manual_reminder	Boolean	Specifies to send the document reminder message. Defaults to `true`.
reminder	Boolean	Specifies to send the automated document reminder message. Defaults to `true`.

Template Summary Form

Table 46. Template Summary Form Fields
Path	Type	Description
`id`	`String`	The id of the form.
`name`	`String`	The name of the form.
`mime_type`	`String`	The mime-type of the form.
`links`	`Array`	The links associated with this form.

Template Form

Table 47. Template Form Fields
Path	Type	Description
`id`	`String`	The id of the form.
`name`	`String`	The name of the form.
`mime_type`	`String`	The mime-type of the form.
`fields`	`Array`	The list of fields associated with this form.
`fields[].id`	`String`	The unique identifier of this field, as determined by the Sender, for addressing during integrations.
`fields[].internalId`	`String`	The unique identifier of this field
`fields[].assignee_role`	`String`	The role of the participant assigned to the field, if applicable.
`fields[].label`	`String`	The label of the field.
`fields[].data_type`	`String`	The data type of the value of the field. Refer to Field Data Type for more information.
`fields[].page_number`	`Number`	The page number of the form on which the field resides. Starts with `0` for the first page.
`fields[].source_keys`	`Array`	The internal ids of an external system fields or properties which defines the default formulaic value of this field, if any.
`fields[].default_value`	`String`	The default value of this field.
`links`	`Array`	The links associated with this form.

Attachment

Table 48. Attachment Fields
Path	Type	Description
`id`	`String`	The id of the attachment.
`name`	`String`	The name of the attachment.
`mime_type`	`String`	The mime-type of the attachment.
`required`	`Boolean`	Indicates the attachment is required.
`added_by_signer`	`Boolean`	Indicates the attachment was uploaded by the signer and not requested by the sender.
`assignee`	`String`	The id of the participant assigned to the attachment.
`tag_id`	`String`	The id of the field tag associaed with the attachment.
`uploaded_date`	`Number`	The date the attachment was uploaded.
`links`	`Array`	The links associated with this attachment.

Table 49. Attachment Links
Relation	Description
`self`	Link to the attachment resource.
`assignee`	Link to the assignee of the attachment.
`download`	Link to download the attachment.

Constants

Table 50. Field Data Types
Type	Description
`STRING`	The value of the field is a String.
`LONG`	The value of the field is a number.
`DATE`	The value of the field is a date.
`TIME`	The value of the field is a time of milliseconds from the start of day.
`FILE`	The value of the field is a file attachment.
`DATETIME`	The value of the field is a date plus time.
`BOOLEAN`	The value of the field is a boolean, true or false.
`DOUBLE`	The value of the field is a number with a decimal point.
`CURRENCY`	The value of the field is a currency
`SSN`	The value of the field is a social security number.

Table 51. Document Status
Status code	Usage
`CREATED`	The document has been created and is pending initialization.
`PENDING`	The document is initializing prior to being sent.
`SENT`	The document has been sent and are waiting on signatures from participants.
`PROCESSING`	The document contain all the required signatures from participants and are finalizing.
`COMPLETED`	The document are final and are ready for download and review.
`SUSPENDED`	The document are currently suspended in their processing.
`DELETED`	The document have been deleted by an authenticated user.
`REJECTED`	The document have been rejected by an authenticated user.
`ERROR`	The document is in error and cannot be completed.

Table 52. Supported Form Mime Types
Mime Type	Usage
`PDF`	A binary representing the `application/pdf` content type.
`PNG`	A binary representing the `image/png` content type.
`JPG`	A binary representing the `image/jpeg` content type.

Table 53. Form Status
Status code	Usage
`CREATED`	The form has been created and is pending upload.
`UPLOADED`	The form has been uploaded and has been submitted for processing by SnapSign.
`PROCESSING`	The form is being processed by SnapSign. Processing may include some tasks such as virus scan and conversion for HTML-based presentation.
`PROCESSED`	The form has been processed and is available to be added to a document or a template.
`DRAFT`	The form is being modified by a Sender prior to being sent in a document..
`SENT`	The form has been sent out with a document for signature.
`COMPLETED`	The form has been completed and finalized.
`ERROR`	The form is in error and cannot be completed.