NAV

Scrive Document API

General Information

Version 2.0.0

Schemes

https

Host & base path

scrive.com/api/v2/documents/

Terms of Service

In using this API you agree to be bound by the Scrive Terms of Service, available at http://scrive.com/en/terms

Overview

The Scrive Document API uses HTTPS methods and RESTful endpoints to create, edit, and manage the life-cycle of documents in the Scrive eSign system. JSON is the data interchange format, but we also use query parameters.

The API is accessed through a versioned URL. This allows users to clearly identify which API they are using, and to make it easier to upgrade to any newer versions. It also avoids having to use version codes in HTTP headers.

Any breaking changes to the API will be introduced through a new version number. We aim to keep these changes to a minimum, and when we do so, will support the current API until it is phased out.

Changelog

We will list any changes to the current version of the API here.

Date Details of changes
2016-10-14 Pre-release of Scrive Document API Version 2
2016-10-27 Small improvements to documentation following internal and customer feedback
2016-12-17 New optional no_attachments parameter for the forward API call
2017-01-17 Add JSON fields related to highlighting
2017-01-28 Documentation of removepages API call
2017-03-11 Add dk_nemid (Danish NemID) to authentication_to_view
2017-05-15 Add missing company standard signatory field
2017-06-08 Add required field to signatory attachments, optional attachments are now possible
2017-07-04 Remove a comment about anchoring that was due to a bug, which has now been fixed
2017-08-03 Revamped definitions of signatory fields, it should now be much clearer
Added SignatoryFieldRadiogroup, Scrive now supports radio button fields
Factor out SignatoryFieldStandard into SignatoryFieldEmailMobile to allow for editable_by_signatory property
2017-11-15 Custom validations for the SignatoryFieldCustomField are now supported

Environments & IP Addresses

Production

The main application is available through the scrive.com domain.

The IP addresses that will be used as endpoints to and from our system are:

API Testbed

A testing environment is available through the api-testbed.scrive.com domain.

This environment should be used when developing an integration with the Scrive eSign system.

We usually deploy the latest production environment to our API testbed, but may occasionally update it with newer builds, which may not be as reliable or well tested.

The API testbed uses 54.229.20.170 as its IP address.

API Explorer

An interactive API Explorer is available for both environments:

This is useful way to test API calls and the OAuth workflow.

The implementation is in JavaScript and you can use Firebug or the Google Chrome DevTools to inspect HTTP requests.

Upgrading from Version 1

There is no change to the Document workflow from Version 1 of the API. The main changes in this version, compared to Version 1, are:

The root endpoint for Version 1 was /api/v1, this has changed to /api/v2/documents.

Most of the parameters have had minor name changes to make it easier for newcomers to use. However, the parameters for the /list call have undergone significant structural changes.

The following table summarises the changes in naming of the API calls. For details of the new parameters and JSON data structures, please consult the documentation.

API endpoint in Version 1 (/api/v1) Equivalent API endpoint in Version 2 (/api/v2/documents)
/list /list
/createfromfile /new
/createfromtemplate/$template_id$ /newfromtemplate/{template_id}
/changemainfile/$documentid$ /{document_id}/setfile
/update/$documentid$ /{document_id}/update
/ready/$documentid$ /{document_id}/start
/cancel/$documentid$ /{document_id}/cancel
/get/$documentid$ /{document_id}/get
/delete/$documentid$ /{document_id}/trash
/reallydelete/$documentid$ /{document_id}/delete
/remind/$documentid$ /{document_id}/remind
/setattachments/$documentid$ /{document_id}/setattachments
/downloadmainfile/$documentid$/$any_name$.pdf /{document_id}/files/main/{filename}
/downloadfile/$documentid$/$fileid$/$any_name$.pdf /{document_id}/files/{file_id}/{filename}
/changeauthenticationtoview/$documentid$/$signatorylinkid$ /{document_id}/{signatory_id}/setauthenticationtoview
/changeauthentication/$documentid$/$signatorylinkid$ /{document_id}/{signatory_id}/setauthenticationtosign

Quick Start

To get started using our API it is recommended to first read the Introduction, this will give you an overview of some key concepts in use by the Scrive eSign system.

Once you are familiar with the basic concepts the simplest document workflow can be achieved by:

  1. Creating a new document using api/v2/documents/new (see New Document)
  2. Updating the document with the desired process options and signatory details using api/v2/documents/{document_id}/update (see Update a document)
  3. Start the signing process with api/v2/documents/{document_id}/ready (see Start the signing process)

Introduction

Scrive eSign is a system for signing documents electronically.

Users need to create an account with Scrive to create and send Documents, but recipients do not need to have an account.

Documents in the Scrive eSign system define the parties to the document, including the information these parties parties should fill out, the document workflow, such as delivery and authentication for the parties, and many other features related to the E-signing of documents as provided by Scrive.

The Scrive Document API uses the Document JSON data structure to represent Documents in the Scrive eSign system. These always include an array of parties, which are either signing or non-signing parties to the document, and represent the workflow assigned to that party, and their individual information. These use the Signatory JSON data structure.

We will first talk about the Document JSON, followed by the Signatory JSON. For the reference documentation about these data structures please see the Definitions.

Documents

A core data structure used throughout the API is the Document JSON. The Document JSON is used to create documents, define the workflow for signing and non-signing parties, monitor the progress of the document, etc.

A key property of a document is its status (as defined by DocumentStatus).

Newly created documents have status: "preparation" and can be easily modified. Most changes to the Document at this stage are done using the Document update API call, by passing a Document JSON with values updated as necessary. Not all fields can be updated in this way. For example, the Document’s id is auto-generated and cannot be changed. For details of which fields cannot be updated in this way, look for the readOnly property in the Document Definitions.

Once the document signing process has been started, using the start API call, the status will change to "pending" and relatively few modifications by the author are possible. Making the start API call will also deliver the document to the parties, depending on the delivery methods set (e.g. by email or SMS).

After all signing parties have successfully signed the document, its status will change to "closed", after which it cannot be modified.

A pending document can also be cancelled by the author using the cancel API call, or rejected by a signing party, resulting in its status being "cancelled" or "rejected", respectively.

Any actions performed by parties to a document, such as signing, can only be performed in the web application interface. We will not provide an API for such actions.

The following diagram provides a rough overview of the document lifecycle: Document workflow diagram

Please refer to Document in the Definitions for a detailed description of all the fields available, and their use.

Templates

It is possible to set up template documents to be used with the “new document from template” API call.

Any document in preparation can be made into a template by executing an update call and setting the "template" field to be true. This cannot be reversed once set, and templates cannot direclty be made into documents for signing.

Templates have the same JSON structure as regular documents and can also be updated. In particular, their "id" can be used to create a new document from a template. Updating a template will only affect documents created from a template after the template was updated.

Finally, using the list call, it is possible to list all your available templates by setting the appropriate filters.

Parties

Every Document has an array field named parties. This defines the signing and viewing parties to a document, their details, how the document is to be delivered to them, an extra authentication that must be performed, etc.

It is possible to add an extra party to a Document in preparation using the update call. Simply add an extra empty object (i.e. { }) to the list of existing parties and the Scrive API will return an additional party populated using default values.

Each party has a unique id, which we refer to as the signatory_id. As with Documents, not all fields may be changed using the update call.

For details of this data structure, please refer to Signatory in the Definitions.

Callbacks

The Scrive eSign system can trigger API callbacks when some significant property of a Document changes, as for example, when a signing party signs the Document. You can also trigger callbacks manually using the callback API call.

For a callback to be triggered, either the api_callback_url must be set on the Document, or the Author should have a User callback scheme defined. You will need to contact us to set up a User callback scheme.

The Scrive eSign system will perform an HTTP POST request, with the following POST parameters:

There will generally be two callbacks executed with document_signed_and_sealed set to true. The first will be shortly after all signing parties have signed the document and Scrive has applied a digital signature, and the second will be issued when a keyless signature has been applied to the document. This usually happens between 15-30 days after the original signing date.

We guarantee to make at least one callback when the Document status changes to one of the following values:

We cannot guarantee to make only one callback per status change, and we may trigger callbacks for changes not listed here. Furthermore, a callback does not indicate what changed in a document, it simply tells you the current state of a document. Finally, callbacks will not be triggered for documents that have been deleted.

The Scrive eSign system will look at the HTTP response code returned by the callback URL. If it is not an HTTP 2xx response, then the callback will be retried in increasing intervals, the first after 5 minutes. After 10 failed attempts, we will no longer attempt the callback.

We may modify the specifics of this behaviour without notice.

Authentication

The Scrive Document API supports OAuth 1.0 and personal access credentials based on this.

Where your application needs to perform actions on behalf of Users, the recommended approach is to use the full OAuth workflow.

Personal Access Credentials

You can retrieve personal access credentials for a user account using a special endpoint and supplying their login details.

Using cURL, you can do:

curl -X POST 'https://{server_address}/api/v2/getpersonaltoken' \
  --data-urlencode 'email={user_email}' \
  --data-urlencode 'password={user_password}'

Replacing {server_address}, {user_email} and {user_password} to match your needs.

This will return the personal access tokens as a JSON:

{
  "apitoken" : "987dfsd312sd76sh_123"
, "apisecret" : "c47b87126dsacbhb"
, "accesstoken" : "2d1287dassg22jke_114"
, "accesssecret" : "12876adsdhght665"
}

Then, given the following example personal access credentials:

  • Client credentials identifier: apitoken = 123
  • Client credentials secret: apisecret = abc
  • Token credentials identifier: accesstoken = 456
  • Token credentials secret: accesssecret = cde

The following authorisation header can be used:

Authorization: oauth_signature_method="PLAINTEXT", oauth_consumer_key="123", oauth_token="456", oauth_signature="abc&cde"

Instead of OAuth, clients may access the Scrive API using personal access credentials. A user can create personal access credentials in the Scrive Account Section through the web interface, or using a dedicated API call, as described in the right column.

Only one personal token is available per user. Such credentials can be used instead of OAuth client and token credentials in API calls. The personal access credentials are associated with the user and can be used instead of any other OAuth privileges, they are intended for special cases where OAuth is not a viable option, or for getting started quickly in a sandbox environment.

OAuth

Managing API access is done through a Scrive user account, and each user account may have zero or more client credentials. These client credentials are managed in the Integration settings tab of the user account settings.

These client credentials may be used to request privileges from users. Users, in turn, can approve or deny granting such privileges. They may also remove privileges as they see fit, from the Integration settings tab.

The OAuth authorisation sequence allows you to request privileges from a user and retrieve token credentials. Once these have been approved, you may use the token credentials to make API requests on behalf of the user.

OAuth privileges

The current API version accepts the following privileges names: DOC_CREATE, DOC_CHECK, and DOC_SEND.

Permission levels required for each API call are described on a per call basis.

OAuth and Cookies

As the Scrive eSign web interface uses the Scrive API, all API calls support two modes of authentication: OAuth based, and browser cookie based. If the Authorization header is set, any browser cookies are ignored.

OAuth 1.0 Workflow

OAuth Workflow using cURL

Here we provide some examples using the cURL command.

1. Temporary credentials request using cURL and response:

$ curl 'https://${host}/oauth/temporarycredentials?privileges=DOC_CREATE%2BDOC_SEND' \
  -H 'Authorization: oauth_realm="Scrive",oauth_signature_method="PLAINTEXT",oauth_consumer_key="4d224b89875b39af_2",oauth_signature="f446cae781995b05&aaaaaa",oauth_callback="http://www.mywebsite.com/scrive"'

