NAV Navbar
Logo
  • Scrive Document API
  • Overview
  • Quick Start
  • Introduction
  • Authentication
  • Errors
  • List of API Calls
  • Prepare
  • Get
  • Modify
  • Responses
  • Definitions
  • 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
    2018-01-08 Add an endpoint to get a sign link as a QR code
    2018-01-29 Add an endpoint to change the email and mobile number of a signatory
    2018-02-28 Fix a minor error in the Quick Start guide
    2018-03-26 Add rejection_reason to the Signatory JSON and an API endpoint to control template sharing
    2018-03-29 Fix an omission where no_bankid (Norwegian BankID) was missing as an Authentication to Sign
    2018-04-09 Add a new field to the Signatory JSON: consent_module

    Environments & IP Addresses

    Production

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

    The IP addresses that may 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}/start (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/{document_id}/{signatory_id}/getqrcode

    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

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

    POST /api/v2/documents/templates/setsharing

    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.

    By default, it replaces any existing attachments, so all attachments must be set by any use of this call. See the parameter incremental to change this behaviour.

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

    incremental
    optional

    default: false

    If set to true, this will make the API set the given author attachments leaving all already set attachments intact.

    For each given attachment, if there already is one with the same name, it will get overwritten, otherwise, the attachment will be added.

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

    GET /api/v2/documents/{document_id}/{signatory_id}/getqrcode

    Get a Scrive eSign link for a given signatory and document ID, encoded as a QR code in PNG format. Only valid for pending documents.

    The encoded link is of the form scrive://{hostname}/{document_id}/{signatory_id}/{token} and is intended to be used with our mobile applications available on the Apple App Store and Google Play Store.

    This endpoint will work irrespective of the delivery method set. It will also work for viewing parties.

    OAuth Privileges required: DOC_CHECK

    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

    Responses

    Code Description
    200

    PNG image, content-type: image/png.

    409

    document_state_error with message The document state must be 'Pending'.

    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

    personal_number
    optional

    If provided, it must be valid for the chosen authentication-to-sign method.

    If it is not used by the chosen authentication-to-sign method, the parameter will be ignored and will have no effect.

    If not provided, any existing personal_number field value set for the signatory will not be changed. However, if a personal_number SignatoryField does not yet exist, one will be added to the signatory (with empty string as value).

    string

    formData

    mobile_number
    optional

    If provided, it must be valid for the chosen authentication-to-sign method.

    If it is not used by the chosen authentication-to-sign method, the parameter will be ignored and will have no effect.

    If not provided, any existing mobile field value set for the signatory will not be changed. However, if a mobile SignatoryField does not yet exist, one will be added to the signatory (with empty string as value).

    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.

    Change the email and mobile number of a signatory

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

    Change the email address and mobile number of a signatory after the document has been started.

    This API call is meant to be used for correcting mistakes that may occur during a manual document preparation process.

    If you are planning to use it programatically, please be aware that this will result in extra invitation messages being sent, the old invitation links being invalidated, and may therefore not be the approach best suited to your use-case.

    You will only be able to change values for fields that a signatory has. For example, if they have no mobile field set, you will not be able to change it.

    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

    email
    optional

    The new email address for the signatory.

    Whilst this field is optional, both email and mobile_number cannot be blank, you need at least one.

    string

    formData

    mobile_number
    optional

    The new mobile number for the signatory.

    Whilst this field is optional, both email and mobile_number cannot be blank, you need at least one.

    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, is the author, or does not have a mobile or email field already.
    • request_parameter_parse_error: Can happen if the email or mobile_number is not in the correct format.
    • request_parameter_missing: If neither email nor mobile_number is provided.

    Share or unshare templates

    POST /api/v2/documents/templates/setsharing

    Share or unshare the specified templates with the company's other users.

    OAuth Privileges required: DOC_CREATE

    Parameters

    Parameter Description Type In

    document_ids
    required

    List of document IDs of templates to share or unshare.

    string
    application/json

    formData

    shared
    required

    true to share, false to unshare.

    string
    application/json

    formData

    Responses

    Code Description
    202

    The change has succeeded. The body is empty.

    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,
          "rejection_reason": 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,
          "rejection_reason": 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)
    rejection_reason (string, read only)

    Will only have a value if the signatory rejected the document, and will contain the message from the signatory to explain rejection. The Document display_options needs to allow the signatory to write a reject reason (allow_reject_reason).

    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)

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface.

    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
    • no_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

    hide_personal_number (boolean)

    Whether the personal number should be hidden in the final PDF verification page and the Evidence Log.

    This is to be used when the document will be distributed to a wider audience, and the personal number of the signatory should not be available in the final document.

    If the signatory has a placed field for their personal number, it will be included in the final PDF. So this solution only works when the field does not have any placements.

    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.

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface.

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

    consent_module (object)

    If present, a section will be shown asking the signatory to answer some questions which must be answered by the signatory with either the positive or the negative option specified.

    The consent_module object has the following properties:

    title (string)

    Section title.

    questions (array)

    All array elements must be of type:

    (object)

    This object has the following properties:

    title (string)

    Question text.

    positive_option (string)
    negative_option (string)
    response (bool)

    Will be present when the party has answered the question. true when the signatory selected the positive response and false when the signatory selected the negative response.

    detailed_description (object)

    Optional additional information to show the signatory.

    The detailed_description object has the following properties:

    title (string)

    Title of the section. Will be shown in a button.

    text (string)

    Explanation of the question. New lines are shown as is.

    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,
          "rejection_reason": 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,
          "rejection_reason": 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)
    rejection_reason (string, read only)

    Will only have a value if the signatory rejected the document, and will contain the message from the signatory to explain rejection. The Document display_options needs to allow the signatory to write a reject reason (allow_reject_reason).

    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)

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface.

    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
    • no_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

    hide_personal_number (boolean)

    Whether the personal number should be hidden in the final PDF verification page and the Evidence Log.

    This is to be used when the document will be distributed to a wider audience, and the personal number of the signatory should not be available in the final document.

    If the signatory has a placed field for their personal number, it will be included in the final PDF. So this solution only works when the field does not have any placements.

    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.

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface.

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

    consent_module (object)

    If present, a section will be shown asking the signatory to answer some questions which must be answered by the signatory with either the positive or the negative option specified.

    The consent_module object has the following properties:

    title (string)

    Section title.

    questions (array)

    All array elements must be of type:

    (object)

    This object has the following properties:

    title (string)

    Question text.

    positive_option (string)
    negative_option (string)
    response (bool)

    Will be present when the party has answered the question. true when the signatory selected the positive response and false when the signatory selected the negative response.

    detailed_description (object)

    Optional additional information to show the signatory.

    The detailed_description object has the following properties:

    title (string)

    Title of the section. Will be shown in a button.

    text (string)

    Explanation of the question. New lines are shown as is.

    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,
      "rejection_reason": 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,
      "hide_personal_number": false,
      "attachments": [],
      "highlighted_pages": [
        {
          "page": 1,
          "file_id": "195173"
        }
      ],
      "api_delivery_url": null,
      "consent_module": {
        "title": "Handling of personal information",
        "questions": [
          {
            "title": "Do you agree for your information to be processed?",
            "positive_option": "Yes, I agree with the processing of my data.",
            "negative_option": "No, I do not agree with any processing of my data.",
            "response": null,
            "detailed_description": {
              "title": "More information",
              "text": "Long extra information regarding the question can go here, and can be separated using newlines.\n\nThis is useful for long terms and conditions that come along with a question."
            }
          }
        ]
      }
    }
    

    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)

    rejection_reason (string, read only)

    Will only have a value if the signatory rejected the document, and will contain the message from the signatory to explain rejection. The Document display_options needs to allow the signatory to write a reject reason (allow_reject_reason).

    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)

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface.

    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
    • no_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

    hide_personal_number (boolean)

    Whether the personal number should be hidden in the final PDF verification page and the Evidence Log.

    This is to be used when the document will be distributed to a wider audience, and the personal number of the signatory should not be available in the final document.

    If the signatory has a placed field for their personal number, it will be included in the final PDF. So this solution only works when the field does not have any placements.

    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.

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface.

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

    consent_module (object)

    If present, a section will be shown asking the signatory to answer some questions which must be answered by the signatory with either the positive or the negative option specified.

    The consent_module object has the following properties:

    title (string)

    Section title.

    questions (array)

    All array elements must be of type:

    (object)

    This object has the following properties:

    title (string)

    Question text.

    positive_option (string)
    negative_option (string)
    response (bool)

    Will be present when the party has answered the question. true when the signatory selected the positive response and false when the signatory selected the negative response.

    detailed_description (object)

    Optional additional information to show the signatory.

    The detailed_description object has the following properties:

    title (string)

    Title of the section. Will be shown in a button.

    text (string)

    Explanation of the question. New lines are shown as is.

    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.