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

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

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

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

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.

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.

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%2F

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:

  1. Using SnapSign UI, create a template with tags in the desired location using a similar form.

  2. Via the API, create the metadata of the form to merge with the template.

  3. Upload the form using the returned location header from the Form Create API.

  4. Wait for the form to be processed.

  5. Call the Send Document API with the new form Id and rules for how to merge the form into the template.

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

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" : 1713360727586,
    "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 Constraints

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.

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.