oauth_token=b0d6be3270a2b3ad_8&oauth_token_secret=dac0ec76e037c01d&oauth_callback_confirmed=true

2. Now redirect the user to:

https://${host}/oauth/authorization?oauth_token=b0d6be3270a2b3ad_8

If the user grants access to your application, they will be redirected to:

http://www.mywebsite.com/scrive?=&oauth_token=b0d6be3270a2b3ad_8&oauth_verifier=6382be3e8fcafd94

3. You should now request for an OAuth token using all the information:

$ curl '${host}/oauth/tokencredentials' \
  -H 'Authorization: oauth_realm="Scrive",oauth_signature_method="PLAINTEXT",oauth_consumer_key="4d224b89875b39af_2",oauth_signature="f446cae781995b05&dac0ec76e037c01d",oauth_token="b0d6be3270a2b3ad_8",oauth_verifier="6382be3e8fcafd94"'

oauth_token=0e870aa5ff434d5a_2&oauth_token_secret=22adb49346ba7674

You should now be able to perform an API call, for example:

curl -X POST '${host}/api/v2/documents/new' \
  -H 'Authorization: oauth_realm="Scrive",oauth_signature_method="PLAINTEXT",oauth_consumer_key="4d224b89875b39af_2",oauth_signature="f446cae781995b05&22adb49346ba7674",oauth_token="0e870aa5ff434d5a_2"'

The OAuth workflow consists of three steps, which we will describe in turn:

  1. Temporary credentials request and response
  2. Authorisation redirect
  3. Token request and response

1. Temporary Credentials

You must first request temporary credentials using the client credentials identifier and secret from your account’s Integration settings tab.

To do so you must issue a GET request to https://${host}/oauth/temporarycredentials?privileges=${privileges} with the following parameters in the authorization header:

${privileges} must be separated by a +, for example "DOC_CREATE+DOC_SEND" (or %2B when URL encoded). You can set ${oauth_callback_url} to what you like, but it must be set. The oauth_signature must be appended with a dummy &aaaaaa at this stage, it will be replaced with other tokens later.

The reponse should include an oauth_token, oauth_token_secret, and oauth_callback_confirmed=true.

2. Authorisation redirect

You must now redirect the User to https://${host}/oauth/authorization?oauth_token=${oauth_token} using the oauth_token from the previous step.

The user will be asked to grant you the requested privileges, displaying your company name.

If they accept, they will be redirected to:

If they reject, the redirection will be to:

Therefore, you should be able to inspect the redirection to the callback URL.

3. Token request

Now you should have the following pieces of information:

We then use oauth_signature_method="PLAINTEXT" and construct a new oauth_signature from the client credentials secret and temporary credentials secret:

Finally, we wrap all of this into the Authorization header to https://${host}/oauth/tokencredentials and get back an oauth_token and oauth_token_secret.

We can now make API calls on behalf of the User by including the finalised tokens in the Authorization header:

Errors

Error responses will contain a JSON response body, structured as follows:

{
  "error_type": "$error_type$"
, "error_message": "$error_message$"
, "http_code": $http_code$
}

For example:

{
  "error_type": "resource_not_found"
, "error_message": "The resource was not found. A document with id $id$ was not found."
, "http_code": 404
}

Scrive uses HTTP status codes to indicate the success or failure of an API request.

HTTP response codes in the 2xx range indicate that the API call completed successfully. The 4xx range indicates an error, either due to missing, incomplete, or not applicable information (e.g. missing or invalid parameters, invalid authorisation, etc.).

When a request is well formed, but does not satisfy necessary conditions, then we will return a 409 code. For example, when trying to start the signing process for a document that has already been signed.

Codes in the 5xx range suggest an error with Scrive’s eSign system, they could also indicate planned system downtime, and will be rare.

The following table of error responses applies to all API calls, there may be additional errors which are specific to the respective API calls, but will follow the same structure.

HTTP code Reason Error Type and Message
400 Bad Request Obligatory parameters were missing

request_parameters_missing

The parameter(s) $bad_parameters$ were missing. Please refer to our API documentation.

400 Bad Request Parameter(s) could not be parsed

request_parameters_parse_error

The parameter(s) $bad_parameters$ could not be parsed. Please refer to our API documentation.

Some debugging information may also be present, detailing why parsing failed.

400 Bad Request Parameter(s) were present and could be parsed, but were not valid.

request_parameters_invalid

Error message should detail what is wrong with the parameter(s).

401 Unauthorised No or invalid access credentials

invalid_authorisation

No valid access credentials were provided. Please refer to our API documentation.

403 Forbidden Insufficient access privileges for request

insufficient_privileges

The access credentials provided do not have sufficient privileges for this request.

403 Forbidden User doesn’t have permission for a document action or retrieval

document_action_forbidden

You do not have permission to perform this action on the document.

404 Not Found Non existent API endpoint

endpoint_not_found

The endpoint was not found. See our website for API documentation.

404 Not Found The endpoint exists but the resource was not found.

resource_not_found

The resource was not found.

We will try to give additional information about what is missing.

409 Conflict The document’s object_version does not match

document_object_version_mismatch

The document has a different object_version to the one provided and so the request was not processed.

500 Server Error Other unexpected server error

server_error

We encountered an unexpected error. Please contact Scrive support and include as much details about what caused the error, including the document_id and any other details.

We recommend writing integration code that handles the possibility of the Scrive eSign system returning errors.

List of API Calls

Prepare

POST /api/v2/documents/new

POST /api/v2/documents/newfromtemplate/{document_id}

POST /api/v2/documents/{document_id}/clone

POST /api/v2/documents/{document_id}/update

POST /api/v2/documents/{document_id}/setfile

POST /api/v2/documents/{document_id}/setattachments

POST /api/v2/documents/{document_id}/removepages

POST /api/v2/documents/{document_id}/start

Get

GET /api/v2/documents/{document_id}/get

GET /api/v2/documents/{short_document_id}/getbyshortid

GET /api/v2/documents/list

GET /api/v2/documents/{document_id}/files/main/{filename}

GET /api/v2/documents/{document_id}/files/{file_id}/{filename}

GET /api/v2/documents/{document_id}/history

POST /api/v2/documents/{document_id}/callback

Modify

POST /api/v2/documents/{document_id}/remind

POST /api/v2/documents/{document_id}/prolong

POST /api/v2/documents/{document_id}/cancel

POST /api/v2/documents/{document_id}/trash

POST /api/v2/documents/{document_id}/delete

POST /api/v2/documents/{document_id}/forward

POST /api/v2/documents/{document_id}/setautoreminder

POST /api/v2/documents/{document_id}/restart

POST /api/v2/documents/{document_id}/{signatory_id}/setauthenticationtoview

POST /api/v2/documents/{document_id}/{signatory_id}/setauthenticationtosign

Prepare

New document

POST /api/v2/documents/new

Create a new document with the given PDF (if any) as the main file. The new document will have state Preparation, and will not be a template.

If no PDF is provided, you can set one using the {document_id}/setfile API call.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

file
optional

default: No file

The PDF to use for the document.

If supplied, the document’s title will be set to the filename (with the extensions removed). Otherwise a default document title will be set, depending on the user language settings.

file
application/pdf

formData

saved
optional

default: true

Whether the document should start out as being “saved” (i.e. appear in the E-archive).

The document can be “saved” later, by setting the “saved” field to true via an update call. All API operations are applied immediately, the “saved” flag simply represents visibility in the E-archive.

boolean

formData

Responses

Code Description
201

The document metadata as a JSON.

400

The parameter file could not be parsed.

New document from Template

POST /api/v2/documents/newfromtemplate/{document_id}

Create a new document from a template, given the document ID for a document that is a template.

The new document will have state Preparation and will not be a template, and the signing process can thus be carried out.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
201

The document metadata as a JSON.

409

The document is not a template.

Clone a document

POST /api/v2/documents/{document_id}/clone

Clone an existing document, returning a new document in Preparation.

You can only clone documents for which you are the author, the new document will use the current author details for the author signatory fields.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
201

The document metadata as a JSON.

Update a document

POST /api/v2/documents/{document_id}/update

Update the metadata for a document in preparation.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

document
required

The document metadata

Must be of type Document, see Definitions.

Can be a subset of the JSON structure, for example it is possible to just update the title of a document with {"title": "New title"}.

Not all fields can be set this way, please refer to the definitions for details, those marked as read-only cannot be modified using this API call.

string
application/json

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

The document status should be Preparation.

Set the Main File

POST /api/v2/documents/{document_id}/setfile

Set or replace the main PDF file for a document in Preparation.

If the file parameter is blank, the main file for the document will be removed (if any).

A note about anchors: Signatory field placements with anchors are only recalculated if a main file was already set on the document, as it requires the relative placement in original file to recalculate placements for the new file. Contact us to learn more about anchors, and discuss advanced features that we may be able to offer you.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

file
optional

If provided, the PDF will be set as the main file for the document.

If not provided, the current main file for the document will be removed.

file
application/pdf

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

400

The parameter file could not be parsed.

409

The document status should be Preparation.

Set Author Attachments

POST /api/v2/documents/{document_id}/setattachments

Example

As this call can be a little tricky to understand, we provide a concrete example.

Suppose we wanted to set two author attachments:

  1. terms_and_conditions.pdf
  2. proof_of_purchase.pdf

To do this we would need to include the two files as form data in our request. We are then free to chose names for the form data elements, so suppose we chose toc_file for the first, and proof_file for the second.

In this case the attachments JSON would need to resemble:

[
  {
    "name": "Terms and Conditions",
    "required": true,
    "add_to_sealed_file": false,
    "file_param": "toc_file"
  },
  {
    "name": "Proof of purchase",
    "required": false,
    "add_to_sealed_file": true,
    "file_param": "proof_file"
  }
]

And we would include our files as named form elements.

Set or remove author attachments for the document.

Replaces any existing attachments, so all attachments must be set by any use of this call.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

attachments
required

List of author attachments.

The list provided will replace any existing attachments (if any). Therefore, to add an attachment to an existing list, you would need to first fetch the existing attachments file_id and use it for this call.

Note: The JSON structure two variants, one with file_param and the other with file_id.

  • file_param refers to a named parameter that must also be included in this API call. This is the suggested way to include files.

  • file_id refers to a file in the Scrive system. You must have the rights to access the file_id to use it.

Must be of type Author Attachments.

string
application/json

formData

{attachment_name}
optional

The named file parameters

Any file_param in the attachments JSON must be supplied as named file parameters.

If converting from API version 1, it is convenient to name these parameters attachment_1, attachment_2, etc, and reference them as such in the attachments JSON. Although it is possible to use any HTTP compatible naming scheme.

file
application/pdf

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

The document status should be Preparation.

Remove pages

POST /api/v2/documents/{document_id}/removepages

Remove some pages from main PDF file of a document in Preparation.

Checkboxes and signature areas that are placed on pages to be removed will be removed from their respective signatory. For standard and text fields, only the placements that are on the pages to be removed will be removed, the signatory field will still exist. As a consequence of removing pages, the page property of any placements may change to account for any removed pages.

This operation will update the document’s file with a new one, that will have the requested pages removed from its current main file.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

pages
required

List of pages to be removed. Pages are indexed from 1.

To remove the first and last page, when the main file has 4 pages, set this param to [1,4].

array
[integer]

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

400

Parameter pages could not be parsed or given pages can’t be removed from PDF:

  • Parameter pages could not be parsed.
  • Pages parameter can’t have more then 100 positions.
  • Pages parameter can’t be an empty list.
  • Pages parameter can’t contain duplicates.
  • Some page indexes lower then 1 or higher then number of pages.
  • Can’t remove all pages from PDF.
409

document_state_error with error messages:

  • The document status should be Preparation.
  • Document does not have a main file.

Start the signing process

POST /api/v2/documents/{document_id}/start

Start the signing process for a document in preparation.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

document_state_error with error messages:

  • The document state must be ‘Preparation’.
  • Document is a template, templates can not be started.
  • Document must have a file before it can be started.
  • The document has missing or invalid data. Some information about what is missing or invalid in the document is given.

Get

Get a document

GET /api/v2/documents/{document_id}/get

Get the JSON metadata for a given document_id.

OAuth Privileges required: DOC_CHECK

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

Responses

Code Description
200

The document metadata as a JSON.

Get by short ID

GET /api/v2/documents/{short_document_id}/getbyshortid

Get the Document JSON metadata using a short Document ID.

This can only be used for documents created or modified within the last 24 hours. It can only be used for documents that are pending. You can only get documents that you have access to.

OAuth Privileges required: DOC_CHECK

Parameters

Parameter Description Type In

short_document_id
required

Last 6 digits of a regular Document ID. Must be a pending document created or modified within the last 24 hours.

integer
int64

path

Responses

Code Description
200

The document metadata as a JSON.

400

The parameter short_document_id had the following problems: was greater than 6 digits

404

The resource was not found. A document matching short id short_document_id was not found

List documents

GET /api/v2/documents/list

Fetch a list of documents, with filtering and sorting options.

OAuth Privileges required: DOC_CHECK

Parameters

Parameter Description Type In

offset
optional

default: 0

Starting offset for documents to return.

If offset is larger than the total number of matching documents, an empty list is returned.

integer
int32

query

max
optional

default: 100

Maximum number of documents to return.

Server may cap to a lower value.

Default value may change without notice.

integer
int32

query

filter
optional

default: []

List of filtering options.

You can supply a list of filtering options to apply. Only documents that match all filters will be returned. Therefore, it is easy to apply a set of filters that will return no documents.

If not supplied, the default is not to apply any filter, i.e. [].

Must be of type List Filter, for example:

[ { "filter_by":"status", "statuses": ["preparation","pending"] } ]

string
application/json

query

sorting
optional

default: [ { "sort_by":"mtime", "order":"descending" } ]

List of sorting options.

You can supply a list of sorting options, which will be applied to list of documents in the order you provided.

If not supplied, the default is [ { "sort_by":"mtime", "order":"descending" } ], i.e., sort by modification time, newest first.

Must be of type List Sorting.

string
application/json

query

Responses

Code Description
200

A JSON object containing the total number of matching documents, and an array of documents.

The total_matching value is capped at 1,000 + offset. Therefore, further API calls will be needed with a higher offset if the total_matching is 1,000.

Get the main file

GET /api/v2/documents/{document_id}/files/main/{filename}

Get the main PDF file for a document.

The filename parameter in the URL can be set to any valid file name. This allows you to download the file with user-specified file name.

OAuth Privileges required: DOC_CHECK

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

Responses

Code Description
200

The PDF file.

503

Error message: The sealed PDF for the document is not ready yet, please wait and try again.

This happens immediately after all signatories have signed (i.e. Document status is closed), as Scrive eSign is preparing the finalised PDF. It should not take more than ~10 seconds for the finalised PDF to be available.

GET /api/v2/documents/{document_id}/files/{file_id}/{filename}

Get a file related to a document.

This can be used to get author or signatory attachments by looking up their respective file_id the Document JSON.

The filename parameter in the URL can be set to any valid file name. This allows you to download the file with user-specified file name.

OAuth Privileges required: DOC_CHECK

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

file_id
required

Unique identifier for a file available via Scrive.

integer
int64

path

Responses

Code Description
200

The file

Usually an image (JPG, PNG) or PDF, but this may change. Content-Type header will be set according to the file type.

Get the Document History

GET /api/v2/documents/{document_id}/history

Get the document history to display to the user.

Default language for the document history text is the one set for the user making the API call. This can optionally be overridden.

OAuth Privileges required: DOC_CHECK

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

lang
optional

default: User language

The language used to display the document history.

Defaults to the language of the User making the API call.

Has to be a supported language code. Languages may be added or removed without notice.

string

query

Responses

Code Description
200

The list of history items for this document.

Will be in reverse-chronological order and an array of History Items.

Trigger an API callback

POST /api/v2/documents/{document_id}/callback

Explicitly trigger an extra API callback to the URL set for the document. If one is set, no effect otherwise.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
202

A callback will be triggered for the document if a User or Document callback URL was set.

409

Can not send callbacks for documents in Preparation.

Modify

Remind signatories

POST /api/v2/documents/{document_id}/remind

Send a reminder invitation message to all signatories that have not yet signed.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
202

The call succeeded, reminders have been queued and will be sent to all signatories that have not yet signed.

409

The document status should be Pending.

Prolong a document

POST /api/v2/documents/{document_id}/prolong

Prolong a document that has timed out.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

days
required

Number of days to prolong the document by.

integer

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

400

The days parameter must be a number between 1 and 90.

409

The document has not timed out. Only timed out documents can be prolonged.

Cancel a pending document

POST /api/v2/documents/{document_id}/cancel

Cancel a pending document.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

The document state is not Pending.

Move a document to Trash

POST /api/v2/documents/{document_id}/trash

Note: In API Version 2 delete and trash behave differently to Version 1.

Move a document to Trash.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

Pending documents can not be trashed or deleted.

Delete a document

POST /api/v2/documents/{document_id}/delete

Note: In API Version 2 delete and trash behave differently to Version 1.

Delete a document that is in Trash.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

Pending documents can not be trashed or deleted.

Forward a document

POST /api/v2/documents/{document_id}/forward

Forward a signed document to a third party.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

email
required

The email address to forward the document to.

string

formData

no_content
optional

default: true

When set to true only the signed document will be forwarded, with no other email content. Otherwise a template email content is used, with the document attached.

boolean

formData

no_attachments
optional

default: false

When set to true, only the main file will be included as email attachments. Any attachments not merged with the main file will not be sent.

boolean

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
202

The call succeeded, an email to the given address has been queued.

409

The document status should be Closed.

Set an auto-reminder

POST /api/v2/documents/{document_id}/setautoreminder

Set the number of days in which to send an automatic invitation reminder message to the signatories that have not yet signed by that date.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

days
optional

Including this parameter sets the number of days in which to send automatic reminders.

Excluding it will remove automatic reminders from the document.

integer
int32

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

400

The days parameter must a number between 1 and the number of days left before the document expires.

409

The document status should be Pending.

Restart a document

POST /api/v2/documents/{document_id}/restart

Restart a document that has been cancelled, timed out, or rejected.

OAuth Privileges required: DOC_CREATE

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
201

The document metadata as a JSON.

409

Documents that are in Preparation, Pending, or Closed can not be restarted.

Set the signatory authentication-to-view method

POST /api/v2/documents/{document_id}/{signatory_id}/setauthenticationtoview

Set the signatory authentication-to-view method after the document has been started.

Side effects of this operation may include adding or modifying fields for the signatory.

For example, if the signatory does not have a field for personal number, then setting the authentication method to Swedish BankID will necessitate adding the field to the signatory with a valid personal number.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

signatory_id
required

Unique identifier for a signatory. This value can change before document is made ready for signing, and should not be used to identify signatories while document is a draft.

integer
int64

path

authentication_type
required

The type of authentication-to-view method to set for the signatory.

string

formData

personal_number
optional

If the authentication_type requires a personal number, and the signatory doesn’t have one set already, then it must be provided and valid for the chosen authentication-to-view method.

string

formData

mobile_number
optional

Can be used for authentication_type that makes use of a mobile number. Similar requirements as personal_number.

Currently only Norwegian BankID uses this and therefore must be a valid Norwegian mobile number.

string

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

Possible error responses:

  • document_state_error: The document status should be 'Pending’.
  • signatory_state_error: The signatory has already authenticated to view.
  • signatory_state_error: The signatory has already signed.
  • signatory_state_error: You can’t mix different e-legitimation providers (one for viewing and another for signing) for the same signatory.

Set the signatory authentication-to-sign method

POST /api/v2/documents/{document_id}/{signatory_id}/setauthenticationtosign

Set the signatory authentication-to-sign method after the document has been started.

Side effects of this operation may include adding or modifying fields for the signatory.

For example, if the signatory does not have a field for mobile number, then setting the authentication method to SMS PIN will necessitate adding a mobile number field to the signatory and setting it as obligatory.

OAuth Privileges required: DOC_SEND

Parameters

Parameter Description Type In

document_id
required

Unique identifier for a document. Will not change.

integer
int64

path

signatory_id
required

Unique identifier for a signatory. This value can change before document is made ready for signing, and should not be used to identify signatories while document is a draft.

integer
int64

path

authentication_type
required

The type of authentication-to-sign method to set for the signatory.

string

formData

authentication_value
optional

Including this parameter will set the value associated with authentication_type to this value (e.g. mobile number for SMS PIN).

Setting it to empty string will clear the associated value, if present.

Excluding it will not affect any signatory properties other than necessary side-effects. In particular, if a value for the associated field was already set, it will not be cleared.

string

formData

object_version
optional

If provided, will check the document object_version and only perform the operation if these match. Otherwise you will get a HTTP 409.

integer

formData

Responses

Code Description
200

The document metadata as a JSON.

409

Possible error responses:

  • document_state_error: The document status should be 'Pending’.
  • signatory_state_error: The signatory has already signed.
  • signatory_state_error: You can’t mix different e-legitimation providers (one for viewing and another for signing) for the same signatory.

Responses

Document

The document metadata as a JSON.

Document

(object)

Example JSON: for “Document”

{
  "id": "8222115557375075439",
  "title": "Contract for Magnus",
  "parties": [
    {
      "id": "189255",
      "user_id": "1404",
      "is_author": true,
      "is_signatory": false,
      "fields": [
        {
          "type": "name",
          "order": 1,
          "value": "Gregory",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "name",
          "order": 2,
          "value": "Davids",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "email",
          "value": "noreply@scrive.com",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "company",
          "value": "Scrive",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        }
      ],
      "sign_order": 1,
      "sign_time": null,
      "seen_time": null,
      "read_invitation_time": null,
      "rejected_time": null,
      "sign_success_redirect_url": null,
      "reject_redirect_url": null,
      "email_delivery_status": "unknown",
      "mobile_delivery_status": "unknown",
      "has_authenticated_to_view": false,
      "csv": null,
      "delivery_method": "pad",
      "authentication_method_to_view": "standard",
      "authentication_method_to_sign": "standard",
      "confirmation_delivery_method": "none",
      "allows_highlighting": false,
      "attachments": [],
      "highlighted_pages": [],
      "api_delivery_url": null
    },
    {
      "id": "189256",
      "user_id": null,
      "is_author": false,
      "is_signatory": true,
      "fields": [
        {
          "type": "name",
          "order": 1,
          "value": "Magnus",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "name",
          "order": 2,
          "value": "Söderholm",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "email",
          "value": "noemail@scrive.com",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "mobile",
          "value": "",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "company",
          "value": "Scrive",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "company_number",
          "value": "",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "signature",
          "name": "Signature 1",
          "signature": "195174",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": [
            {
              "xrel": 0.07894736842105263,
              "yrel": 0.09962825278810408,
              "wrel": 0.2736842105263158,
              "hrel": 0.0758364312267658,
              "fsrel": 0.0168,
              "page": 1,
              "tip": "right",
              "anchors": []
            }
          ]
        }
      ],
      "sign_order": 1,
      "sign_time": "2017-01-13T10:38:49.590815Z",
      "seen_time": "2017-01-13T10:38:33.1783Z",
      "read_invitation_time": null,
      "rejected_time": null,
      "sign_success_redirect_url": null,
      "reject_redirect_url": null,
      "email_delivery_status": "unknown",
      "mobile_delivery_status": "unknown",
      "has_authenticated_to_view": false,
      "csv": null,
      "delivery_method": "pad",
      "authentication_method_to_view": "standard",
      "authentication_method_to_sign": "standard",
      "confirmation_delivery_method": "none",
      "allows_highlighting": true,
      "attachments": [],
      "highlighted_pages": [
        {
          "page": 1,
          "file_id": "195173"
        }
      ],
      "api_delivery_url": null
    }
  ],
  "file": {
    "name": "contract.pdf",
    "id": "195124"
  },
  "sealed_file": {
    "name": "contract.pdf",
    "id": "195172"
  },
  "author_attachments": [],
  "ctime": "2017-01-13T10:38:17.916324Z",
  "mtime": "2017-01-13T10:38:49.590815Z",
  "timeout_time": "2017-04-13T22:59:59Z",
  "auto_remind_time": null,
  "status": "closed",
  "days_to_sign": 90,
  "days_to_remind": null,
  "display_options": {
    "show_header": true,
    "show_pdf_download": true,
    "show_reject_option": true,
    "allow_reject_reason": true,
    "show_footer": true,
    "document_is_receipt": false
  },
  "invitation_message": "",
  "confirmation_message": "",
  "lang": "en",
  "api_callback_url": null,
  "object_version": 26,
  "access_token": "da675b76d876abda",
  "timezone": "Europe/London",
  "tags": [],
  "is_template": false,
  "is_saved": true,
  "is_shared": false,
  "is_trashed": false,
  "is_deleted": false,
  "viewer": {
    "signatory_id": "189255",
    "role": "signatory"
  }
}

Defines the entire structure of a document to be signed, including the parties, the processes to follow, etc. It is a core data structure used throughout the Scrive Document API.

This object has the following properties:

id (string, read only)

Unique identifier for a document.

Will not change over time, and cannot be changed.

title (string)

The title of the document.

Can be modified while a document is in preparation. The title will be used in messages sent to the document’s parties.

parties (array)

List of signing and viewing parties.

Defines their details, how the document is delivered to them, what authentication method they must use, fields they must fill, fields placed on the PDF, etc.

All array elements must be of type:

Signatory
(object)

A signatory defines the details and process for each signing or non-signing party to a document.

This object has the following properties:

id (string, read only)

Unique identifier for a party.

Will not change over time, and cannot be changed.

user_id (integer, read only)

If this party has an account on the Scrive eSign system, it will be set here.

is_author (boolean, read only)

Whether this party is the author of the document.

is_signatory (boolean)

Whether this party is a signatory to the document, otherwise they are viewers and will not sign the document.

fields (array)

The signatory fields represent information requested from, or information about, the signatory. There are different types of fields, and the array can contain multiple instances of the same type.

Currently, Scrive supports the following field types:

  • SignatoryFieldName: First and last name of the signatory.
  • SignatoryFieldEmailMobile: Email and mobile of the signatory.
  • SignatoryFieldSignature: A signature box placed on the document, for the signatory to draw their signature.
  • SignatoryFieldStandard: Company name and number, and personal number (AKA social security number).
  • SignatoryFieldCheckbox: Checkboxes of varying sizes.
  • SignatoryFieldRadiogroup: Radio buttons of varying sizes.
  • SignatoryFieldCustomText: A text field for any other information about, or requested, from the signatory.

Please read the detailed definition of each field type for more information. New field types may be added at any point to extend Scrive eSign features.

Fields can have placements, which define where on the document they will appear. Similarly, a single field can have multiple placements on the document.

Note: Some field types have no effect without at least one placement.

The elements of this array must match *at least one* of the following properties:
SignatoryFieldName
(object)

A signatory field for the name(s) of the party.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a name field.

This element must be one of the following enum values:

  • name
order (integer, enum, required)

Whether this is the first name (i.e. given name) or second name (i.e. last name or surname).

Please ensure that there is exacatly one first name and one second name field, otherwise the signatory may not be asked for their name on the signing page.

This element must be one of the following enum values:

  • 1
  • 2
value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldEmailMobile

(object)

A signatory field for email addresses and mobile numbers.

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • email
  • mobile
value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

editable_by_signatory (boolean)

Whether the signatory can edit a pre-filled value for this field. This is useful when you have signatory details on file, but you want them to be able to modify their email or mobile if it has changed.

Note: Setting this to true means a signatory will always be able to change the value on the signing page. If you want a signatory to authenticate with SMS PIN, please be aware that this may affect your desired workflow.

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldSignature

(object)

A signatory field for placing signature boxes on the document.

This object has the following properties:

type (string, enum, required)

This element must be one of the following enum values:

  • signature
name (string, required)

A name for the signature field.

The signatory will not see the name of the signature field, however it will be used in the Evidence Log as a reference.

signature
The elements of this item must match *at least one* of the following properties:
(null)

When the signatory has not yet drawn a signature.

(string)

The File ID of the signature drawn by the signatory.

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be able to draw a signature.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldStandard

(object)

A signatory field for placing a number of standard text fields on the document:

  • Company name
  • Company number
  • Personal number (AKA social security number)

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • company
  • company_number
  • personal_number
value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCheckbox

(object)

A signatory field for placing checkboxes on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a checkbox field.

This element must be one of the following enum values:

  • checkbox
name (string, required)

A name for the checkbox.

The signatory will not see the name of the checkbox, however it will be used in the Evidence Log as a reference.

is_checked (boolean)

true when the checkbox is checked, false otherwise.

Setting this to true on a document in preparation has the effect of pre-checking the checkbox for the signatory.

Default: false

is_obligatory (boolean)

Whether the signatory is obliged to check this checkbox in order to sign the document.

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise there will be no checkbox visible to the signatory.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Checkboxes can only be three sizes. The numbers represent small, medium and large checkboxes.

This element must be one of the following enum values:

  • 0.011538
  • 0.021153
  • 0.0423076
hrel (number, enum, required)

Height of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldRadiogroup

(object)

A signatory field for placing radio buttons on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a radio button group field.

This element must be one of the following enum values:

  • radiogroup
name (string, required)

A name for the radiogroup.

The signatory will not see the name of the radiogroup, however it will be used in the Evidence Log as a reference.

values (array, required)

An array of radio button option values. The signatory will not see the name of the radio button values, however they will be used in the Evidence Log as a reference.

These must correspond one-to-one with the list of placements: that is the length of values must equal that of placements and vice-versa, otherwise an error is returned.

Must be equal in length to placements and have at least 2 items. Each item must be unique and not an empty string.

All array elements must be of type:

(string)

Empty strings are not allowed.

placements (array, required)

Defines where the individual radio buttons should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

These must correspond one-to-one with the list of values: that is the length of placements must equal that of vales and vice-versa, otherwise an error is returned.

Must be equal in length to values and have at least 2 items.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Radio buttons can only be three sizes. The numbers represent small, medium and large radio buttons.

This element must be one of the following enum values:

  • 0.014736
  • 0.021052
  • 0.025263
hrel (number, enum, required)

Height of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

All radio buttons within the same group must be placed on the same page.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCustomText

(object)

A custom signatory field for text values. Can be used for any text-based information. Must be placed on the document, otherwise the signatory will not be asked to fill in details. Provides an optional regular expression-based validation mechanism via the custom_validation field (see below).

This object has the following properties:

type (string, enum, required)

Used to specify that this is a custom text field.

This element must be one of the following enum values:

  • text
name (string, required)

A name for the custom field.

The name will be used as a placeholder value on the signing page, it will also be used in the Evidence Log as a reference.

value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be asked or presented with this information.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

custom_validation (object)

Optional. Describes how to validate the input to this field using a custom regular expression.

Default: null

The custom_validation object has the following properties:

pattern (string, required)

Regular expression pattern for field validation.

positive_example (string, required)

Example of an input that matches the pattern.

tooltip (string, required)

Tooltip for the input text field.

sign_order (integer)

Default: 1

sign_time (string, read only)
seen_time (string, read only)
read_invitation_time (string, read only)
rejected_time (string, read only)
sign_success_redirect_url (string)

The URL to redirect this party after they have signed the document.

reject_redirect_url (string)

The URL to redirect this party if they reject the document.

email_delivery_status (string, enum)

The current delivery status.

This element must be one of the following enum values:

  • unknown
  • not_delivered
  • delivered
  • deferred
mobile_delivery_status (string, enum)

The current delivery status.

This element must be one of the following enum values:

  • unknown
  • not_delivered
  • delivered
  • deferred
csv (array)

All array elements must be of type:

(array)

All array elements must be of type:

(string)

delivery_method (string, enum)

Default: "email"

This element must be one of the following enum values:

  • email
  • mobile
  • email_mobile
  • pad
  • api
authentication_method_to_view (string, enum)

Default: "standard"

This element must be one of the following enum values:

  • standard
  • se_bankid
  • no_bankid
  • dk_nemid
authentication_method_to_sign (string, enum)

Default: "standard"

This element must be one of the following enum values:

  • standard
  • sms_pin
  • se_bankid
confirmation_delivery_method (string, enum)

Default: "email"

This element must be one of the following enum values:

  • email
  • mobile
  • email_mobile
  • none
allows_highlighting (boolean)

Whether the signatory can highlight pages of the PDF when viewing the signing page.

If any highlights are performed, the evidence log states that they were performed while the signatory was viewing the document.

The intention of this feature is not for the signatory to affect a contract via highlighting, but simply for a point-of-sale situation to assist contract review.

Default: false

highlighted_pages (array, read only)

A list of highlights performed by the signatory.

While a document is pending, highlights may be added, but will not appear in the document file PDF until after the document is closed.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

page (integer)

The page number which is highlighted (starts from 1). Each signatory can only have one highlight per page.

file_id (string)

The file_id for an image of the highlights.

The image dimensions will fit the ratio of the PDF page, and will be of a fixed colour and transparency.

This will be integrated into the final PDF once the document is closed.

attachments (array)

Default: []

All array elements must be of type:

(object)

An attachment requested from the signing party. Attachments requested from viewing only parties have no effect.

This object has the following properties:

name (string)

A name for the requested attachment. Will be visible to the signatory when signing the document.

description (string)

A description for the requested attachment. Will be visible to the signatory when signing the document alongside the attachment name.

required (boolean)

Whether the signatory must upload this attachment. If false, the signatory may choose not to upload this attachment when signing.

Default: true

file_id (string)

Will be present if and when the party uploads this attachment.

file_name (string)

Will be present if and when the party uploads this attachment.

api_delivery_url (string)

If the delivery_method is set to api, then this field will hold the relative URL for the party.

This will only be available after the signing process has been started, and will only be visible when accessing the document as the author.

file (object)

A file that can be accessed using the API call to download related files.

The file object has the following properties:

id (string, read only)
name (string, read only)

sealed_file (object)

The cryptographically sealed file.

Will only exist for documents that have been closed. This field may be null for a short period of time after a document has been signed by all parties, while the Scrive eSign system seals the document.

The sealed_file object has the following properties:

id (string, read only)
name (string, read only)

author_attachments (array, read only)

List of author attachments.

Can be updated during document preparation using the “set author attachments” (/{document_id}/setattachments) API call.

All array elements must be of type:

(object)

This object has the following properties:

name (string, read only)
required (boolean, read only)
add_to_sealed_file (boolean, read only)
file_id (string)

ctime (string, read only)

Time at which the document was created.

mtime (string, read only)

Latest time at which the document was modified.

timeout_time (string, read only)

Time after which the document will timeout if it has not been signed.

auto_remind_time (string, read only)

status (string, enum)

The current document status.

A document in “preparation” can be changed using the update call and the main file can also be set or changed.

Once the document signing process has begun, the document will be “pending”.

Once all parties have successfully signed the document is “closed” and cannot be changed.

This element must be one of the following enum values:

  • preparation
  • pending
  • closed
  • canceled
  • timedout
  • rejected
  • document_error

days_to_sign (integer)

Default: 90

days_to_remind (integer)

display_options (object)

The display_options object has the following properties:

show_header (boolean)

Whether to show the Scrive header on the signing page.

show_pdf_download (boolean)

Whether to show an option to download the PDF on the signing page.

show_reject_option (boolean)

Whether to allow signatories to reject a document.

allow_reject_reason (boolean)

Whether to allow signatories to enter a plain text reason for rejecting a document.

show_footer (boolean)

Whether to show the Scrive footer on the signing page.

document_is_receipt (boolean)

Whether the document is a receipt to be printed out, and thus should not have the verification footer added.

Note: This reduces the durability of evidence for a document signed through Scrive eSign, and should only be used when absolutely necessary.

invitation_message (string)

The invitation message to send to all parties at the start of the signing process.

Default is blank.

Default: ""

confirmation_message (string)

The confirmation message to send to all parties once the document has been signed.

Default is blank.

Default: ""

lang (string, enum)

Currently supported language codes

This element must be one of the following enum values:

  • da
  • de
  • el
  • en
  • es
  • et
  • fi
  • fr
  • is
  • it
  • lt
  • lv
  • nl
  • no
  • pt
  • sv

api_callback_url (string)

The URL to perform an API callback request.

Please see Callbacks for details.

object_version (integer, read only)

The document object version is auto-incremented by the Scrive eSign system each time an action is performed on it.

Therefore this can be used as a rudimentary synchronisation mechanism to ensure you are handling a document that has not changed.

It is not recommended to use this field unless you are building an application with offline capabilities.

Additional restrictions:

access_token (string, read only)

timezone (string)

tags (array)

User defined set of names and values.

Can be used to manage categories of documents. The list API call can filter based on document tags.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

name (string)
value (string)

is_template (boolean)

is_saved (boolean)

A ‘saved’ document will appear in the E-archive.

is_shared (boolean, read only)

is_trashed (boolean, read only)

is_deleted (boolean, read only)

viewer (object)

The viewer object has the following properties:

role (string, enum)

This element must be one of the following enum values:

  • company_shared
  • company_admin
  • signatory
signatory_id (string)

APIError

The JSON structured errors returned by the API.

API Error

(object)

Example JSON: for “API Error”

{
  "error_type": "request_parameters_parse_error",
  "error_message": "The parameter 'document' could not be parsed. Please refer to our API documentation. Error details: Invalid JSON",
  "http_code": 400
}

The structure of errors returned by the Scrive Document API.

This object has the following properties:

error_type (string, enum)

This element must be one of the following enum values:

  • server_error
  • endpoint_not_found
  • invalid_authorisation
  • insufficient_privileges
  • resource_not_found
  • document_action_forbidden
  • request_parameters_missing
  • request_parameters_parse_error
  • request_parameters_invalid
  • document_object_version_mismatch
  • document_state_error
  • signatory_state_error

error_message (string)

http_code (integer, enum)

This element must be one of the following enum values:

  • 400
  • 401
  • 403
  • 404
  • 409
  • 500
  • 603

Definitions

Document

(object)

Example JSON: for “Document”

{
  "id": "8222115557375075439",
  "title": "Contract for Magnus",
  "parties": [
    {
      "id": "189255",
      "user_id": "1404",
      "is_author": true,
      "is_signatory": false,
      "fields": [
        {
          "type": "name",
          "order": 1,
          "value": "Gregory",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "name",
          "order": 2,
          "value": "Davids",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "email",
          "value": "noreply@scrive.com",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "company",
          "value": "Scrive",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        }
      ],
      "sign_order": 1,
      "sign_time": null,
      "seen_time": null,
      "read_invitation_time": null,
      "rejected_time": null,
      "sign_success_redirect_url": null,
      "reject_redirect_url": null,
      "email_delivery_status": "unknown",
      "mobile_delivery_status": "unknown",
      "has_authenticated_to_view": false,
      "csv": null,
      "delivery_method": "pad",
      "authentication_method_to_view": "standard",
      "authentication_method_to_sign": "standard",
      "confirmation_delivery_method": "none",
      "allows_highlighting": false,
      "attachments": [],
      "highlighted_pages": [],
      "api_delivery_url": null
    },
    {
      "id": "189256",
      "user_id": null,
      "is_author": false,
      "is_signatory": true,
      "fields": [
        {
          "type": "name",
          "order": 1,
          "value": "Magnus",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "name",
          "order": 2,
          "value": "Söderholm",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "email",
          "value": "noemail@scrive.com",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "mobile",
          "value": "",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "company",
          "value": "Scrive",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "company_number",
          "value": "",
          "is_obligatory": false,
          "should_be_filled_by_sender": false,
          "placements": []
        },
        {
          "type": "signature",
          "name": "Signature 1",
          "signature": "195174",
          "is_obligatory": true,
          "should_be_filled_by_sender": false,
          "placements": [
            {
              "xrel": 0.07894736842105263,
              "yrel": 0.09962825278810408,
              "wrel": 0.2736842105263158,
              "hrel": 0.0758364312267658,
              "fsrel": 0.0168,
              "page": 1,
              "tip": "right",
              "anchors": []
            }
          ]
        }
      ],
      "sign_order": 1,
      "sign_time": "2017-01-13T10:38:49.590815Z",
      "seen_time": "2017-01-13T10:38:33.1783Z",
      "read_invitation_time": null,
      "rejected_time": null,
      "sign_success_redirect_url": null,
      "reject_redirect_url": null,
      "email_delivery_status": "unknown",
      "mobile_delivery_status": "unknown",
      "has_authenticated_to_view": false,
      "csv": null,
      "delivery_method": "pad",
      "authentication_method_to_view": "standard",
      "authentication_method_to_sign": "standard",
      "confirmation_delivery_method": "none",
      "allows_highlighting": true,
      "attachments": [],
      "highlighted_pages": [
        {
          "page": 1,
          "file_id": "195173"
        }
      ],
      "api_delivery_url": null
    }
  ],
  "file": {
    "name": "contract.pdf",
    "id": "195124"
  },
  "sealed_file": {
    "name": "contract.pdf",
    "id": "195172"
  },
  "author_attachments": [],
  "ctime": "2017-01-13T10:38:17.916324Z",
  "mtime": "2017-01-13T10:38:49.590815Z",
  "timeout_time": "2017-04-13T22:59:59Z",
  "auto_remind_time": null,
  "status": "closed",
  "days_to_sign": 90,
  "days_to_remind": null,
  "display_options": {
    "show_header": true,
    "show_pdf_download": true,
    "show_reject_option": true,
    "allow_reject_reason": true,
    "show_footer": true,
    "document_is_receipt": false
  },
  "invitation_message": "",
  "confirmation_message": "",
  "lang": "en",
  "api_callback_url": null,
  "object_version": 26,
  "access_token": "da675b76d876abda",
  "timezone": "Europe/London",
  "tags": [],
  "is_template": false,
  "is_saved": true,
  "is_shared": false,
  "is_trashed": false,
  "is_deleted": false,
  "viewer": {
    "signatory_id": "189255",
    "role": "signatory"
  }
}

Defines the entire structure of a document to be signed, including the parties, the processes to follow, etc. It is a core data structure used throughout the Scrive Document API.

This object has the following properties:

id (string, read only)

Unique identifier for a document.

Will not change over time, and cannot be changed.

title (string)

The title of the document.

Can be modified while a document is in preparation. The title will be used in messages sent to the document’s parties.

parties (array)

List of signing and viewing parties.

Defines their details, how the document is delivered to them, what authentication method they must use, fields they must fill, fields placed on the PDF, etc.

All array elements must be of type:

Signatory

(object)

A signatory defines the details and process for each signing or non-signing party to a document.

This object has the following properties:

id (string, read only)

Unique identifier for a party.

Will not change over time, and cannot be changed.

user_id (integer, read only)

If this party has an account on the Scrive eSign system, it will be set here.

is_author (boolean, read only)

Whether this party is the author of the document.

is_signatory (boolean)

Whether this party is a signatory to the document, otherwise they are viewers and will not sign the document.

fields (array)

The signatory fields represent information requested from, or information about, the signatory. There are different types of fields, and the array can contain multiple instances of the same type.

Currently, Scrive supports the following field types:

  • SignatoryFieldName: First and last name of the signatory.
  • SignatoryFieldEmailMobile: Email and mobile of the signatory.
  • SignatoryFieldSignature: A signature box placed on the document, for the signatory to draw their signature.
  • SignatoryFieldStandard: Company name and number, and personal number (AKA social security number).
  • SignatoryFieldCheckbox: Checkboxes of varying sizes.
  • SignatoryFieldRadiogroup: Radio buttons of varying sizes.
  • SignatoryFieldCustomText: A text field for any other information about, or requested, from the signatory.

Please read the detailed definition of each field type for more information. New field types may be added at any point to extend Scrive eSign features.

Fields can have placements, which define where on the document they will appear. Similarly, a single field can have multiple placements on the document.

Note: Some field types have no effect without at least one placement.

The elements of this array must match *at least one* of the following properties:
SignatoryFieldName
(object)

A signatory field for the name(s) of the party.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a name field.

This element must be one of the following enum values:

  • name
order (integer, enum, required)

Whether this is the first name (i.e. given name) or second name (i.e. last name or surname).

Please ensure that there is exacatly one first name and one second name field, otherwise the signatory may not be asked for their name on the signing page.

This element must be one of the following enum values:

  • 1
  • 2
value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldEmailMobile

(object)

A signatory field for email addresses and mobile numbers.

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • email
  • mobile
value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

editable_by_signatory (boolean)

Whether the signatory can edit a pre-filled value for this field. This is useful when you have signatory details on file, but you want them to be able to modify their email or mobile if it has changed.

Note: Setting this to true means a signatory will always be able to change the value on the signing page. If you want a signatory to authenticate with SMS PIN, please be aware that this may affect your desired workflow.

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldSignature

(object)

A signatory field for placing signature boxes on the document.

This object has the following properties:

type (string, enum, required)

This element must be one of the following enum values:

  • signature
name (string, required)

A name for the signature field.

The signatory will not see the name of the signature field, however it will be used in the Evidence Log as a reference.

signature
The elements of this item must match *at least one* of the following properties:
(null)

When the signatory has not yet drawn a signature.

(string)

The File ID of the signature drawn by the signatory.

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be able to draw a signature.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldStandard

(object)

A signatory field for placing a number of standard text fields on the document:

  • Company name
  • Company number
  • Personal number (AKA social security number)

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • company
  • company_number
  • personal_number
value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCheckbox

(object)

A signatory field for placing checkboxes on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a checkbox field.

This element must be one of the following enum values:

  • checkbox
name (string, required)

A name for the checkbox.

The signatory will not see the name of the checkbox, however it will be used in the Evidence Log as a reference.

is_checked (boolean)

true when the checkbox is checked, false otherwise.

Setting this to true on a document in preparation has the effect of pre-checking the checkbox for the signatory.

Default: false

is_obligatory (boolean)

Whether the signatory is obliged to check this checkbox in order to sign the document.

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise there will be no checkbox visible to the signatory.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Checkboxes can only be three sizes. The numbers represent small, medium and large checkboxes.

This element must be one of the following enum values:

  • 0.011538
  • 0.021153
  • 0.0423076
hrel (number, enum, required)

Height of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldRadiogroup

(object)

A signatory field for placing radio buttons on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a radio button group field.

This element must be one of the following enum values:

  • radiogroup
name (string, required)

A name for the radiogroup.

The signatory will not see the name of the radiogroup, however it will be used in the Evidence Log as a reference.

values (array, required)

An array of radio button option values. The signatory will not see the name of the radio button values, however they will be used in the Evidence Log as a reference.

These must correspond one-to-one with the list of placements: that is the length of values must equal that of placements and vice-versa, otherwise an error is returned.

Must be equal in length to placements and have at least 2 items. Each item must be unique and not an empty string.

All array elements must be of type:

(string)

Empty strings are not allowed.

placements (array, required)

Defines where the individual radio buttons should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

These must correspond one-to-one with the list of values: that is the length of placements must equal that of vales and vice-versa, otherwise an error is returned.

Must be equal in length to values and have at least 2 items.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Radio buttons can only be three sizes. The numbers represent small, medium and large radio buttons.

This element must be one of the following enum values:

  • 0.014736
  • 0.021052
  • 0.025263
hrel (number, enum, required)

Height of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

All radio buttons within the same group must be placed on the same page.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCustomText

(object)

A custom signatory field for text values. Can be used for any text-based information. Must be placed on the document, otherwise the signatory will not be asked to fill in details. Provides an optional regular expression-based validation mechanism via the custom_validation field (see below).

This object has the following properties:

type (string, enum, required)

Used to specify that this is a custom text field.

This element must be one of the following enum values:

  • text
name (string, required)

A name for the custom field.

The name will be used as a placeholder value on the signing page, it will also be used in the Evidence Log as a reference.

value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be asked or presented with this information.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

custom_validation (object)

Optional. Describes how to validate the input to this field using a custom regular expression.

Default: null

The custom_validation object has the following properties:

pattern (string, required)

Regular expression pattern for field validation.

positive_example (string, required)

Example of an input that matches the pattern.

tooltip (string, required)

Tooltip for the input text field.

sign_order (integer)

Default: 1

sign_time (string, read only)
seen_time (string, read only)
read_invitation_time (string, read only)
rejected_time (string, read only)
sign_success_redirect_url (string)

The URL to redirect this party after they have signed the document.

reject_redirect_url (string)

The URL to redirect this party if they reject the document.

email_delivery_status (string, enum)

The current delivery status.

This element must be one of the following enum values:

  • unknown
  • not_delivered
  • delivered
  • deferred
mobile_delivery_status (string, enum)

The current delivery status.

This element must be one of the following enum values:

  • unknown
  • not_delivered
  • delivered
  • deferred
csv (array)

All array elements must be of type:

(array)

All array elements must be of type:

(string)

delivery_method (string, enum)

Default: "email"

This element must be one of the following enum values:

  • email
  • mobile
  • email_mobile
  • pad
  • api
authentication_method_to_view (string, enum)

Default: "standard"

This element must be one of the following enum values:

  • standard
  • se_bankid
  • no_bankid
  • dk_nemid
authentication_method_to_sign (string, enum)

Default: "standard"

This element must be one of the following enum values:

  • standard
  • sms_pin
  • se_bankid
confirmation_delivery_method (string, enum)

Default: "email"

This element must be one of the following enum values:

  • email
  • mobile
  • email_mobile
  • none
allows_highlighting (boolean)

Whether the signatory can highlight pages of the PDF when viewing the signing page.

If any highlights are performed, the evidence log states that they were performed while the signatory was viewing the document.

The intention of this feature is not for the signatory to affect a contract via highlighting, but simply for a point-of-sale situation to assist contract review.

Default: false

highlighted_pages (array, read only)

A list of highlights performed by the signatory.

While a document is pending, highlights may be added, but will not appear in the document file PDF until after the document is closed.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

page (integer)

The page number which is highlighted (starts from 1). Each signatory can only have one highlight per page.

file_id (string)

The file_id for an image of the highlights.

The image dimensions will fit the ratio of the PDF page, and will be of a fixed colour and transparency.

This will be integrated into the final PDF once the document is closed.

attachments (array)

Default: []

All array elements must be of type:

(object)

An attachment requested from the signing party. Attachments requested from viewing only parties have no effect.

This object has the following properties:

name (string)

A name for the requested attachment. Will be visible to the signatory when signing the document.

description (string)

A description for the requested attachment. Will be visible to the signatory when signing the document alongside the attachment name.

required (boolean)

Whether the signatory must upload this attachment. If false, the signatory may choose not to upload this attachment when signing.

Default: true

file_id (string)

Will be present if and when the party uploads this attachment.

file_name (string)

Will be present if and when the party uploads this attachment.

api_delivery_url (string)

If the delivery_method is set to api, then this field will hold the relative URL for the party.

This will only be available after the signing process has been started, and will only be visible when accessing the document as the author.

file (object)

A file that can be accessed using the API call to download related files.

The file object has the following properties:

id (string, read only)

name (string, read only)

sealed_file (object)

The cryptographically sealed file.

Will only exist for documents that have been closed. This field may be null for a short period of time after a document has been signed by all parties, while the Scrive eSign system seals the document.

The sealed_file object has the following properties:

id (string, read only)

name (string, read only)

author_attachments (array, read only)

List of author attachments.

Can be updated during document preparation using the “set author attachments” (/{document_id}/setattachments) API call.

All array elements must be of type:

(object)

This object has the following properties:

name (string, read only)
required (boolean, read only)
add_to_sealed_file (boolean, read only)
file_id (string)

ctime (string, read only)

Time at which the document was created.

mtime (string, read only)

Latest time at which the document was modified.

timeout_time (string, read only)

Time after which the document will timeout if it has not been signed.

auto_remind_time (string, read only)

status (string, enum)

The current document status.

A document in “preparation” can be changed using the update call and the main file can also be set or changed.

Once the document signing process has begun, the document will be “pending”.

Once all parties have successfully signed the document is “closed” and cannot be changed.

This element must be one of the following enum values:

  • preparation
  • pending
  • closed
  • canceled
  • timedout
  • rejected
  • document_error

days_to_sign (integer)

Default: 90

days_to_remind (integer)

display_options (object)

The display_options object has the following properties:

show_header (boolean)

Whether to show the Scrive header on the signing page.

show_pdf_download (boolean)

Whether to show an option to download the PDF on the signing page.

show_reject_option (boolean)

Whether to allow signatories to reject a document.

allow_reject_reason (boolean)

Whether to allow signatories to enter a plain text reason for rejecting a document.

show_footer (boolean)

Whether to show the Scrive footer on the signing page.

document_is_receipt (boolean)

Whether the document is a receipt to be printed out, and thus should not have the verification footer added.

Note: This reduces the durability of evidence for a document signed through Scrive eSign, and should only be used when absolutely necessary.

invitation_message (string)

The invitation message to send to all parties at the start of the signing process.

Default is blank.

Default: ""

confirmation_message (string)

The confirmation message to send to all parties once the document has been signed.

Default is blank.

Default: ""

lang (string, enum)

Currently supported language codes

This element must be one of the following enum values:

  • da
  • de
  • el
  • en
  • es
  • et
  • fi
  • fr
  • is
  • it
  • lt
  • lv
  • nl
  • no
  • pt
  • sv

api_callback_url (string)

The URL to perform an API callback request.

Please see Callbacks for details.

object_version (integer, read only)

The document object version is auto-incremented by the Scrive eSign system each time an action is performed on it.

Therefore this can be used as a rudimentary synchronisation mechanism to ensure you are handling a document that has not changed.

It is not recommended to use this field unless you are building an application with offline capabilities.

Additional restrictions:

access_token (string, read only)

timezone (string)

tags (array)

User defined set of names and values.

Can be used to manage categories of documents. The list API call can filter based on document tags.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

name (string)
value (string)

is_template (boolean)

is_saved (boolean)

A ‘saved’ document will appear in the E-archive.

is_shared (boolean, read only)

is_trashed (boolean, read only)

is_deleted (boolean, read only)

viewer (object)

The viewer object has the following properties:

role (string, enum)

This element must be one of the following enum values:

  • company_shared
  • company_admin
  • signatory

signatory_id (string)

Document Status

(string, enum)

The current document status.

A document in “preparation” can be changed using the update call and the main file can also be set or changed.

Once the document signing process has begun, the document will be “pending”.

Once all parties have successfully signed the document is “closed” and cannot be changed.

This element must be one of the following enum values:

  • preparation
  • pending
  • closed
  • canceled
  • timedout
  • rejected
  • document_error

Signatory

(object)

Example JSON: for “Signatory”

{
  "id": "189256",
  "user_id": null,
  "is_author": false,
  "is_signatory": true,
  "fields": [
    {
      "type": "name",
      "order": 1,
      "value": "Magnus",
      "is_obligatory": true,
      "should_be_filled_by_sender": false,
      "placements": []
    },
    {
      "type": "name",
      "order": 2,
      "value": "Söderholm",
      "is_obligatory": true,
      "should_be_filled_by_sender": false,
      "placements": []
    },
    {
      "type": "email",
      "value": "noemail@scrive.com",
      "is_obligatory": false,
      "should_be_filled_by_sender": false,
      "editable_by_signatory": false,
      "placements": []
    },
    {
      "type": "mobile",
      "value": "",
      "is_obligatory": false,
      "should_be_filled_by_sender": false,
      "placements": []
    },
    {
      "type": "company",
      "value": "Scrive",
      "is_obligatory": false,
      "should_be_filled_by_sender": false,
      "placements": []
    },
    {
      "type": "company_number",
      "value": "",
      "is_obligatory": false,
      "should_be_filled_by_sender": false,
      "placements": []
    },
    {
      "type": "signature",
      "name": "Signature 1",
      "signature": "195174",
      "is_obligatory": true,
      "should_be_filled_by_sender": false,
      "placements": [
        {
          "xrel": 0.07894736842105263,
          "yrel": 0.09962825278810408,
          "wrel": 0.2736842105263158,
          "hrel": 0.0758364312267658,
          "fsrel": 0.0168,
          "page": 1,
          "tip": "right",
          "anchors": []
        }
      ]
    }
  ],
  "sign_order": 1,
  "sign_time": "2017-01-13T10:38:49.590815Z",
  "seen_time": "2017-01-13T10:38:33.1783Z",
  "read_invitation_time": null,
  "rejected_time": null,
  "sign_success_redirect_url": null,
  "reject_redirect_url": null,
  "email_delivery_status": "unknown",
  "mobile_delivery_status": "unknown",
  "has_authenticated_to_view": false,
  "csv": null,
  "delivery_method": "pad",
  "authentication_method_to_view": "standard",
  "authentication_method_to_sign": "standard",
  "confirmation_delivery_method": "none",
  "allows_highlighting": true,
  "attachments": [],
  "highlighted_pages": [
    {
      "page": 1,
      "file_id": "195173"
    }
  ],
  "api_delivery_url": null
}

A signatory defines the details and process for each signing or non-signing party to a document.

This object has the following properties:

id (string, read only)

Unique identifier for a party.

Will not change over time, and cannot be changed.

user_id (integer, read only)

If this party has an account on the Scrive eSign system, it will be set here.

is_author (boolean, read only)

Whether this party is the author of the document.

is_signatory (boolean)

Whether this party is a signatory to the document, otherwise they are viewers and will not sign the document.

fields (array)

The signatory fields represent information requested from, or information about, the signatory. There are different types of fields, and the array can contain multiple instances of the same type.

Currently, Scrive supports the following field types:

  • SignatoryFieldName: First and last name of the signatory.
  • SignatoryFieldEmailMobile: Email and mobile of the signatory.
  • SignatoryFieldSignature: A signature box placed on the document, for the signatory to draw their signature.
  • SignatoryFieldStandard: Company name and number, and personal number (AKA social security number).
  • SignatoryFieldCheckbox: Checkboxes of varying sizes.
  • SignatoryFieldRadiogroup: Radio buttons of varying sizes.
  • SignatoryFieldCustomText: A text field for any other information about, or requested, from the signatory.

Please read the detailed definition of each field type for more information. New field types may be added at any point to extend Scrive eSign features.

Fields can have placements, which define where on the document they will appear. Similarly, a single field can have multiple placements on the document.

Note: Some field types have no effect without at least one placement.

The elements of this array must match *at least one* of the following properties:

SignatoryFieldName

(object)

A signatory field for the name(s) of the party.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a name field.

This element must be one of the following enum values:

  • name
order (integer, enum, required)

Whether this is the first name (i.e. given name) or second name (i.e. last name or surname).

Please ensure that there is exacatly one first name and one second name field, otherwise the signatory may not be asked for their name on the signing page.

This element must be one of the following enum values:

  • 1
  • 2
value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldEmailMobile

(object)

A signatory field for email addresses and mobile numbers.

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • email
  • mobile
value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

editable_by_signatory (boolean)

Whether the signatory can edit a pre-filled value for this field. This is useful when you have signatory details on file, but you want them to be able to modify their email or mobile if it has changed.

Note: Setting this to true means a signatory will always be able to change the value on the signing page. If you want a signatory to authenticate with SMS PIN, please be aware that this may affect your desired workflow.

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldSignature

(object)

A signatory field for placing signature boxes on the document.

This object has the following properties:

type (string, enum, required)

This element must be one of the following enum values:

  • signature
name (string, required)

A name for the signature field.

The signatory will not see the name of the signature field, however it will be used in the Evidence Log as a reference.

signature
The elements of this item must match *at least one* of the following properties:
(null)

When the signatory has not yet drawn a signature.

(string)

The File ID of the signature drawn by the signatory.

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be able to draw a signature.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldStandard

(object)

A signatory field for placing a number of standard text fields on the document:

  • Company name
  • Company number
  • Personal number (AKA social security number)

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • company
  • company_number
  • personal_number
value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCheckbox

(object)

A signatory field for placing checkboxes on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a checkbox field.

This element must be one of the following enum values:

  • checkbox
name (string, required)

A name for the checkbox.

The signatory will not see the name of the checkbox, however it will be used in the Evidence Log as a reference.

is_checked (boolean)

true when the checkbox is checked, false otherwise.

Setting this to true on a document in preparation has the effect of pre-checking the checkbox for the signatory.

Default: false

is_obligatory (boolean)

Whether the signatory is obliged to check this checkbox in order to sign the document.

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise there will be no checkbox visible to the signatory.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Checkboxes can only be three sizes. The numbers represent small, medium and large checkboxes.

This element must be one of the following enum values:

  • 0.011538
  • 0.021153
  • 0.0423076
hrel (number, enum, required)

Height of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldRadiogroup

(object)

A signatory field for placing radio buttons on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a radio button group field.

This element must be one of the following enum values:

  • radiogroup
name (string, required)

A name for the radiogroup.

The signatory will not see the name of the radiogroup, however it will be used in the Evidence Log as a reference.

values (array, required)

An array of radio button option values. The signatory will not see the name of the radio button values, however they will be used in the Evidence Log as a reference.

These must correspond one-to-one with the list of placements: that is the length of values must equal that of placements and vice-versa, otherwise an error is returned.

Must be equal in length to placements and have at least 2 items. Each item must be unique and not an empty string.

All array elements must be of type:

(string)

Empty strings are not allowed.

placements (array, required)

Defines where the individual radio buttons should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

These must correspond one-to-one with the list of values: that is the length of placements must equal that of vales and vice-versa, otherwise an error is returned.

Must be equal in length to values and have at least 2 items.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Radio buttons can only be three sizes. The numbers represent small, medium and large radio buttons.

This element must be one of the following enum values:

  • 0.014736
  • 0.021052
  • 0.025263
hrel (number, enum, required)

Height of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

All radio buttons within the same group must be placed on the same page.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCustomText

(object)

A custom signatory field for text values. Can be used for any text-based information. Must be placed on the document, otherwise the signatory will not be asked to fill in details. Provides an optional regular expression-based validation mechanism via the custom_validation field (see below).

This object has the following properties:

type (string, enum, required)

Used to specify that this is a custom text field.

This element must be one of the following enum values:

  • text
name (string, required)

A name for the custom field.

The name will be used as a placeholder value on the signing page, it will also be used in the Evidence Log as a reference.

value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be asked or presented with this information.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

custom_validation (object)

Optional. Describes how to validate the input to this field using a custom regular expression.

Default: null

The custom_validation object has the following properties:

pattern (string, required)

Regular expression pattern for field validation.

positive_example (string, required)

Example of an input that matches the pattern.

tooltip (string, required)

Tooltip for the input text field.

sign_order (integer)

Default: 1

sign_time (string, read only)

seen_time (string, read only)

read_invitation_time (string, read only)

rejected_time (string, read only)

sign_success_redirect_url (string)

The URL to redirect this party after they have signed the document.

reject_redirect_url (string)

The URL to redirect this party if they reject the document.

email_delivery_status (string, enum)

The current delivery status.

This element must be one of the following enum values:

  • unknown
  • not_delivered
  • delivered
  • deferred

mobile_delivery_status (string, enum)

The current delivery status.

This element must be one of the following enum values:

  • unknown
  • not_delivered
  • delivered
  • deferred

csv (array)

All array elements must be of type:

(array)

All array elements must be of type:

(string)

delivery_method (string, enum)

Default: "email"

This element must be one of the following enum values:

  • email
  • mobile
  • email_mobile
  • pad
  • api

authentication_method_to_view (string, enum)

Default: "standard"

This element must be one of the following enum values:

  • standard
  • se_bankid
  • no_bankid
  • dk_nemid

authentication_method_to_sign (string, enum)

Default: "standard"

This element must be one of the following enum values:

  • standard
  • sms_pin
  • se_bankid

confirmation_delivery_method (string, enum)

Default: "email"

This element must be one of the following enum values:

  • email
  • mobile
  • email_mobile
  • none

allows_highlighting (boolean)

Whether the signatory can highlight pages of the PDF when viewing the signing page.

If any highlights are performed, the evidence log states that they were performed while the signatory was viewing the document.

The intention of this feature is not for the signatory to affect a contract via highlighting, but simply for a point-of-sale situation to assist contract review.

Default: false

highlighted_pages (array, read only)

A list of highlights performed by the signatory.

While a document is pending, highlights may be added, but will not appear in the document file PDF until after the document is closed.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

page (integer)

The page number which is highlighted (starts from 1). Each signatory can only have one highlight per page.

file_id (string)

The file_id for an image of the highlights.

The image dimensions will fit the ratio of the PDF page, and will be of a fixed colour and transparency.

This will be integrated into the final PDF once the document is closed.

attachments (array)

Default: []

All array elements must be of type:

(object)

An attachment requested from the signing party. Attachments requested from viewing only parties have no effect.

This object has the following properties:

name (string)

A name for the requested attachment. Will be visible to the signatory when signing the document.

description (string)

A description for the requested attachment. Will be visible to the signatory when signing the document alongside the attachment name.

required (boolean)

Whether the signatory must upload this attachment. If false, the signatory may choose not to upload this attachment when signing.

Default: true

file_id (string)

Will be present if and when the party uploads this attachment.

file_name (string)

Will be present if and when the party uploads this attachment.

api_delivery_url (string)

If the delivery_method is set to api, then this field will hold the relative URL for the party.

This will only be available after the signing process has been started, and will only be visible when accessing the document as the author.

SignatoryFieldName

(object)

Example JSON: for “SignatoryFieldName”

{
  "type": "name",
  "order": 1,
  "value": "John",
  "is_obligatory": true,
  "should_be_filled_by_sender": false,
  "placements": [
    {
      "xrel": 0.26105263157894737,
      "yrel": 0.0975609756097561,
      "wrel": 0.07894736842105263,
      "hrel": 0.024390243902439025,
      "fsrel": 0.01263157894736842,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ]
}

A signatory field for the name(s) of the party.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a name field.

This element must be one of the following enum values:

  • name

order (integer, enum, required)

Whether this is the first name (i.e. given name) or second name (i.e. last name or surname).

Please ensure that there is exacatly one first name and one second name field, otherwise the signatory may not be asked for their name on the signing page.

This element must be one of the following enum values:

  • 1
  • 2

value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldEmailMobile

(object)

Example JSON: for “SignatoryFieldEmailMobile”

{
  "type": "mobile",
  "value": "+461234567890",
  "is_obligatory": false,
  "should_be_filled_by_sender": false,
  "editable_by_signatory": false,
  "placements": [
    {
      "xrel": 0.09052631578947369,
      "yrel": 0.2700892857142857,
      "wrel": 0.09157894736842105,
      "hrel": 0.025297619047619048,
      "fsrel": 0.016842105263157894,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ]
}

A signatory field for email addresses and mobile numbers.

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • email
  • mobile

value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

editable_by_signatory (boolean)

Whether the signatory can edit a pre-filled value for this field. This is useful when you have signatory details on file, but you want them to be able to modify their email or mobile if it has changed.

Note: Setting this to true means a signatory will always be able to change the value on the signing page. If you want a signatory to authenticate with SMS PIN, please be aware that this may affect your desired workflow.

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldSignature

(object)

Example JSON: for “SignatoryFieldSignature”

{
  "type": "signature",
  "name": "Signature 1",
  "signature": "9215148251416996589",
  "is_obligatory": true,
  "should_be_filled_by_sender": false,
  "placements": [
    {
      "xrel": 0.3510526315789474,
      "yrel": 0.1796747967479675,
      "wrel": 0.2736842105263158,
      "hrel": 0.08292682926829269,
      "fsrel": 0.0168,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ]
}

A signatory field for placing signature boxes on the document.

This object has the following properties:

type (string, enum, required)

This element must be one of the following enum values:

  • signature

name (string, required)

A name for the signature field.

The signatory will not see the name of the signature field, however it will be used in the Evidence Log as a reference.

signature

The elements of this item must match *at least one* of the following properties:

(null)

When the signatory has not yet drawn a signature.

(string)

The File ID of the signature drawn by the signatory.

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be able to draw a signature.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldStandard

(object)

Example JSON: for “SignatoryFieldStandard”

{
  "type": "company",
  "value": "Scrive AB",
  "is_obligatory": false,
  "should_be_filled_by_sender": false,
  "placements": [
    {
      "xrel": 0.09052631578947369,
      "yrel": 0.2700892857142857,
      "wrel": 0.09157894736842105,
      "hrel": 0.025297619047619048,
      "fsrel": 0.016842105263157894,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ]
}

A signatory field for placing a number of standard text fields on the document:

  • Company name
  • Company number
  • Personal number (AKA social security number)

This object has the following properties:

type (string, enum, required)

Used to specify what type of field this is.

This element must be one of the following enum values:

  • company
  • company_number
  • personal_number

value (string)

Either a pre-filled value, or the value entered by the signatory.

For the author: the value will revert to that set in the account settings. Trying to set any other value will simply result in this field reverting back to information set in account settings.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

If set, where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCheckbox

(object)

Example JSON: for “SignatoryFieldCheckbox”

{
  "type": "checkbox",
  "name": "Checkbox Name",
  "is_checked": true,
  "is_obligatory": true,
  "should_be_filled_by_sender": false,
  "placements": [
    {
      "xrel": 0.17526315789473684,
      "yrel": 0.3382113821138211,
      "wrel": 0.011538,
      "hrel": 0,
      "fsrel": 0,
      "page": 1,
      "tip": "left",
      "anchors": []
    }
  ]
}

A signatory field for placing checkboxes on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a checkbox field.

This element must be one of the following enum values:

  • checkbox

name (string, required)

A name for the checkbox.

The signatory will not see the name of the checkbox, however it will be used in the Evidence Log as a reference.

is_checked (boolean)

true when the checkbox is checked, false otherwise.

Setting this to true on a document in preparation has the effect of pre-checking the checkbox for the signatory.

Default: false

is_obligatory (boolean)

Whether the signatory is obliged to check this checkbox in order to sign the document.

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise there will be no checkbox visible to the signatory.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Checkboxes can only be three sizes. The numbers represent small, medium and large checkboxes.

This element must be one of the following enum values:

  • 0.011538
  • 0.021153
  • 0.0423076
hrel (number, enum, required)

Height of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for checkboxes, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldRadiogroup

(object)

Example JSON: for “SignatoryFieldRadiogroup”

{
  "type": "radiogroup",
  "name": "Large Radio buttons",
  "selected_value": "Radio button 2",
  "placements": [
    {
      "xrel": 0.7405263157894737,
      "yrel": 0.3796747967479675,
      "wrel": 0.025263,
      "hrel": 0,
      "fsrel": 0,
      "page": 1,
      "tip": "right",
      "anchors": []
    },
    {
      "xrel": 0.7405263157894737,
      "yrel": 0.4008130081300813,
      "wrel": 0.021052,
      "hrel": 0,
      "fsrel": 0,
      "page": 1,
      "tip": "right",
      "anchors": []
    },
    {
      "xrel": 0.7410526315789474,
      "yrel": 0.4211382113821138,
      "wrel": 0.014736,
      "hrel": 0,
      "fsrel": 0,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ],
  "values": [
    "Radio button 1",
    "Radio button 2",
    "Radio button 3"
  ]
}

A signatory field for placing radio buttons on the document.

This object has the following properties:

type (string, enum, required)

Used to specify that this is a radio button group field.

This element must be one of the following enum values:

  • radiogroup

name (string, required)

A name for the radiogroup.

The signatory will not see the name of the radiogroup, however it will be used in the Evidence Log as a reference.

values (array, required)

An array of radio button option values. The signatory will not see the name of the radio button values, however they will be used in the Evidence Log as a reference.

These must correspond one-to-one with the list of placements: that is the length of values must equal that of placements and vice-versa, otherwise an error is returned.

Must be equal in length to placements and have at least 2 items. Each item must be unique and not an empty string.

All array elements must be of type:

(string)

Empty strings are not allowed.

placements (array, required)

Defines where the individual radio buttons should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

These must correspond one-to-one with the list of values: that is the length of placements must equal that of vales and vice-versa, otherwise an error is returned.

Must be equal in length to values and have at least 2 items.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, enum, required)

Width of placement, as proportion of total width.

Radio buttons can only be three sizes. The numbers represent small, medium and large radio buttons.

This element must be one of the following enum values:

  • 0.014736
  • 0.021052
  • 0.025263
hrel (number, enum, required)

Height of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
fsrel (number, enum, required)

Font size of placement, not used for radio buttons, must be 0.

This element must be one of the following enum values:

  • 0
page (integer, required)

The page number for this placement, starting from 1.

All radio buttons within the same group must be placed on the same page.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

SignatoryFieldCustomText

(object)

Example JSON: for “SignatoryFieldCustomText”

{
  "type": "text",
  "name": "Custom Field Name",
  "value": "",
  "is_obligatory": true,
  "should_be_filled_by_sender": true,
  "placements": [
    {
      "xrel": 0.29368421052631577,
      "yrel": 0.3444940476190476,
      "wrel": 0.10842105263157895,
      "hrel": 0.025297619047619048,
      "fsrel": 0.016842105263157894,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ],
  "custom_validation": {
    "pattern": "^foo|bar|baz$",
    "positive_example": "foo",
    "tooltip": "Must be either 'foo', 'bar', or 'baz'."
  }
}

A custom signatory field for text values. Can be used for any text-based information. Must be placed on the document, otherwise the signatory will not be asked to fill in details. Provides an optional regular expression-based validation mechanism via the custom_validation field (see below).

This object has the following properties:

type (string, enum, required)

Used to specify that this is a custom text field.

This element must be one of the following enum values:

  • text

name (string, required)

A name for the custom field.

The name will be used as a placeholder value on the signing page, it will also be used in the Evidence Log as a reference.

value (string)

Either a pre-filled value, or the value entered by the signatory.

Default: ""

is_obligatory (boolean)

Default: true

should_be_filled_by_sender (boolean)

Default: false

placements (array)

Needs to be set, otherwise the signatory will not be asked or presented with this information.

Defines where this field should be placed on the document. This is both for the signatory to fill out on the signing page, and for the final sealed PDF.

Note that this is an array, you can have multiple placements for the same field.

The easiest way to set the xrel, yrel, etc. values is to create a template in the document UI design view, and use those values.

Default: []

All array elements must be of type:

(object)

This object has the following properties:

xrel (number, required)

Position on the x-axis, from 0 to 1.

yrel (number, required)

Position on the y-axis, from 0 to 1.

wrel (number, required)

Width of placement, as proportion of total width, from 0 to 1.

hrel (number, required)

Height of placement, as proportion of total width, from 0 to 1.

fsrel (number, required)

Font size of placement, as proportion of total width, from 0 to 1.

page (integer, required)

The page number for this placement, starting from 1.

tip

Default: null

The elements of this item must match *at least one* of the following properties:
(string, enum)

From which side the arrow on the signing page should point to the field.

This element must be one of the following enum values:

  • left
  • right
(null)

Let the signing page default to either left or right depending on the field type.

anchors (array)

Default: []

All array elements must be of type:

(object)

This object has the following properties:

text (string)
index (integer)

custom_validation (object)

Optional. Describes how to validate the input to this field using a custom regular expression.

Default: null

The custom_validation object has the following properties:

pattern (string, required)

Regular expression pattern for field validation.

positive_example (string, required)

Example of an input that matches the pattern.

tooltip (string, required)

Tooltip for the input text field.

List Filter

(array)

Example JSON: for “List Filter”

[
  {
    "filter_by": "status",
    "statuses": [
      "preparation",
      "pending"
    ]
  }
]

Parameter used to filter documents for the list API call.

Default: []

The elements of this array must match *at least one* of the following properties:

Filter by status

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • status

statuses (array)

All array elements must be of type:

Document Status
(string, enum)

The current document status.

A document in “preparation” can be changed using the update call and the main file can also be set or changed.

Once the document signing process has begun, the document will be “pending”.

Once all parties have successfully signed the document is “closed” and cannot be changed.

This element must be one of the following enum values:

  • preparation
  • pending
  • closed
  • canceled
  • timedout
  • rejected
  • document_error

Filter by mtime

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • mtime

start_time (string)

end_time (string)

Filter by tag

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • tag

value (string)

name (string)

Filter by author

(object)

Only include documents where the person making the API call is the document author.

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • is_author

Signable on pad

(object)

This implicitly adds an is_author filter.

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • is_signable_on_pad

Only templates

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • is_template

Only non-templates

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • is_not_template

In trash

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • is_in_trash

Not in trash

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • is_not_in_trash

Filter by author id

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • author

user_id (string)

Signable by user

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • user_can_sign

user_id (string)

Filter by text

(object)

This object has the following properties:

filter_by (string, enum)

This element must be one of the following enum values:

  • text

text (string)

List Sorting

(array)

Example JSON: for “List Sorting”

[
  {
    "sort_by": "author",
    "order": "ascending"
  }
]

Parameter used to sort documents for the list API call.

All array elements must be of type:

(object)

This object has the following properties:

order (string, enum)

Default: "ascending"

This element must be one of the following enum values:

  • ascending
  • descending

sort_by (string, enum, required)

This element must be one of the following enum values:

  • title
  • status
  • mtime
  • author

Author Attachments

(array)

Example JSON: for “Author Attachments”

[
  {
    "name": "Attachment using ID",
    "required": false,
    "add_to_sealed_file": true,
    "file_id": "36"
  },
  {
    "name": "Attachment using parameter",
    "required": false,
    "add_to_sealed_file": true,
    "file_param": "file_1"
  }
]

Attachments that have been added to a document by the author.

The elements of this array must match *at least one* of the following properties:

(object)

Attachment that is uploaded as part of the API call.

This object has the following properties:

name (string, required)

required (boolean, required)

add_to_sealed_file (boolean, required)

Whether to add the attachment to the sealed file after signing

file_param (string, required)

The parameter name used in the API call for this attachment.

(object)

Attachment that references a file_id.

This object has the following properties:

name (string, required)

required (boolean, required)

add_to_sealed_file (boolean, required)

Whether to add the attachment to the sealed file after signing

file_id (integer, required)

History Items

(object)

Example JSON: for “History Items”

{
  "events": [
    {
      "status": "initiated",
      "time": "2015-06-06T17:50:15Z",
      "party": "Not named party (1)",
      "text": "The signing process was initiated."
    }
  ]
}

The type returned by the Document History API call.

This can be used to show the progress of a document to the user.

This object has the following properties:

events (array)

All array elements must be of type:

(object)

This object has the following properties:

status (string, enum)

The document status “class”, not the same as the statuses available for documents.

This element must be one of the following enum values:

  • initiated
  • draft
  • cancelled
  • rejected
  • timeouted
  • problem
  • deliveryproblem
  • sent
  • delivered
  • read
  • opened
  • signed
  • prolonged
  • sealed
  • extended
time (string)
text (string)

The text describing the action.

party (string)

The name of the party performing the action.