NAV Navbar
Logo
  • Scrive Document API
  • Overview
  • Quick Start
  • Introduction
  • Authentication
  • Errors
  • List of API Calls
  • Monitor
  • Prepare
  • Get
  • Modify
  • Bulk send
  • Signatory attachments
  • Attachment
  • User
  • User Group
  • Access Control
  • Folders
  • Responses
  • Definitions

    • Scrive Document API

    General Information

    Version 2.0.0

    Schemes

    https

    Host & base path

    scrive.com/api/v2/

    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
    2024-03-28 Removed dk_nemid* authentication methods
    2024-03-22 Added Usage limitations subsection to Overview section
    2024-02-28 Added IPs of new egress nodes
    2024-01-18 Added hideZeroSumEidColumns and addSums options to CSV statistic export
    2023-11-03 Added sms_otp authentication to sign
    2023-11-17 Added company_number parameter to setauthenticationtoview, setauthenticationtosign, setauthenticationtoviewarchived endpoints
    2023-11-01 Added dk_mitid_erhverv authentication to view and view archived
    2023-10-17 Added dk_mitid_erhverv authentication to sign
    2023-09-27 Removed API documentation about BankIdent method for Swisscom SRS
    2023-01-30 Added bulk send
    Added "awaiting_start" document status
    2022-12-02 Updated signingdata description
    2022-11-24 Update language codes
    2022-11-17 Updated prolong responses description
    2022-07-25 Added IP address for API testbed
    2022-07-18 Added document_roles_feature_disabled and cannot_use_document_roles_with_forwarding document validation errors
    2022-07-01 Added IP address for API testbed
    2022-05-12 Added onfido authentication with support for provider settings
    2022-05-03 Added authentication to sign provider: smart_id_qes
    2022-04-22 Added /documents/DOC_ID/appendfile endpoint
    2022-04-21 Update URLs for api-explorer
    2022-04-05 attachment/new now returns attachment metadata in the response body
    2022-03-30 Updated API Testbed IP addresses.
    2022-03-01 Added new usagestats/custom endpoint
    2021-12-22 Added authentication to sign itsme
    2021-12-13 Added signatory_status_summary and signatory_status
    2021-12-06 Added documentation for signatory signingdata endpoint
    2021-11-05 Added authentication to sign swisscom_qes_with_srs
    2021-10-11 Added dk_mitid authentication to sign
    Added optional obligatory parameter to setautheticationtoview, setautheticationtosign and setautheticationtoviewarchived endpoints.
    2021-09-29 Add new /usergroups/list endpoint
    2021-08-27 setautheticationtoview endpoint now accepts more parameters
    and allows changing auth-to-view to Freja and Onfido.
    2021-08-23 Updated list of production IP addresses.
    2021-04-30 Added authentication to view provider: freja.
    2021-04-28 Added FullName Signatory Field type.
    2021-04-22 Added missing authentication to view providers: nl_idin.
    Added missing authentication to sign providers: swisscom_qes, verimi_qes.
    Enum values are now displayed in the parameter description.
    2021-04-20 Added onfido_document_check and onfido_document_and_photo_check' toauthentication_method_to_view`
    2021-03-15 Added SignDate Signatory Field type.
    2021-02-19 Added Date Signatory Field type.
    2021-02-18 Added description to signatory fields.
    2021-02-11 Added nl_idin option to authentication_method_to_sign.
    2020-12-14 Added freja option to authentication_method_to_sign.
    2020-10-15 Adding dk_nemid_pid, dk_nemid_cpr and dk_nemid_cvr as authentication to sign/view/view archived
    2020-10-01 Fixed changelog.
    2020-09-02 Added two missing ip-addresses to list of endpoints.
    2020-06-29 Added documentation for custom SMS messages.
    2020-06-15 View Folder endpoint: added recursive parameter and fields: home_for_user, home_for_user_group.
    2020-06-02 Added onfido_document_check and onfido_document_and_photo_check options to authentication_method_to_sign.
    Added missing fi_tupas for authentication_method_to_sign.
    2020-05-08 Added IP address to Environments & IP Addresses.
    2020-04-20 Added nl_idin and fi_tupas to various authentication_method_to_*.
    2020-04-02 Updated endpoint list to include missing ip-addresses.
    2020-03-04 Add user tags API.
    2020-02-21 Change the format of user group tags.
    2020-01-28 Add support for tags in the user group API.
    2020-02-05 Change getbyshortid limit from 24 hours from created/modified time, to 72 hours from created time.
    2019-11-25 Add folder API documentation.
    2019-11-15 Update production IP addresses.
    2019-09-30 Add verimi to authentication_to_view.
    2019-08-15 Add access control API documentation.
    2019-07-19 Add user and user group API documentation.
    2019-04-09 Documented link confirmation delivery.
    2019-04-01 Reordered the changelog - new changes are now on top.
    2019-03-27 Clarified cases where fields can also have a null value.
    Clarified use of authentication_method_to_*
    2019-02-25 Add gettokenforpersonalcredentials endpoint and update getpersonaltoken to accept login_tokens
    2019-02-18 Add monitoring endpoint which was already implemented but missing from this document
    2019-01-03 Add usagestats endpoints
    2018-12-17 Add fi_tupas (Finnish EID) to authentication_method_to_view/authentication_method_to_view_archived
    Add documentation for /documents/trash and /documents/delete bulk endpoints
    Add documentation for authentication_method_to_view_archived
    New signatory role: approver. New Signatory field signatory_role, supercedes is_signatory.
    2018-06-01 Add dk_nemid (Danish NemID) to authentication_to_sign
    2018-04-09 Add a new field to the Signatory JSON: consent_module
    2018-03-29 Fix an omission where no_bankid (Norwegian BankID) was missing as an Authentication to Sign
    2018-03-26 Add rejection_reason to the Signatory JSON and an API endpoint to control template sharing
    2018-02-28 Fix a minor error in the Quick Start guide
    2018-01-29 Add an endpoint to change the email and mobile number of a signatory
    2018-01-08 Add an endpoint to get a sign link as a QR code
    2017-11-15 Custom validations for the SignatoryFieldCustomField are now supported
    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-07-04 Remove a comment about anchoring that was due to a bug, which has now been fixed
    2017-06-08 Add required field to signatory attachments, optional attachments are now possible
    2017-05-15 Add missing company standard signatory field
    2017-03-11 Add dk_nemid (Danish NemID) to authentication_to_view
    2017-01-28 Documentation of removepages API call
    2017-01-17 Add JSON fields related to highlighting
    2016-12-17 New optional no_attachments parameter for the forward API call
    2016-10-27 Small improvements to documentation following internal and customer feedback
    2016-10-14 Pre-release of Scrive Document API Version 2

    Environments & IP Addresses

    This section provides details on the IP addresses used by the Scrive Service. You may want to add these addresses to your firewalls' allowlist for outgoing traffic but more importantly for incoming traffic from Scrive eSign when using callbacks.

    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 IP addresses that may be used as endpoints to and from our API testbed systems are:

    API Explorer

    An interactive API Explorer is available for both environments:

    This is a 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.

    Usage limitations

    TLS Secure Renegotiation

    To be able to establish a secure connection with the Scrive servers using TLS versions prior to 1.3, your client software needs to support TLS Secure Renegotiation as described in RFC 5746.

    TLS 1.3 does not support renegotiation by design.

    Iframe embedding disabled

    To enhance the security of our service, the ability to embed Scrive Online using iframes is disabled. This is done to mitigate the risk of Cross-Site Scripting (XSS) vulnerabilities and clickjacking attacks and ensure the integrity of signed Scrive documents.

    If you have previously integrated Scrive using iframes, it is recommended to migrate to alternative methods that do not rely on iframing. For instance, consider redirecting users to the Scrive Online page, opening it in a new tab or window, or utilizing the branded domain feature.

    POST request data as URL parameters

    This API accepts POST request data as URL-encoded form-data. While the HTTP protocol does not restrict sending POST data as URL parameters, it is not recommended to send sensitive data this way. Instead, it should be sent as body parameters with application/x-www-form-urlencoded or multipart/form-data content type. POST data sent as an URL parameters will be ignored.

    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 the API. 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 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 "is_template" field to be true. This cannot be reversed once set, and templates cannot directly 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.

    For callbacks to be triggered, you need to set the api_callback_url value on the Document. You can also trigger callbacks manually using the callback API call (this call has no effect if the api_callback_url is not set).

    For certain use cases it is possible to instead have a "User callback scheme" defined. You will need to contact us to set this up, and setting callbacks on Documents is the preferred solution.

    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.

    If you are experiencing issues, it is worth checking the TLS/SSL certificate configuration on the server which is receiving the callbacks. This is a common cause of failure.

    If you would like to test your server, the following resource may be useful:

    Instructions for properly configuring a certificate on many kinds of servers can be found at the following location:

    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 the appropriate values.

    Or, if you are using the login_token method:

    curl -X POST 'https://{server_address}/api/v2/getpersonaltoken' \
  --data-urlencode 'login_token={login_token}'

    Replacing {server_address}, {login_token} to the appropriate values.

    These two methods will both 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.

    There are two ways to use this endpoint. One is to provide the username and password of the user you are creating the personal access credentials for. The other is to provide a login_token. These are temporary tokens created by the gettokenforpersonalcredentials endpoint. These are demonstrated in the sidebar.

    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, DOC_SEND and FULL_ACCESS.

    FULL_ACCESS can be used instead of all the other privileges and their combinations.

    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$
, "error_details": $error_details$
}

    For example:

    {
  "error_type": "resource_not_found"
, "error_message": "Document not found."
, "http_code": 404
, "error_details": {
    "document_id": "$id"
  }
}

    error_details property can be arbitrary JSON value unless endpoint documentation specifies otherwise. This property is meant to to aid developers/API integrators to figure out what caused an error and it's not meant to be interpreted by API integration.

    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

    Monitor

    GET /api/v2/monitor/status

    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}/appendfile

    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}/canbestarted

    GET /api/v2/documents/validation_errors

    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/{document_id}/{signatory_id}/signingdata

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

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

    POST /api/v2/documents/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}/setauthenticationtoviewarchived

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

    POST /api/v2/documents/templates/setsharing

    Bulk send

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

    POST /api/v2/documents/{document_id}/bulk_send/canbestarted

    GET /api/v2/documents/bulk_send/{bulk_send_id}

    GET /api/v2/documents/bulk_send

    Signatory attachments

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

    Attachment

    GET /api/v2/attachments/list

    GET /api/v2/attachments/{attachment_id}/download/{filename}

    POST /api/v2/attachments/new

    POST /api/v2/attachments/delete

    POST /api/v2/attachments/setsharing

    User

    POST /api/v2/loginandgetsession

    POST /api/v2/gettokenforpersonalcredentials/{user_id}

    POST /api/v2/2fa/setup

    POST /api/v2/2fa/confirm

    POST /api/v2/2fa/disable

    POST /api/v2/isuserdeletable

    POST /api/v2/deleteuser

    GET /api/v2/dataretentionpolicy

    POST /api/v2/dataretentionpolicy/set

    GET /api/v2/usertags

    POST /api/v2/usertags/update

    GET /api/v2/usagestats/days

    GET /api/v2/usagestats/months

    POST /api/v2/signup

    User Group

    POST /api/v2/usergroups/create

    GET /api/v2/usergroups/{user_group_id}

    POST /api/v2/usergroups/{user_group_id}/update

    POST /api/v2/usergroups/{user_group_id}/delete

    GET /api/v2/usergroups/{user_group_id}/contact_details

    POST /api/v2/usergroups/{user_group_id}/contact_details/update

    POST /api/v2/usergroups/{user_group_id}/contact_details/delete

    GET /api/v2/usergroups/{user_group_id}/settings

    POST /api/v2/usergroups/{user_group_id}/settings/update

    POST /api/v2/usergroups/{user_group_id}/settings/delete

    GET /api/v2/usergroups/{user_group_id}/users

    GET /api/v2/usergroups/list

    Access Control

    GET /api/v2/getuserroles/{user_id}

    GET /api/v2/accesscontrol/roles/{role_id}

    POST /api/v2/accesscontrol/roles/add

    POST /api/v2/accesscontrol/roles/{role_id}/delete

    Folders

    GET /api/v2/folders/{folder_id}

    POST /api/v2/folders/create

    POST /api/v2/folders/{folder_id}/update

    POST /api/v2/folders/{folder_id}/delete

    GET /api/v2/folders/{folder_id}/list

    Monitor

    Get the system status

    GET /api/v2/monitor/status

    Check the system status, no API credentials required.

    Responses

    Code Description
    200

    A simple JSON response with the system status: {"status":"ok"}

    Any other response implies there are system issues. We may add more fields and more details in the future.

    Prepare

    New document

    POST /api/v2/documents/new

    Example

    curl -X POST 'https://{server_address}/api/v2/documents/new' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    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}

    Example

    curl -X POST 'https://{server_address}/api/v2/documents/newfromtemplate/${document_id}' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    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

    Example

    curl -X POST 'https://{server_address}/api/v2/documents/${document_id}/update' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"' \
  --data-urlencode 'document={ "id":"${document_id}", "parties": [{}] }' \
  --data-urlencode 'document_id=${document_id}'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    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.

    Append a new PDF file to the main PDF file

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

    Append the provided PDF file to the main PDF file for a document in Preparation.

    If document had no main file set, this will be equivalent to simply setting the main PDF file of the document to the provided one. See {document_id}/setfile.

    A note about anchors: Similarly to {document_id}/setfile behavior, anchors are only recalculated if a main file was already set on the document. 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
    required

    The PDF file to be appended to the main file for the document.

    If document doesn't have a main file set, this will become then new main file.

    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

    A document uploaded by the author that the signatory parties must review in order to complete the signing process.

    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 (note that the order of already set attachments can still be changed).

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

    Note that, if this is set to true, the order of attachments will be:

    1. Existing, non-overwritten attachments in their current order, followed by
    2. New and overwritten attachments in the order they were given.

    This means that first setting the attachments to A, B, C, D, and then calling setattachments (with incremental set to true) with the attachments E, F, A, B, will lead to the final order: C, D, E, F, A, B.

    If the order of attachments is important to you, don't use incremental: true. Instead, explicitly specify all the attachments in your payload.

    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

    Example

    curl -X POST 'https://{server_address}/api/v2/documents/${document_id}/start' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"' \
  --data-urlencode 'document_id=${document_id}'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    Start the signing process for a document in preparation.

    OAuth Privileges required: DOC_SEND

    Error response example

    {
  "error_type": "document_state_error",
  "error_message": "Document is a template and can't be started.",
  "http_code": 409,
  "error_details": {
    "document_id": "97",
    "explanations": [ // Human readable explanation not intended for presentation to user
      "Document is a template and can't be started.",
      "Document is missing the main PDF.",
      "Invitation delivery for participant #2 requires valid \"email\" field.",
      "Value of \"email\" field for participant #2 is obligatory for sender and can't be empty."
    ],
    "errors": [
      {
        "details": {},
        "type": "document_is_template"
      },
      {
        "details": {},
        "type": "missing_document_file"
      },
      {
        "details": {
          "field": {
            "type": "email"
          },
          "signatory_id": "198"
        },
        "type": "invalid_invitation_delivery_info"
      },
      {
        "details": {
          "field": {
            "type": "email"
          },
          "signatory_id": "198"
        },
        "type": "field_obligatory_for_sender"
      }
    ]
  }
}

    Parameters

    Parameter Description Type In

    document_id
    required

    Unique identifier for a document. Will not change.

    integer
    int64

    		path

    strict_validations
    optional

    default: false

    Whether to include new field validation errors (invalid_value, field_obligatory_for_sender).

    The purpose of this parameter is to provide backward compatibility, as the introduction of additional validations could break existing integrations, but if you're just integrating this call, we recommend to enable this option.

    bool

    		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
    • document_object_version_mismatch
    • document_state_error with error messages:
      • Unexpected document status
      • One of the error messages in the error_details.explanations field.

    More information about individual errors in Document validation error.

    Get

    Can the signing process be started?

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

    Example

    curl -X GET 'https://{server_address}/api/v2/documents/${document_id}/canbestarted' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    Find out whether the signing process can be started. If it cannot, return a list of reasons.

    OAuth Privileges required: DOC_SEND

    Response example

    {
  "can_start": false,
  "errors": [
    {
      "details": {},
      "type": "missing_document_file"
    },
    {
      "details": {
        "field": {
          "type": "personal_number"
        },
        "signatory_id": "199"
      },
      "type": "invalid_authentication_to_view_info"
    },
    {
      "details": {
        "field": {
          "type": "first_name"
        },
        "signatory_id": "200"
      },
      "type": "invalid_authentication_to_view_info"
    },
    {
      "details": {
        "field": {
          "type": "last_name"
        },
        "signatory_id": "200"
      },
      "type": "invalid_authentication_to_view_info"
    },
    {
      "details": {
        "field": {
          "type": "mobile"
        },
        "signatory_id": "199"
      },
      "type": "invalid_invitation_delivery_info"
    },
    {
      "details": {
        "field": {
          "type": "mobile"
        },
        "signatory_id": "199"
      },
      "type": "field_obligatory_for_sender"
    },
    {
      "details": {
        "field": {
          "type": "personal_number"
        },
        "signatory_id": "199"
      },
      "type": "field_obligatory_for_sender"
    },
    {
      "details": {
        "field": {
          "type": "first_name"
        },
        "signatory_id": "200"
      },
      "type": "field_obligatory_for_sender"
    },
    {
      "details": {
        "field": {
          "type": "last_name"
        },
        "signatory_id": "200"
      },
      "type": "field_obligatory_for_sender"
    }
  ]
}

    Parameters

    Parameter Description Type In

    document_id
    required

    Unique identifier for a document. Will not change.

    integer
    int64

    		path

    strict_validations
    optional

    default: false

    Whether to include new field validation errors (invalid_value, field_obligatory_for_sender).

    The purpose of this parameter is to provide backward compatibility, as the introduction of additional validations could break existing integrations, but if you're just integrating this call, we recommend to enable this option.

    bool

    		url

    Responses

    Code Description
    200
    • "can_start": true if the signing process can be started.
    • "can_start": false otherwise, along with a list of errors.

    More information about individual errors in Document validation error.
    409
    • document_object_version_mismatch
    • document_state_error with error messages:
      • Unexpected document status

    Validation error templates

    GET /api/v2/documents/validation_errors

    Lists user presentable templates for document validation errors.

    Example

    # No authentication is required
curl -X GET 'https://{server_address}/api/v2/documents/validation_errors'

    Should be used together with GET /api/v2/documents/{document_id}/canbestarted response and/or POST /api/v2/documents/{document_id}/start error response to present an error message in user's language.

    Whenever certain property in details property of Document Validation Error is present, there's a related substitution variable of the same or very similar (signatory × signatory_id) name in the template, which should be replaced with information based on content of that property details including highlighting (substituting with something like «Email» or <b>Mobile</b>).

    For example {signatory} should be replaced by participant's name or email if one of them is available (non-empty), otherwise use identification using participant order (e.g. <b>#2</b> for second participant).

    The table of substitution variables and their corresponding error properties is as follows:

    Error property Substitution variable
    attachment_name attachment_name
    authentication_method authentication_method
    delivery_method delivery_method
    field field
    signatory_id signatory
    recipient_index recipient_index
    limit limit

    Example

    {
  "approver_cannot_have_field_placement":
    "Approver {signatory} can't have field placements.",
  "approver_cannot_have_non_standard_sign_authentication":
    "Approver {signatory} can't have non-standard authentication to sign.",
  "authentication_to_sign_method_disabled":
    "Participant {signatory} can't use authentication to sign {authentication_method}. This feature is disabled.",
  "authentication_to_view_archived_method_disabled":
    "Participant {signatory} can't use authentication to view archived {authentication_method}. This feature is disabled.",
  "authentication_to_view_method_disabled":
    "Participant {signatory} can't use authentication to view {authentication_method}. This feature is disabled.",
  "author_attachments_feature_disabled":
    "Document can't use author attachments. This feature is disabled.",
  "author_cannot_be_approver":
    "Document author can't be an approver.",
  "author_cannot_use_forwarding":
    "Document author can't use forwarding.",
  "bulk_send_empty_recipient_list":
    "Can't start document using bulk send. The recipient list is empty.",
  "bulk_send_feature_disabled":
    "Can't use bulk send. This feature is disabled.",
  "bulk_send_multiple_matching_fields":
    "Can't start document using bulk send. Field name {field} is ambiguous (can match multiple fields).",
  "bulk_send_no_matching_field":
    "Can't start document using bulk send. Field name {field} doesn't match any field in the document.",
  "bulk_send_no_matching_signatory_found":
    "Can't start document using bulk send. Target signatory wasn't found in the document.",
  "bulk_send_non_text_field":
    "Can't start document using bulk send. Field name {field} corresponds to non-text field.",
  "bulk_send_target_signatory_is_an_author":
    "Can't start document using bulk send. Target signatory for bulk send can't be the author of the document.",
  "bulk_send_too_many_recipients":
    "Can't start document using bulk send. The recipient limit ({limit}) was exceeded.",
  "cannot_use_document_roles_with_forwarding":
    "Participant {signatory} can't use document roles with forwarding enabled. These options are mutually exclusive.",
  "confirmation_delivery_method_disabled":
    "Participant {signatory} can't use confirmation delivery {delivery_method}. This feature is disabled.",
  "custom_sms_text_feature_disabled":
    "Document can't use custom SMS text. This feature is disabled.",
  "document_is_template":
    "Document is a template and can't be started.",
  "document_roles_feature_disabled":
    "Participant {signatory} can't use document roles. This feature is disabled.",
  "field_obligatory":
    "Value of {field} field for participant {signatory} is obligatory and can't be empty.",
  "field_obligatory_for_sender":
    "Value of {field} field for participant {signatory} is obligatory for sender and can't be empty.",
  "forwarding_feature_disabled":
    "Participant {signatory} can't use forwarding. This feature is disabled.",
  "invalid_authentication_to_sign_info":
    "Authentication to sign for participant {signatory} requires valid {field} field.",
  "invalid_authentication_to_view_archived_info":
    "Authentication to view archived for participant {signatory} requires valid {field} field.",
  "invalid_authentication_to_view_info":
    "Authentication to view for participant {signatory} requires valid {field} field.",
  "invalid_confirmation_delivery_info":
    "Confirmation delivery for participant {signatory} requires valid {field} field.",
  "invalid_date_config":
    "Date configuration of {field} field for participant {signatory} is not valid.",
  "invalid_invitation_delivery_info":
    "Invitation delivery for participant {signatory} requires valid {field} field.",
  "invalid_notification_delivery_info":
    "Notification delivery for participant {signatory} requires valid {field} field.",
  "invalid_value":
    "Value of {field} field for participant {signatory} is not valid.",
  "invitation_delivery_method_disabled":
    "Participant {signatory} can't use invitation delivery {delivery_method}. This feature is disabled.",
  "missing_document_file":
    "Document is missing the main PDF.",
  "no_signing_party":
    "Document has no signing party.",
  "notification_delivery_method_disabled":
    "Participant {signatory} can't use notification delivery {delivery_method}. This feature is disabled.",
  "qes_incompatible_signing_method":
    "Signatory {signatory} has unexpected authentication method. All signatories must have the same authentication to sign when QES is used.",
  "qes_missing_attachment":
    "Attachment {attachment_name} is missing. QES requires all attachments to be present when starting the document.",
  "qes_signatory_field_cannot_be_editable_by_signatory":
    "There is a visible field that is set to be editable by {signatory}, but only the author is allowed to edit fields when QES signing is used.",
  "qes_signatory_field_cannot_be_editable_in_signview":
    "There is a visible field assigned to {signatory} whose value is editable in signview, but visible fields can't be edited after the document is started when QES signing is used.",
  "qes_signatory_non_author_field":
    "There is a field assigned to be filled by {signatory}, but only the author is allowed to fill fields when QES signing is used.",
  "signatory_attachment_feature_disabled":
    "Document can't use signatory attachments. This feature is disabled."
}

    Responses

    Code Description
    200

    A JSON object with mapping from error type to text template.

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

    The resource was not found. A document matching id document_id was not found

    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 within the last 72 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 within the last 72 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
    409

    The resource was in an unexpected state. A document matching short id short_document_id was found in an unexpected state

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

    Get document signing data

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

    Gets information about whether a signatory for a document has signed yet or not.

    OAuth Privileges required: FULL_ACCESS

    Response example (not signed and no authentication method selected for signing)

    {
  "has_signed": false,
  "provider": "standard"
}

    Response example (signed without any authentication method)

    {
  "has_signed": true,
  "provider": "standard"
}

    Response example (signed with Norwegian BankID)

    {
  "has_signed": true,
  "no_bankid_data": {
    "signature": "PD94bWwgdm...",
    "signatory_name": "John Doe",
    "signatory_date_of_birth": "1921-10-03",
    "signatory_mobile": null,
    "signatory_personal_number": "03102106309"
  },
  "provider": "no_bankid",
  "eid_hub_transaction_id": "14619149-cdcc-48dd-aebe-aa2cfb8e87f2"
}

    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

    A JSON object containing information about the signing status of the signatory for the document.

    The response will contain provider-dependent data about the signatory: The name of the signatory is always included in this data; also information such as email, mobile number, and personal number could be included here, depending on the provider used for the signature.

    List documents

    GET /api/v2/documents/list

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

    Note that listing a large number of documents frequently is discouraged and in the future will be subject to API rate limiting.

    Under most circumstances it is better to use callbacks. Once set up, your systems will be notified whenever a document undergoes an important state change.

    In the unlikely event that callbacks are insufficient for your integration and you do need to call the list API periodically please make your sure your polling strategy is smart. Do not poll more often than necessary, and if there are no changes between subsequent calls, use an exponential backoff.

    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"] } ]

    Note that documents with "awaiting_start" status won't be listed, unless they are explicitly specified by status filter.

    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 optional 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 in the browser.

    OAuth Privileges required: DOC_CHECK

    Parameters

    Parameter Description Type In

    document_id
    required

    Unique identifier for a document. Will not change.

    integer
    int64

    		path

    filename
    optional

    Optional filename parameter.

    string

    		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 optional 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 in the browser.

    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.

    Enum: cs, da, de, el, en, es, et, fi, fr, hu, is, it, lt, lv, nl, no, pl, pt, sv

    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

    Cannot 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 is pending or 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 365, such that the new timeout is not later than 365 days from now.
    409

    The document is neither pending nor has it timed out. Only timed out or pending 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

    Documents that are pending or awaiting start cannot be trashed or deleted.

    Move one or more documents to Trash

    POST /api/v2/documents/trash

    Move one or more documents to Trash.

    OAuth Privileges required: DOC_SEND

    Parameters

    Parameter Description Type In

    document_ids
    required

    List of document IDs to trash.

    string
    application/json

    		formData

    Responses

    Code Description
    200

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

    Documents that are pending or awaiting start cannot 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

    Documents that are pending or awaiting start cannot be trashed or deleted.

    Delete one or more documents

    POST /api/v2/documents/delete

    Delete one or more documents that are in Trash.

    OAuth Privileges required: DOC_SEND

    Parameters

    Parameter Description Type In

    document_ids
    required

    List of document IDs to delete.

    string
    application/json

    		formData

    Responses

    Code Description
    200

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

    Documents that are pending or awaiting start cannot 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 cannot 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
    required

    Must be of type Authentication to view with settings.

    This parameter overrides authentication_type parameter, making it optional. Either one of those two has to be provided.

    object
    application/json

    		formData

    authentication_type
    required

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

    This paramater is deprecated in favor of authentication parameter. Either one of those two has to be provided.

    Enum: standard, sms_pin, dk_mitid, dk_mitid_erhverv, fi_tupas, nl_idin, no_bankid, se_bankid, verimi, onfido_document_check, onfido_document_and_photo_check, freja, verimi

    string

    		formData

    personal_number
    optional

    Must be of type Authentication field setting.

    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.

    force_obligatory parameter currently does not apply to any authentication method.

    object
    application/json

    		formData

    mobile_number
    optional

    Must be of type Authentication field setting.

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

    Currently SMS PIN and Norwegian BankID methods use this. For Norwegian BankID, the number must be valid Norwegian mobile number.

    force_obligatory parameter currently does not apply to any authentication method.

    object
    application/json

    		formData

    firstname
    optional

    Must be of type Authentication field setting.

    If the authentication_type requires a name, and the signatory doesn't have one set already, then it must be provided and valid for the chosen authentication_type.

    Currently only Onfido uses this.

    force_obligatory parameter currently does not apply to any authentication method.

    object
    application/json

    		formData

    lastname
    optional

    Must be of type Authentication field setting.

    If the authentication_type requires a name, and the signatory doesn't have one set already, then it must be provided and valid for the chosen authentication_type.

    Currently only Onfido uses this.

    force_obligatory parameter currently does not apply to any authentication method.

    object
    application/json

    		formData

    email
    optional

    Must be of type Authentication field setting.

    If the authentication_type requires an email, and the signatory doesn't have one set already, then it must be provided and valid for the chosen authentication_type.

    Currently only Freja uses this.

    force_obligatory parameter currently does not apply to any authentication method.

    object
    application/json

    		formData

    company_number
    optional

    Must be of type Authentication field setting.

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

    force_obligatory parameter currently does not apply to any authentication method.

    object
    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

    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.
    • signatory_state_error: Signatory does not have a valid personal number for the authentication method and you did not provide one.
    • signatory_state_error: The personal number you provided is not valid for the authentication method.
    • signatory_state_error: Signatory does not have a valid mobile number set for the authentication method and you did not provide one."
    • signatory_state_error: The mobile number you provided is not valid for the authentication method.
    • signatory_state_error: Signatory does not have a valid email set for the authentication method and you did not provide one."
    • signatory_state_error: The email you provided is not valid for the authentication method.
    • signatory_state_error: Signatory does not have a valid first name set for the authentication method and you did not provide one.
    • signatory_state_error: The first name you provided is not valid for the authentication method.
    • signatory_state_error: Signatory does not have a valid last name set for the authentication method and you did not provide one.
    • signatory_state_error: The last name you provided is not valid for the authentication method.

    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
    required

    Must be of type Authentication to sign with settings.

    This parameter overrides authentication_type parameter, making it optional. Either one of those two has to be provided.

    object
    application/json

    		formData

    authentication_type
    required

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

    This paramater is deprecated in favor of authentication parameter. Either one of those two has to be provided.

    Enum: standard, sms_pin, sms_otp, dk_mitid, dk_mitid_erhverv, fi_tupas, freja, nl_idin, no_bankid, onfido_document_and_photo_check, onfido_document_check, se_bankid, swisscom_qes, swisscom_qes_with_srs, verimi_qes, itsme, smart_id_qes

    string

    		formData

    personal_number
    optional

    Must be of type Authentication field setting.

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

    force_obligatory parameter currently applies only to dk_mitid.

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

    object
    application/json

    		formData

    mobile_number
    optional

    Must be of type Authentication field setting.

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

    force_obligatory parameter currently does not apply to any authentication 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).

    object
    application/json

    		formData

    company_number
    optional

    Must be of type Authentication field setting.

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

    force_obligatory parameter currently applies only to dk_mitid_erhverv.

    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 company_number field value set for the signatory will not be changed. However, if a company_number SignatoryField does not yet exist, one will be added to the signatory (with empty string as value).

    object
    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

    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.

    Set the signatory authentication-to-view-archived method

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

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

    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.

    For details refer to Set the signatory authentication-to-view method.

    OAuth Privileges required: DOC_SEND

    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.

    Bulk send

    Start the signing process using a bulk send

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

    Example

    curl -X POST 'https://{server_address}/api/v2/documents/${document_id}/bulk_send/start' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"' \
  --data-urlencode 'document_id=${document_id}' \
  --data-urlencode 'target_signatory_id=${signatory_id}' \
  --data-urlencode 'name=Example bulk send title' \
  --data-urlencode 'recipients=[{"email": "recipient@example.org"}, {"email": "recipient.too@example.org"}]'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    Start the signing process for a document in preparation, as an individual document for each recipient.

    Depending on the number of recipients, the call to this endpoint can take a few seconds to finish, so it's appropriate to provide some visual feedback about the operation in progress.

    OAuth Privileges required: DOC_SEND

    Parameters

    Parameter Description Type In

    document_id
    required

    Unique identifier for a document. Will not change.

    integer
    int64

    		path

    target_signatory_id
    required

    ID of the targeted signatory in the document.

    string

    		formData

    name
    optional

    Label for the bulk send. Only used for presentation purposes.

    If omitted, the original document name will be used.

    string

    		formData

    recipients
    required

    List of recipients, which will replace the targeted signatory.

    Items must be of type Bulk send recipient info

    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

    Details about bulk send and its progress.

    See Bulk send descriptor.
    409
    • document_object_version_mismatch
    • document_state_error with error messages:
      • Unexpected document status
      • One of the error messages in the error_details.explanations field.

    More information about individual errors in Document validation error.

    Can the signing process be started with given bulk send parameters?

    POST /api/v2/documents/{document_id}/bulk_send/canbestarted

    Example

    curl -X POST 'https://{server_address}/api/v2/documents/${document_id}/bulk_send/canbestarted' \
  -H 'Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="${apitoken}",oauth_token="${accesstoken}",oauth_signature="${apisecret}&${accesssecret}"' \
  --data-urlencode 'document_id=${document_id}' \
  --data-urlencode 'target_signatory_id=${signatory_id}' \
  --data-urlencode 'recipients=[{"email": "recipient@example.org"}, {"email": "recipient.too@example.org"}]'

    The above example uses personal access credentials (see -H option), but can be easily updated to use OAuth.

    Find out whether the signing process can be started using bulk send. If it cannot be started, returns a list of reasons.

    With the exception of this endpoint accepting only POST requests and requiring some extra parameters, the behavior is almost identical to GET /api/v2/documents/{document_id}/canbestarted.

    One notable difference is that strict validations are always enabled for this endpoint.

    OAuth Privileges required: DOC_SEND

    Parameters

    Parameter Description Type In

    document_id
    required

    Unique identifier for a document. Will not change.

    integer
    int64

    		path

    target_signatory_id
    required

    ID of the targeted signatory in the document.

    string

    		formData

    recipients
    required

    List of recipients, which will replace the targeted signatory.

    Items must be of type Bulk send recipient info

    string
    application/json

    		formData

    Responses

    Code Description
    200
    • "can_start": true if the signing process can be started.
    • "can_start": false otherwise, along with a list of errors.

    Unlike the GET /api/v2/documents/{document_id}/canbestarted endpoint, we also provide recipient_index in the error details, which refers to an index of the recipients parameter list.

    More information about individual errors in Document validation error.
    409
    • document_object_version_mismatch
    • document_state_error with error messages:
      • Unexpected document status

    Get a description and status of a bulk send

    GET /api/v2/documents/bulk_send/{bulk_send_id}

    Fetches the JSON data of a bulk send with the given bulk_send_id.

    Parameters

    Parameter Description Type In

    bulk_send_id
    required

    Unique identifier for a bulk send.

    integer
    int64

    		path

    Responses

    Code Description
    200

    Details about the bulk send and its progress.

    See Bulk send descriptor.
    404

    The resource was not found. No bulk send matching the bulk_send_id was found.

    List recent bulk sends

    GET /api/v2/documents/bulk_send

    Fetch a list of recently started bulk sends. Bulk sends are available for a month before expiring.

    Responses

    Code Description
    200

    Lists basic information about recent bulk sends.

    See Bulk send list descriptor.

    Signatory attachments

    Set/Unset file to signatory attachment

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

    Set/Unset a file to a particular signatory attachment. This operation does not allow you to request a signatory attachment from a signatory, only to set/unset files to already requested signatory attachment. To request signatory attachment from signatory, this has to be done in preparation phase of the document by updating the respective document metadata.

    This operation behaves as 'Set' when the attachment parameter is sent, otherwise it behaves as 'Unset'. Furthermore, depending on whether fileID parameter is sent, it either unsets one or all of the files which have been previously set to a signatory attachment.

    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

    name
    required

    The name of the attachment.

    Must match an attachment name as requested by the document author.

    string

    		formData

    attachment
    optional

    Set a file to signatory attachment. If provided, this is the file to set as the attachment.

    If not provided, this operation behaves as either unset all files/unset one file. If fileID is set then it unsets one file. If fileID is NOT set then it unsets ALL files.

    file
    application/pdf image/jpeg image/png

    		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

    fileID
    optional

    This identifies one particular file.

    string

    		formData

    Responses

    Code Description
    200

    The document metadata as a JSON.
    400

    This status code is returned when:

    • There is no attachment with that fileID for the signatory.
    • There is no attachment with that name for the signatory.

    Attachment

    List

    GET /api/v2/attachments/list

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

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    domain
    optional

    Domain in which to search.

    The list always contains the attachments of the user. If domain is set to All, it will also return the attachments shared within the company.

    string
    string

    		query

    filter
    optional

    default: []

    List of filtering options.

    You can supply a list of filtering options to apply. Only attachments 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 Attachment List Filter, for example:

    [ { "filter_by":"text", "text":"some keywords" } ]

    string
    application/json

    		query

    sorting
    optional

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

    List of sorting options.

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

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

    Must be of type Attachment List Sorting.

    string
    application/json

    		query

    offset
    optional

    default: 0

    Pagination parameter. How many items to skip from the beginning. Server may cap to a lower value. Default value may change without notice.

    integer
    int32

    		query

    limit
    optional

    default: 1000

    Pagination parameter. Maximum number of items to return. Server may cap to a lower value. Default value may change without notice.

    integer
    int32

    		query

    Responses

    Code Description
    200

    A JSON object containing an array of attachments.

    Download

    GET /api/v2/attachments/{attachment_id}/download/{filename}

    Get the attachment's PDF file.

    The optional 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 in the browser.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    attachment_id
    required

    Identifier for the attachment.

    integer
    int64

    		path

    filename
    optional

    Optional filename parameter.

    string

    		path

    Responses

    Code Description
    200

    The attachment's PDF file.

    Create

    POST /api/v2/attachments/new

    Create a new attachment.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    title
    optional

    Title of the attachment. If not present, the title will be taken from the file name.

    string

    		formData

    file
    required

    The PDF to use for the attachment.

    file
    application/pdf

    		formData

    Responses

    Code Description
    201

    The attachment has been added. The body is a JSON object representing the created attachment.

    Delete

    POST /api/v2/attachments/delete

    Delete the specified attachments.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    attachment_ids
    required

    List of attachment IDs of attachments to delete.

    string
    application/json

    		formData

    Responses

    Code Description
    202

    The change has succeeded. The body is empty.

    Share or unshare

    POST /api/v2/attachments/setsharing

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

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    attachment_ids
    required

    List of attachment IDs of attachments 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.

    User

    Login and get session

    POST /api/v2/loginandgetsession

    Login as a user by using their OAuth tokens.

    The tokens have to be acquired using getpersonaltoken endpoint, see Personal Access Credentials.

    Using this endpoint, you can create a link which redirects the user directly to any page on the Scrive eSign system without going through the login page.

    This can be used to create a better user experience for your integration.

    The call returns a session id, which can be used to create a link such as: https://scrive.com/loginwithredirect?session_id=SESSION_ID&url=PATH_INSIDE_SCRIVE_COM.

    This link will redirect the user to PATH_INSIDE_SCRIVE_COM. Remember that all URL query parameters must be URL encoded!

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    personal_token
    required

    Must be of type OAuthAuthorization

    string
    application/json

    		formData

    Responses

    Code Description
    200

    JSON response, for example: { "session_id" : "12345-a2510867954321d0" }

    The string format may change at any time, please treat it as an opaque string.

    Get temporary login_token for a user

    POST /api/v2/gettokenforpersonalcredentials/{user_id}

    Generate a temporary login_token which can be used with getpersonaltoken to get valid OAuth credentials for that user. The endpoint also returns a base64-encoded PNG image of a QR code. This QR code also contains the login_token embedded in a simple JSON structure. The only purpose of the JSON is to allow the potential for versioning in future.

    This feature is generally for use with Scrive mobile applications and will be supported in an upcoming relase.

    Parameters

    Parameter Description Type In

    minutes
    optional

    default: 5

    How many minutes the login_token should be valid for (maximum of 30).

    integer

    		formData

    Responses

    Code Description
    200

    Returns a JSON containing login_token, qr_code and expiration_time.

    Setup 2FA

    POST /api/v2/2fa/setup

    If already activated, returns true, else triggers QR code generation

    Responses

    Code Description
    200

    A JSON with the twofactor_active flag and (if not activated yet) a qr_code. If present, the field qr_code contains a base64-encoded image of the QR code.

    Confirm 2FA

    POST /api/v2/2fa/confirm

    Activates 2-factor-authentication if 2-factor code from QR code is valid

    Parameters

    Parameter Description Type In

    totp
    required

    2-factor code

    string

    		formData

    Responses

    Code Description
    200

    A JSON with the twofactor_active flag and totp_valid flag
    400

    2-factor code from QR code is invalid

    Disable 2FA

    POST /api/v2/2fa/disable

    Disables 2-factor-authentication

    Responses

    Code Description
    200

    A JSON with the twofactor_active flag

    Is user deletable?

    POST /api/v2/isuserdeletable

    Returns an object with boolean flag

    Responses

    Code Description
    200

    A JSON with the deletable flag and (if not deletable) a reason

    Delete user

    POST /api/v2/deleteuser

    undefined

    Parameters

    Parameter Description Type In

    email
    required

    User's email

    string

    		formData

    Responses

    Code Description
    200

    The user was deleted successfully. The body is empty
    400

    Email parameter isn't provided or doesn't match the user's email

    Get data retention policies

    GET /api/v2/dataretentionpolicy

    Returns an object with user and company data detention policies

    Responses

    Code Description
    200

    An object with data retention policies properties.

    Set data retention policies

    POST /api/v2/dataretentionpolicy/set

    Returns an object with user and company data detention policies

    Parameters

    Parameter Description Type In

    data_retention_policy
    required

    Must be of type DataRetentionPolicy

    object
    application/json

    		formData

    Responses

    Code Description
    200

    The data retention policy has been updated. The body is empty.

    Get tags

    GET /api/v2/usertags

    Returns tags attached to the user

    Responses

    Code Description
    200

    User defined set of name/value pairs.

    Each tag must have {"name": "some-name", "value": "some-value"} format. In the responses value is always a string. In the requests you can also provide null value to delete a tag. Other value types lead to 400 Bad Request response.

    Update tags

    POST /api/v2/usertags/update

    Updates tags attached to the user.

    Parameters

    Parameter Description Type In

    tags
    required

    default:

    Must be of type Tags

    array
    application/json

    		formData

    Responses

    Code Description
    200

    The tags have been updated. The body is empty.

    Get usage stats for days

    GET /api/v2/usagestats/days

    Retrieve usage statistics for the last 30 days

    Parameters

    Parameter Description Type In

    userGroupID
    optional

    The user group ID for which to get usage statistics. This is only used when withCompany is true. This user group must be a child user group of the user's group. If this parameter is omitted, the default is the user group of the API user.

    integer

    		query

    withCompany
    optional

    default: false

    Boolean flag for including a summary of the company statistics in the response.

    boolean

    		query

    recursive
    optional

    default: false

    Boolean flag for recursively including child user group statistics in the response. This flag is only used when withCompany is true.

    boolean

    		query

    includeZeroRecords
    optional

    default: false

    Boolean flag that controls whether to include days or months without statistics in the response.

    boolean

    		query

    includeUsersWithoutStatistics
    optional

    default: false

    Boolean flag that controls whether to include users without statistics in the response.

    This is only possible to use when statsFormat is "csv".

    boolean

    		query

    hideZeroSumEidColumns
    optional

    default: false

    Boolean flag that controls whether to hide columns of chargeable items referring to eID usage that sum up to zero.

    This is only possible to use when statsFormat is "csv".

    boolean

    		query

    addSums
    optional

    default: false

    Boolean flag that controls whether to add row with sums of chargeable items. This will be the first row after the header row.

    This is only possible to use when statsFormat is "csv".

    boolean

    		query

    statsFormat
    optional

    default: json

    The format to use for the response. Either "json" (the default) or "csv". The "csv" option is only available when withCompany is true.

    string

    		query

    fromDate
    optional

    Lower date bound, ISO 8601 format. The default for this is 30 days ago.

    Can be given using either YYYY-mm-dd or YYYY-mm format. When a day number is given, the response will include statistics from the beginning of that day. When only a year and a month is given, the response will include statistics from the beginning of the first day of that month.

    Examples: 2022-02-24, and 2022-01.

    Cannot request data past 1st day of the month, 12 months ago. Only affects user-group statistics.

    string

    		query

    toDate
    optional

    Upper date bound, ISO 8601 format. The default for this is today.

    Can be given using either YYYY-mm-dd or YYYY-mm format. When a day number is given, the response will include statistics until the end of that day. When only a year and a month is given, the response will include statistics until the end of the last day of that month.

    Examples: 2022-03-24, and 2022-04.

    Only affects user-group statistics.

    string

    		query

    Responses

    Code Description
    200

    A JSON object with the statistics on usage: count of documents on different stages of the process

    Get usage stats for months

    GET /api/v2/usagestats/months

    Retrieve usage statistics for the last (up to) 12 months

    Parameters

    Parameter Description Type In

    userGroupID
    optional

    The user group ID for which to get usage statistics. This is only used when withCompany is true. This user group must be a child user group of the user's group. If this parameter is omitted, the default is the user group of the API user.

    integer

    		query

    withCompany
    optional

    default: false

    Boolean flag for including a summary of the company statistics in the response.

    boolean

    		query

    recursive
    optional

    default: false

    Boolean flag for recursively including child user group statistics in the response. This flag is only used when withCompany is true.

    boolean

    		query

    includeZeroRecords
    optional

    default: false

    Boolean flag that controls whether to include days or months without statistics in the response.

    boolean

    		query

    includeUsersWithoutStatistics
    optional

    default: false

    Boolean flag that controls whether to include users without statistics in the response.

    This is only possible to use when statsFormat is "csv".

    boolean

    		query

    hideZeroSumEidColumns
    optional

    default: false

    Boolean flag that controls whether to hide columns of chargeable items referring to eID usage that sum up to zero.

    This is only possible to use when statsFormat is "csv".

    boolean

    		query

    addSums
    optional

    default: false

    Boolean flag that controls whether to add row with sums of chargeable items. This will be the first row after the header row.

    This is only possible to use when statsFormat is "csv".

    boolean

    		query

    statsFormat
    optional

    default: json

    The format to use for the response. Either "json" (the default) or "csv". The "csv" option is only available when withCompany is true.

    string

    		query

    fromDate
    optional

    Lower date bound, ISO 8601 format. The default for this is the 1st day of the month, 12 months ago.

    Can be given using either YYYY-mm-dd or YYYY-mm format. When a day number is given, the response will include statistics from the beginning of that day. When only a year and a month is given, the response will include statistics from the beginning of the first day of that month.

    Examples: 2022-02-24, and 2022-01.

    Cannot request data past 1st day of the month, 12 months ago. Only affects user-group statistics.

    string

    		query

    toDate
    optional

    Upper date bound, ISO 8601 format. The default for this is today.

    Can be given using either YYYY-mm-dd or YYYY-mm format. When a day number is given, the response will include statistics until the end of that day. When only a year and a month is given, the response will include statistics until the end of the last day of that month.

    Examples: 2022-03-24, and 2022-04.

    Only affects user-group statistics.

    string

    		query

    Responses

    Code Description
    200

    A JSON object with the statistics on usage: count of documents on different stages of the process

    Signup Request

    POST /api/v2/signup

    Create a new user signup request. Used to handle submission of the signup form.

    If there is no user associated with the given email address, then a new account will be created, and an activation email will be sent to them.

    If there already is an account, but the user has not yet accepted the Scrive eSign Terms of Service, then a new activation email will be sent to them.

    If a user account that has accepted the Terms of Service already exists, no signup request will be created.

    Parameters

    Parameter Description Type In

    email
    required

    Has to be a valid email address format.

    email

    		formData

    firstName
    optional

    Has to be a valid name string.

    string

    		formData

    lastName
    optional

    Has to be a valid name string.

    string

    		formData

    phone
    optional

    Has to be a valid phone

    string

    		formData

    companyName
    optional

    Has to be a valid company name

    string

    		formData

    companyPosition
    optional

    Has to be a valid position

    string

    		formData

    lang
    optional

    Has to be a valid lang code LanguageCode

    Enum: cs, da, de, el, en, es, et, fi, fr, hu, is, it, lt, lv, nl, no, pl, pt, sv

    string

    		formData

    Responses

    Code Description
    200

    JSON response, will be one of:

    • { "sent": true }
    • { "sent": false }

    User Group

    Create User Group

    POST /api/v2/usergroups/create

    Example of JSON that could be passed in to create a User Group:

    The JSON is URL-encoded and passed in via the usergroup form data field. It is not necessary to minify the JSON, but also not prohibited.

    {
  "parent_id": "1",
  "name": "New UG that's the child of user group 1",
  "tags": [
    {
      "name": "side",
      "value": "dark"
    }
  ]
}

    For examples of the JSON output, see details of "View User Group".

    This endpoint allows you to create a new User Group. When creating it, you have the option to set the User Group's name and to specify which other User Group it will be a child of.

    The JSON input must be passed, URL-encoded, via the usergroup form data field.

    You must set a parent_id since only internal Scrive admins are permitted to create root User Groups. In order to create a new child, you must have the requisite permissions upon the parent.

    You can also set tags, which are arbitrary name/value pairs.

    A full User Group JSON response is returned which displays the state after the create operation has been performed. Performing /update and then using the GET endpoint should produce the same output both times.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    usergroup
    required

    JSON object containing the name, parent_id, and tags of the User Group to be created.

    string
    application/json

    		formData

    include-inheritable
    optional

    Append ?include-inheritable to the URL to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		query

    Responses

    Code Description
    200

    JSON representation of a User Group.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to update it)

    View User Group

    GET /api/v2/usergroups/{user_group_id}

    Example of a User Group without inheritable previews:

    {
  "id": "5",
  "parent_id": "1",
  "name": "A Child Usergroup",
  "children": [
    {
      "id": "2",
      "name": "Some child user group"
    },
    {
      "id": "3",
      "name": "Yet another child user group"
    }
  ],
  "settings": {
    "inherited_from": null,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": 42,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    }
  },
  "contact_details": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    }
  },
  "tags": [
    {
      "name": "founded",
      "value": "1846"
    },
    {
      "name": "status",
      "value": "busy"
    }
  ]
}

    Example of a User Group with inheritable previews:

    {
  "id": "5",
  "parent_id": "1",
  "name": "A Child Usergroup",
  "children": [
    {
      "id": "2",
      "name": "Some child user group"
    },
    {
      "id": "3",
      "name": "Yet another child user group"
    }
  ],
  "settings": {
    "inherited_from": null,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": 42,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    },
    "inheritable_preview": {
      "inherited_from": "1",
      "data_retention_policy": {
        "idle_doc_timeout_preparation": null,
        "idle_doc_timeout_closed": null,
        "idle_doc_timeout_canceled": null,
        "idle_doc_timeout_timedout": null,
        "idle_doc_timeout_rejected": 23,
        "idle_doc_timeout_error": null,
        "immediate_trash": true
      }
    }
  },
  "contact_details": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    },
    "inheritable_preview": {
      "inherited_from": "1",
      "address": {
        "company_number": "5568166804",
        "company_name": "Scrive",
        "address": "Grev Turegatan 11A",
        "zip": "114 46",
        "city": "Stockholm",
        "country": "Sweden"
      }
    }
  },
  "tags": [
    {
      "name": "founded",
      "value": "1846"
    },
    {
      "name": "status",
      "value": "busy"
    }
  ]
}

    This endpoint is used to get an overview of a given User Group, including other, related and dependent, objects. At time of writing, those extra objects are contact_details and settings.

    These dependent objects can be inherited. In this case, their inherited_from field will be non-null. The value in this field is the ID of the User Group which the value is inherited from.

    Inheritance works as follows:

    Root User Groups (i.e. those who are not children of other User Groups) may not inherit since there are no ancestors to inherit from.

    A child User Group may inherit or have its own dedicated object. In the case that a User Group chooses to inherit, for example, the contact_details object, then that User Group will inherit from the closest direct ancestor with its own contact_details object. Since root User Groups cannot inherit, there will always be an ancestor from which a child can inherit.

    If you would like to see what a User Group would inherit then you can append ?include-inheritable to the URL when making the call. This will add extra inheritable_preview subtrees to the objects which perform the inheritance calculation, ignoring whether or not the User Group already inherits.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group you wish to view

    integer

    		path

    include-inheritable
    optional

    Append ?include-inheritable to the URL to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		query

    Responses

    Code Description
    200

    JSON representation of a User Group.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to view it)

    Update User Group

    POST /api/v2/usergroups/{user_group_id}/update

    Example of JSON that could be passed in to update a User Group:

    The JSON is URL-encoded and passed in via the usergroup form data field. It is not necessary to minify the JSON, but also not prohibited.

    {
  "parent_id": "1",
  "name": "UG that's now the child of user group 1",
  "tags": [
    {
      "name": "station",
      "value": "ISS"
    },
    {
      "name": "lifeform",
      "value": null
    }
  ]
}

    For examples of the JSON output, see details of "View User Group".

    This endpoint allows you to update the User Group's meta data, or to change its parent ID (i.e. to move this User Group so that it is the child of a differnt User Group).

    The JSON input must be passed, URL-encoded, via the usergroup form data field.

    When updating the parent_id, the following rules are in force:

    Tags are updated as follows:

    The endpoint supports partial updates. This means that only the fields you supply in your requests will have their values altered.

    A full User Group JSON response is returned which displays the state after the update operation has been performed. Performing /update and then using the GET endpoint should produce the same output both times.

    Important Note: You cannot move usergroups by updating the children field, it must be done via parent_id.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group you wish to update

    integer

    		path

    usergroup
    required

    JSON object containing the new name, parent_id or tags for the User Group.

    string
    application/json

    		formData

    include-inheritable
    optional

    Set to true to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		formData

    Responses

    Code Description
    200

    JSON representation of a User Group.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to update it)

    Delete User Group

    POST /api/v2/usergroups/{user_group_id}/delete

    Example of JSON returned:

    {
  "id": "1",
  "resource": "usergroup",
  "action": "deleted"
}

    This endpoint allows you to delete a User Group.

    It's worth noting that you may only delete child User Groups. Root User Groups can only deleted by internal Scrive admins. Furthermore, User Groups with children cannot be deleted. We also do not support recursive deletion. If this is required, it can be implemented client-side by simply working up the tree, deleting the leaves.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group you wish to update

    integer

    		path

    Responses

    Code Description
    200

    Simple JSON showing that a User Group with a given ID has been deleted.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to update it)

    View User Group Contact Details

    GET /api/v2/usergroups/{user_group_id}/contact_details

    Example of a User Group Contact Details without inheritable previews:

    {
  "inherited_from": "1",
  "address": {
    "company_number": "5568166804",
    "company_name": "Scrive",
    "address": "Grev Turegatan 11A",
    "zip": "114 46",
    "city": "Stockholm",
    "country": "Sweden"
  }
}

    Example of a User Group Contact Details with inheritable previews (where the User Group is root and therefore must have its own Contact Details object):

    {
  "inherited_from": null,
  "address": {
    "company_number": "0987654321",
    "company_name": "Scrive",
    "address": "Other Street",
    "zip": "00-321",
    "city": "Warsaw",
    "country": "PL"
  },
  "inheritable_preview": null
}

    Example of a User Group Contact Details with inheritable previews (where the User Group is a child with its own Contact Details object):

    {
  "inherited_from": null,
  "address": {
    "company_number": "0987654321",
    "company_name": "Scrive",
    "address": "123 Other Street",
    "zip": "00-321",
    "city": "Warsaw",
    "country": "Poland"
  },
  "inheritable_preview": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    }
  }
}

    Example of a User Group Contact Details with inheritable previews (where the User Group is a child which inherits, meaning that the inheritable_preview field is a duplicate):

    {
  "inherited_from": "1",
  "address": {
    "company_number": "5568166804",
    "company_name": "Scrive",
    "address": "Grev Turegatan 11A",
    "zip": "114 46",
    "city": "Stockholm",
    "country": "Sweden"
  },
  "inheritable_preview": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    }
  }
}

    This endpoint is used to get an overview of a given User Group's contact_details object.

    The contact_details object can be inherited. In this case, the inherited_from field will be non-null. The value in this field is the ID of the User Group which the value is inherited from.

    Inheritance works as follows:

    Root User Groups (i.e. those who are not children of other User Groups) may not inherit since there are no ancestors to inherit from.

    A child User Group may inherit or have its own dedicated object. In the case that a User Group chooses to inherit the contact_details object, then that User Group will inherit from the closest direct ancestor with its own contact_details object. Since root User Groups cannot inherit, there will always be an ancestor from which a child can inherit.

    If you would like to see what a User Group would inherit then you can append ?include-inheritable to the URL when making the call. This will add extra inheritable_preview subtrees to the objects which perform the inheritance calculation, ignoring whether or not the User Group already inherits.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose contact_details object you wish to view

    integer

    		path

    include-inheritable
    optional

    Append ?include-inheritable to the URL to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		query

    Responses

    Code Description
    200

    JSON representation of a User Group's Contact Details.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to view it)

    Update User Group Contact Details

    POST /api/v2/usergroups/{user_group_id}/contact_details/update

    Example of JSON that could be passed in to update a User Group's Contact Details:

    The JSON is URL-encoded and passed in via the contact_details form data field. It is not necessary to minify the JSON, but also not prohibited.

    {
  "address": {
    "company_number": "0987654321",
    "company_name": "Scrive",
    "address": "123 Other Street",
    "zip": "00-321",
    "city": "Warsaw",
    "country": "Poland"
  }
}

    For examples of the JSON output, see View User Group Contact Details.

    This endpoint allows you to update the User Group's contact_details object.

    When updating the contact_details object, the following rules are in force:

    Partial updates are permissible (and encouraged). You may only supply the JSON fields that you wish to actually update.

    If you update the contact_details of a User Group which currently inherits, a new, blank contact_details object will be created and your (partial or full) update applied to it.

    The User Group from which the contact_details were previously inherited will be unaffected by the operation.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose contact_details object you wish to update

    integer

    		path

    contact_details
    required

    JSON object containing (partial or full) updates to the contact_details subtrees (currently only data_retention_policy is exposed by the API).

    string
    application/json

    		formData

    include-inheritable
    optional

    Set to true to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		formData

    Responses

    Code Description
    200

    JSON representation of a User Group's Contact Details.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to update it)

    Delete User Group Contact Details

    POST /api/v2/usergroups/{user_group_id}/contact_details/delete

    For examples of the JSON output, see View User Group Contact Details.

    This endpoint is used to delete a given User Group's contact_details object. This will cause the contact_details to be inherited rather than the User Group having its own dedicated contact_details object.

    As such, calling delete on a User Group that already inherits will result in no operation being performed. Also, attempting to delete the contact_details object of a root User Group will result in an error.

    For more details on inheritance, see View User Group Contact Details.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose contact_details object you wish to delete

    integer

    		path

    include-inheritable
    optional

    Set to true to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		formData

    Responses

    Code Description
    200

    JSON representation of a User Group's Contact Details.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to view it)

    View User Group Settings

    GET /api/v2/usergroups/{user_group_id}/settings

    Example of a User Group Settings without inheritable previews:

    {
  "inherited_from": "1",
  "data_retention_policy": {
    "idle_doc_timeout_preparation": null,
    "idle_doc_timeout_closed": null,
    "idle_doc_timeout_canceled": null,
    "idle_doc_timeout_timedout": null,
    "idle_doc_timeout_rejected": null,
    "idle_doc_timeout_error": null,
    "immediate_trash": false
  }
}

    Example of a User Group Settings with inheritable previews (where the User Group is root and therefore must have its own Settings object):

    {
  "inherited_from": null,
  "data_retention_policy": {
    "idle_doc_timeout_preparation": null,
    "idle_doc_timeout_closed": null,
    "idle_doc_timeout_canceled": null,
    "idle_doc_timeout_timedout": null,
    "idle_doc_timeout_rejected": null,
    "idle_doc_timeout_error": null,
    "immediate_trash": false
  },
  "inheritable_preview": null
}

    Example of a User Group Settings with inheritable previews (where the User Group is a child with its own Settings object):

    {
  "inherited_from": null,
  "data_retention_policy": {
    "idle_doc_timeout_preparation": null,
    "idle_doc_timeout_closed": null,
    "idle_doc_timeout_canceled": null,
    "idle_doc_timeout_timedout": null,
    "idle_doc_timeout_rejected": null,
    "idle_doc_timeout_error": null,
    "immediate_trash": false
  },
  "inheritable_preview": {
    "inherited_from": "1",
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": null,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    }
  }
}

    Example of a User Group Settings with inheritable previews (where the User Group is a child which inherits, meaning that the inheritable_preview field is a duplicate):

    {
  "inherited_from": "1",
  "data_retention_policy": {
    "idle_doc_timeout_preparation": null,
    "idle_doc_timeout_closed": null,
    "idle_doc_timeout_canceled": null,
    "idle_doc_timeout_timedout": null,
    "idle_doc_timeout_rejected": null,
    "idle_doc_timeout_error": null,
    "immediate_trash": false
  },
  "inheritable_preview": {
    "inherited_from": "1",
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": null,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    }
  }
}

    This endpoint is used to get an overview of a given User Group's settings object.

    The settings object can be inherited. In this case, the inherited_from field will be non-null. The value in this field is the ID of the User Group which the value is inherited from.

    Inheritance works as follows:

    Root User Groups (i.e. those who are not children of other User Groups) may not inherit since there are no ancestors to inherit from.

    A child User Group may inherit or have its own dedicated object. In the case that a User Group chooses to inherit the settings object, then that User Group will inherit from the closest direct ancestor with its own settings object. Since root User Groups cannot inherit, there will always be an ancestor from which a child can inherit.

    If you would like to see what a User Group would inherit then you can append ?include-inheritable to the URL when making the call. This will add extra inheritable_preview subtrees to the objects which perform the inheritance calculation, ignoring whether or not the User Group already inherits.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose settings object you wish to view

    integer

    		path

    include-inheritable
    optional

    Append ?include-inheritable to the URL to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		query

    Responses

    Code Description
    200

    JSON representation of a User Group's Settings.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to view it)

    Update User Group Settings

    POST /api/v2/usergroups/{user_group_id}/settings/update

    Example of JSON that could be passed in to update a User Group's Settings:

    The JSON is URL-encoded and passed in via the settings form data field. It is not necessary to minify the JSON, but also not prohibited.

    The example below is an example of a partial update.

    {
  "data_retention_policy": {
    "idle_doc_timeout_closed": 123
  }
}

    For examples of the JSON output, see View User Group Settings.

    This endpoint allows you to update the User Group's settings object.

    When updating the settings object, the following rules are in force:

    Partial updates are permissible (and encouraged). You may only supply the JSON fields that you wish to actually update.

    If you update the settings of a User Group which currently inherits, the inherited settings will be cloned, your update applied, and this will then become the new non-inherited settings object for this User Group.

    The User Group from which the contact_details were previously inherited will be unaffected by the operation.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose settings object you wish to update

    integer

    		path

    settings
    required

    JSON object containing (partial or full) updates to the settings subtrees (currently only data_retention_policy is exposed by the API).

    string
    application/json

    		formData

    include-inheritable
    optional

    Set to true to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		formData

    Responses

    Code Description
    200

    JSON representation of a User Group's Settings.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to update it)

    Delete User Group Settings

    POST /api/v2/usergroups/{user_group_id}/settings/delete

    For examples of the JSON output, see View User Group Settings.

    This endpoint is used to delete a given User Group's settings object. This will cause the settings to be inherited rather than the User Group having its own dedicated settings object.

    As such, calling delete on a User Group that already inherits will result in no operation being performed. Also, attempting to delete the settings object of a root User Group will result in an error.

    For more details on inheritance, see View User Group Settings.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose settings object you wish to delete

    integer

    		path

    include-inheritable
    optional

    Set to true to see a preview of which values can be inherited from an ancestor User Group.

    boolean

    		formData

    Responses

    Code Description
    200

    JSON representation of a User Group's Settings.
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to view it)

    List Users in User Group

    GET /api/v2/usergroups/{user_group_id}/users

    Example of a list of the users in a User Group:

    [
  {
    "id": "1",
    "fstname": "Arthur",
    "sndname": "Dent",
    "email": "arthur.dent@scrive.com",
    "twofactor_active": false,
    "twofactor_is_mandatory": false,
    "personalnumber": "197910124242",
    "phone": "+444242424242",
    "companyadmin": true,
    "companyposition": "Hitchhiker",
    "lang": "en"
  }
]

    This endpoint is used to list Users who are members of that User Group.

    Note that this will only display Users that are in that User Group and will not show the Users who are members of any descendent User Groups.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    user_group_id
    required

    The ID of the User Group whose users you wish to view

    integer

    		path

    Responses

    Code Description
    200

    List of Users in the User Group
    403

    Insufficient Permissions error (this means that either no User Group exists with this ID or that you do not have permission to view it)

    List short information about user groups (optionally matching a filter)

    GET /api/v2/usergroups/list

    Get ID, name, and parent ID for each accessible user group, with filtering and sorting options.

    OAuth Privileges required: FULL_ACCESS

    Response example

    { "user_groups": [
    {
      "id": "1",
      "name": "foo",
      "parent": null
    },
    {
      "id": "2",
      "name": "bar",
      "parent": {
        "id": "1"
      }
    },
    {
      "id": "3",
      "name": "baz",
      "parent": {
        "id": "1"
      }
    }
  ]
}

    Parameters

    Parameter Description Type In

    filter
    optional

    default: []

    List of filtering options.

    You can supply a list of filtering options to apply.

    Only user groups that match all filters will be returned.

    If not supplied, the default is to return information for all user groups.

    Must be of type User Group ID and Name Filter, for example:

    [ { "filter_by": "name", "value": "foobar" } ]

    string
    application/json

    		query

    sorting
    optional

    List of sorting options.

    You can supply a list of sorting options, which will be applied to the list of user group IDs and names in the order provided.

    If not supplied, the default is to return the results in an unspecified order.

    Must be of type User Group ID and Name Sorting.

    string
    application/json

    		query

    Responses

    Code Description
    200

    A JSON object with key "user_groups", with the value being an array of user group IDs, names, and parent IDs (see User Group Short Information).

    Access Control

    View Access Roles for User

    GET /api/v2/getuserroles/{user_id}

    Example of a User's Access Roles

    [
  {
    "id": "8",
    "is_generated": false,
    "role_type": "user_group_admin",
    "source": {
      "type": "user",
      "id": "2"
    },
    "target": {
      "type": "user_group",
      "id": "11"
    }
  },
  {
    "id": null,
    "is_generated": true,
    "role_type": "user_admin",
    "source": {
      "type": "user",
      "id": "2"
    },
    "target": {
      "type": "user_group",
      "id": "8"
    }
  }
]

    This endpoint is used to view the roles which have been granted to a given user.

    Parameters

    Parameter Description Type In

    user_id
    required

    The ID of the User whose roles you wish to view

    integer

    		url

    Responses

    Code Description
    200

    A JSON array of Access Role objects.
    403

    Insufficient Permissions error (this means that you don't have Read permissions upon the User or the User does not exist).

    View Access Role

    GET /api/v2/accesscontrol/roles/{role_id}

    Example of an Access Role

    {
  "id": "8",
  "is_generated": false,
  "role_type": "user_group_admin",
  "source": {
    "type": "user",
    "id": "2"
  },
  "target": {
    "type": "user_group",
    "id": "11"
  }
}

    This endpoint is used to get the details of a given access role. Only explicitly granted roles can be viewed via this endpoint, since implicit roles do not have an ID of their own to reference them by.

    Implicit roles are those roles which are granted automatically as a result of, for example, User Group membership. Implicit roles have is_generated set to true and id set to null.

    Explicit roles are those which have been, as the name suggests, explicitly granted. This was also almost certainly done via this API. Explicit roles have is_generated set to false and a non-null id.

    Parameters

    Parameter Description Type In

    role_id
    required

    The ID of the Access Role you wish to view

    integer

    		url

    Responses

    Code Description
    200

    JSON representation of an Access Role.
    403

    Insufficient Permissions error (this means that you don't have enough permissions to view details of the role. In practice this means that you lack Read permissions on either the source or the target that the role refers to.

    Grant Access Role

    POST /api/v2/accesscontrol/roles/add

    Example of JSON that could be used to grant a new role:

    {
  "role_type": "user",
  "source": {
    "type": "user",
    "id": "2"
  },
  "target": {
    "type": "user",
    "id": "4"
  }
}

    This endpoint allows you to grant a new Access Role.

    Parameters

    Parameter Description Type In

    role
    required

    JSON object containing details of the role to be granted.

    string
    application/json

    		formData

    Responses

    Code Description
    200

    JSON representation of an Access Role.
    403

    Insufficient Permissions error (this means that you don't have enough permissions to grant this role. In practice this means that you lack Create permissions on the Policy relation for either the source or the target that the proposed role refers to.

    Delete Access Role

    POST /api/v2/accesscontrol/roles/{role_id}/delete

    The endpoint allows you to delete an explicitly granted access role.

    Explicitly granted in this case generally means "role which was created via the Access Control API" as opposed to an implicit role acquired via, for example, User Group membership. If it has a non-null id field then it is an explicit role and can be deleted.

    Parameters

    Parameter Description Type In

    role_id
    required

    The ID of the Access Role you wish to delete

    integer

    		url

    Responses

    Code Description
    200

    JSON object showing that an Access Role with the given ID has been successfully deleted.
    403

    Insufficient Permissions error (this means that you don't have Delete permissions upon the Policy relation of either the source or target of the role). Either that, or no Access Role exists with this id.

    Folders

    View Folder

    GET /api/v2/folders/{folder_id}

    Example of a Folder

    {
  "id": "1",
  "name": "Root folder",
  "home_for_user": null,
  "home_for_user_group": "10",
  "parent_id": null,
  "children": [
    {
      "id": "2",
      "name": "Subfolder of 1",
      "home_for_user": "33",
      "home_for_user_group": null
    }
  ]
}

    This endpoint is used to get the details of a given folder. Note that the contents of the folder are not displayed, just the metadata about the folder.

    This metadata currently consists of the folder's ID, name, its parent ID (if any), IDs of the user and the user group for whom the folder is a home folder and information about its children. Only the immediate children are included by default (see the recursive parameter).

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    folder_id
    required

    The ID of the Folder you wish to view

    string

    		url

    recursive
    optional

    default: false

    Set ?recursive=true to include all descendant folders in the metadata instead of just the immediate children.

    boolean

    		query

    Responses

    Code Description
    200

    JSON representation of a Folder.
    403

    Insufficient Permissions error (this means that you don't have enough permissions to view this Folder). In practice this means that you lack Read permissions on the Folder. Uniquely, for this endpoint, it is also possible to acquire Read permissions by being a signatory or approver of a document in that folder.

    Create Folder

    POST /api/v2/folders/create

    Example of JSON that could be used create a new Folder:

    {
  "name": "new child folder of 1",
  "parent_id": "1"
}

    This endpoint allows you to create a new Folder. When creating it, you have the option to set the Folder's name and to specify which other Folder it will be a child of.

    The JSON input must be passed, URL-encoded, via the folder form data field.

    You must set a parent_id since only internal Scrive admins are permitted to create root Folders. In order to create a new child, you must have the requisite permissions upon the parent. name will be an empty string if you do not include it.

    A full Folder JSON response is returned which displays the state after the create operation has been performed. Performing /update and then using the GET endpoint should produce the same output both times.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    folder
    optional

    JSON object containing details of the folder to be created.

    string
    application/json

    		formData

    Responses

    Code Description
    200

    JSON representation of a Folder.
    403

    Insufficient Permissions error (this means that you don't have enough permissions to create this Folder. In practice this means that you lack Create permissions on the parent Folder).

    Update Folder

    POST /api/v2/folders/{folder_id}/update

    Example of JSON that could be used update a Folder:

    {
  "name": "new child folder of 1",
  "parent_id": "1"
}

    For examples of the JSON output, see details of "View Folder".

    This endpoint allows you to update the Folder's meta data, or to change its parent ID (i.e. to move this Folder so that it is the child of a differnt Folder).

    The JSON input must be passed, URL-encoded, via the folder form data field.

    When updating the parent_id, the following rules are in force:

    The endpoint supports partial updates. This means that only the fields you supply in your requests will have their values altered. Neither field is required, providing {} as your update JSON is essentially a "no op".

    A full Folder JSON response is returned which displays the state after the update operation has been performed. Performing /update and then using the GET endpoint should produce the same output both times.

    Important Note: You cannot move Folders by updating the children field, it must be done via parent_id.

    Parameters

    Parameter Description Type In

    folder_id
    required

    The ID of the Folder whose contents you wish to list

    string

    		url

    folder
    optional

    JSON object containing details of the folder to be updated.

    string
    application/json

    		formData

    Responses

    Code Description
    200

    JSON representation of a Folder.
    403

    Insufficient Permissions error (this means that you don't have enough permissions to update this Folder. In practice this means that you lack Update permissions on the Folder.

    Delete Folder

    POST /api/v2/folders/{folder_id}/delete

    This endpoint allows you to delete a Folder.

    It's worth noting that you may only delete child Folders. Root Folders can only deleted by internal Scrive admins. We also do not support recursive deletion. If this is required, it can be implemented client-side by simply working up the tree, deleting the leaves.

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    folder_id
    required

    The ID of the Folder you wish to delete

    string

    		url

    Responses

    Code Description
    200

    JSON object showing that a Folder with the given ID has been successfully deleted.
    403

    Insufficient Permissions error (this means that you don't have enough permissions to create this Folder. In practice this means that you lack Delete permissions on the Folder).

    List Documents in Folder

    GET /api/v2/folders/{folder_id}/list

    Example of a Folder Listing

    {
  "total_matching": 2,
  "documents": [
    <Document JSON (see doc endpoints)>,
    <Document JSON (see doc endpoints)>
  ]
}

    This endpoint is used to get the details of the documents in a given folder.

    Other than the JSON fields shown above, which wrap the output data in a list and show a little metadata, the document JSON for each item in "documents" is structured the same as it would be for endpoints that display a given document. (See the Document Definition documentation for details).

    OAuth Privileges required: FULL_ACCESS

    Parameters

    Parameter Description Type In

    folder_id
    required

    The ID of the Folder whose contents you wish to list

    string

    		url

    Responses

    Code Description
    200

    JSON object which states the number of documents in the folder and lists the JSON respresentations of those documents. (See Documents in Definitions)
    403

    Insufficient Permissions error (this means that you don't have enough permissions to create this Folder. In practice this means that you lack Read permissions on the Folder)

    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,
      "signatory_role": "viewer",
      "signatory_status": "invitation_sent",
      "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",
      "authentications": {
        "view": {
          "name": "standard"
        },
        "sign": {
          "name": "standard"
        },
        "view_archived": {
          "name": "standard"
        }
      },
      "authentication_method_to_view": "standard",
      "authentication_method_to_view_archived": "standard",
      "authentication_method_to_sign": "standard",
      "confirmation_delivery_method": "none",
      "notification_delivery_method": "none",
      "allows_highlighting": false,
      "attachments": [],
      "highlighted_pages": [],
      "api_delivery_url": null
    },
    {
      "id": "189256",
      "user_id": null,
      "is_author": false,
      "is_signatory": true,
      "signatory_role": "signing_party",
      "signatory_status": "invitation_sent",
      "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",
      "authentications": {
        "view": {
          "name": "standard"
        },
        "sign": {
          "name": "onfido",
          "settings": {
            "report": "document_only",
            "identity_document_types": [
              "id_card",
              "passport"
            ],
            "identity_document_countries": null,
            "ui_locale": "en-US",
            "force_mobile_document_capture": true
          }
        },
        "view_archived": {
          "name": "standard"
        }
      },
      "authentication_method_to_view": "standard",
      "authentication_method_to_view_archived": "standard",
      "authentication_method_to_sign": "onfido",
      "confirmation_delivery_method": "none",
      "notification_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,
    "show_arrow": true
  },
  "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"
  },
  "experimental_features": {
    "signatory_status_summary": "invitations_sent"
  }
}

    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 (string,null, 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)

    Deprecated, please use signatory_role instead. If true, this party is a signatory to the document, otherwise they are a viewer or an approver and will not sign the document. If both is_signatory and signatory_role are present, is_signatory takes precedence if their values are inconsistent (this is done for backwards compatibility).

    signatory_role (string, enum)

    Signatory role: viewer, approver, or a signing party. Only signing parties can sign documents, viewers only have view access, and approvers can additionally approve or reject. Whether the approver is hidden or visible is controlled by the flag is_visible.

    The value of this property must be one of the following enum values:

    • "viewer"
    • "signing_party"
    • "approver"
    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.
    • SignatoryFieldFullName: Computed combination of the above two.
    • 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.
    • SignatoryFieldDate: A date input field.
    • SignatoryFieldSignDate: The date of signing of this 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.

    Each element of this array must match at least one of the following schemas:

    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.

    The value of this property 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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldFullName (object)

    Signatory field displaying full name of the respective signatory. Note: this field doesn't contain value of its own and when displaying the text will be derived from the "firstname" and "lastname" field values.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a full name field.

    The value of this property must be one of the following enum values:

    • "full_name"
    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldSignature (object)

    A signatory field for placing signature boxes on the document.

    This object has the following properties:

    type (string, enum, required)

    The value of this property 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 (read only)

    The value of this property must match at least one of the following schemas:

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

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property must be one of the following enum values:

    • 0
    fsrel (number, enum, required)

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

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    custom_validation

    The value of this property must match exactly one of the following schemas:

    (null)
    SignatoryFieldCustomValidation (object)

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

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

    description (string,null)

    Description of this field

    SignatoryFieldDate (object)

    Signatory field for dates. Optionally can impose restrictions on start and/or end date (either absolute or relative to document view).

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a date field.

    The value of this property must be one of the following enum values:

    • "date"
    name (string, required)

    A name for the date 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,null)

    Either a pre-filled value, or the value entered by the signatory. Must be specified as ISO8601 date.

    Default: null

    is_obligatory (boolean)

    Default: true

    should_be_filled_by_sender (boolean)

    Default: false

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    configuration (object, required)

    Definition of optional restriction imposed upon start and/or end date. Null means no restriction.

    The configuration object has the following properties:

    start_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    end_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    SignatoryFieldSignDate (object)

    Signatory field displaying sign date of the respective signatory.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a sign date field.

    The value of this property must be one of the following enum values:

    • "sign_date"
    value (string,null)

    Date when the signatory has signed or null if not yet signed. Formatted as ISO8601 date. Read only.

    Default: null

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    sign_order (integer)

    Default: 1

    sign_time (string,null, read only)
    seen_time (string,null, read only)
    deferred_time (string,null, read only)
    read_invitation_time (string,null, read only)
    rejected_time (string,null, read only)
    rejection_reason (string,null, 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,null)

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

    reject_redirect_url (string,null)

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

    email_delivery_status (string, enum)

    The current delivery status.

    The value of this property must be one of the following enum values:

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

    The current delivery status.

    The value of this property must be one of the following enum values:

    • "unknown"
    • "not_delivered"
    • "delivered"
    • "deferred"
    has_authenticated_to_view (boolean, read only)

    If a person has identified to view the document.

    csv (array,null)
    delivery_method (string, enum)

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface. Furthermore, pad delivery is referred to as "In-person".

    Default: "email"

    The value of this property must be one of the following enum values:

    • "email"
    • "mobile"
    • "email_mobile"
    • "pad"
    • "api"
    authentications (object)

    Authentication object replacing individual properties authentication_method_to_view, authentication_method_to_sign and authentication_method_to_view_archived. This object has to be fully defined when present and has lower priority than individual properties so to use it, you have remove those individual properties from the signatory object. Unlike individual authentication properties, this authentication object also supports provider specific settings.

    The authentications object has the following properties:

    view (object)

    This setting forces signatories to authenticate using the supplied identification method to view the document before signing.

    Will be overridden by authentication_method_to_view property when both are present.

    The view object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    sign (object)

    This setting forces user to authenticate to sign.

    Will be overridden by authentication_method_to_sign property when both are present.

    The sign object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"
    settings (object,null)

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to sign settings

    swisscom (object)

    See: Swisscom authentication to sign settings

    view_archived (object)

    This setting forces signatories to authenticate using the supplied identification method to view the document once it has been signed and resides in the e-archive.

    Will be overridden by authentication_method_to_view_archived property when both are present.

    The view_archived object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    authentication_method_to_view (string, enum)

    This setting forces signatories to authenticate using the supplied identification method to view the document before signing.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    authentication_method_to_view_archived (string, enum)

    This setting forces signatories to authenticate using the supplied identification method to view the document once it has been signed and resides in the e-archive.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    authentication_method_to_sign (string, enum)

    This setting forces user to authenticate to sign.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"
    • "smart_id_qes"
    confirmation_delivery_method (string, enum)

    Deliver a confirmation message about the document signing status by:

    • email an email including a file attachment of the signed document
    • mobile a text message with a link to the signed document
    • email_mobile both of the two above
    • email_link an email with a link to the signed document
    • email_link_mobile an email and a text message with a link to the signed document
    • none no delivery at all

    Default: "email"

    The value of this property must be one of the following enum values:

    • "email"
    • "mobile"
    • "email_mobile"
    • "email_link"
    • "email_link_mobile"
    • "none"
    notification_delivery_method (string, enum)

    Deliver a confirmation notification that the party signed/approved the document by:

    • email an email including a link to the document
    • mobile a text message including a link to the document
    • email_mobile both of the two above
    • none no delivery at all

    Default: "none"

    The value of this property 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

    can_forward (boolean)

    Whether the signatory can forward the signing process to someone else.

    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)

    A signatory attachment - 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.

    add_to_sealed_file (boolean)

    Should the file of this attachment be merged into the final sealed document?

    Default: true

    api_delivery_url (string,null)

    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

    The value of this property must match exactly one of the following schemas:

    (null)
    (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.

    This 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 (boolean)

    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.

    is_visible (bool,null)

    Determines if an approver or viewer is visible in verification page and sign view.

    This value is only used for approvers and viewers, it has to be null for signing_party signatories.

    Default: "null"

    document_roles (array)

    List of "roles" this signatory has within the document.

    The individual roles can be arbitrary texts (often in local language of the document). Those roles (if specified) will be part of the evidence log and also will be displayed in sign view (user signs/approves the document in the following roles).

    Default:
    []

    All array elements must be of type:

    (string)

    experimental (object)

    ⚠️ WARNING: EXPERIMENTAL ⚠️

    Experimental properties are not part of public API. Therefore they're not supported and are subject to change without prior notice.

    The experimental object has the following properties:

    signatory_status (string, enum, read only)

    The current status of the signatory in relation to the document.

    The statuses document_problem, document_draft, document_canceled, document_timedout and document_rejected are reflecting the status field of the underlying document for convenience.

    The value of this property must be one of the following enum values:

    • "document_problem"
    • "document_draft"
    • "document_canceled"
    • "document_timedout"
    • "document_rejected"
    • "waiting_for_prior_signatures"
    • "invitation_sent"
    • "invitation_delivery_problem"
    • "invitation_delivered"
    • "invitation_read"
    • "document_opened"
    • "document_deferred"
    • "document_signed"
    • "document_approved"
    • "confirmation_delivery_problem"

    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

    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 value of this property must match exactly one of the following schemas:

    (null)
    File (object)

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

    This object has the following properties:

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

    author_attachments (array, read only)

    List of author attachments.

    These documents are to be reviewed by the signatory parties, and are uploaded by the author of the document. 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,null, read only)

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

    auto_remind_time (string,null, 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". However if the document was started using bulk send feature, it will first transition into "awaiting_start", and shortly after that into "pending".

    Documents in "awaiting_start" cannot be modified, trashed or canceled.

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

    The value of this property must be one of the following enum values:

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

    days_to_sign (integer)

    Default: 90

    days_to_remind (integer,null)

    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.

    show_arrow (boolean)

    Whether to show the auto-scroll arrow on the signing page.

    show_form (boolean)

    Whether to show the fields as a form on the signing page.

    show_form_arrow (boolean)

    Whether to show the auto-scroll arrow on the form page.

    invitation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    sms_invitation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    confirmation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    sms_confirmation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    lang (string, enum)

    Currently supported language codes

    The value of this property must be one of the following enum values:

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

    api_callback_url (string,null)

    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)

    The value of this property must be one of the following enum values:

    • "company_shared"
    • "company_admin"
    • "signatory"
    signatory_id (string)

    experimental_features (object)

    ⚠️ WARNING: EXPERIMENTAL ⚠️

    Experimental properties are not part of public API. Therefore they're not supported and are subject to change without prior notice.

    The experimental_features object has the following properties:

    signatory_status_summary (string, enum, read only)

    The document status in relation to its signatories.

    The statuses document_template, document_problem, document_draft, document_signed, document_canceled, document_timedout and document_rejected are reflecting the status field of the underlying document for convenience.

    A document with document_opened has been opened by all of its signatories.

    A document with invitations_read has all of its signatories having read the invitations to sign or approve. Some might have opened the document as well, but not all.

    A document with invitations_delivered has all the invitations delivered.

    A document with invitation_delivery_problem has some invitation with a delivery problem.

    A document with invitation_sent has all invitations sent but not all delivered neither opened or read.

    When several signing stages (a.k.a. invitation orders) are defined for the document, only the signatories in the current and previous stages are taken into account to determine the status.

    The value of this property must be one of the following enum values:

    • "document_template"
    • "document_problem"
    • "document_draft"
    • "invitations_sent"
    • "invitations_delivered"
    • "invitation_delivery_problem"
    • "invitations_read"
    • "document_opened"
    • "document_signed"
    • "document_canceled"
    • "document_timedout"
    • "document_rejected"

    User group

    The user group metadata as a JSON.

    UserGroup

    (object)

    Example JSON: for "UserGroup"

    {
  "id": "1",
  "parent_id": null,
  "name": "A Root Usergroup",
  "children": [
    {
      "id": "2",
      "name": "Some child user group"
    },
    {
      "id": "3",
      "name": "Yet another child user group"
    }
  ],
  "settings": {
    "inherited_from": null,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": 42,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    }
  },
  "contact_details": {
    "inherited_from": null,
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    }
  },
  "tags": [
    {
      "name": "alignment",
      "value": "chaotic good"
    }
  ]
}

    JSON representation of a User Group.

    This object has the following properties:

    id (string)

    parent_id (string)

    name (string)

    children (array)

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    id (string)
    name (string)

    settings (object)

    JSON representation of a User Group's Settings.

    The settings object has the following properties:

    inherited_from (string)
    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    contact_details (object)

    JSON representation of a User Group's Contact Details.

    The contact_details object has the following properties:

    inherited_from (string)
    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    tags (array)

    User defined set of name/value pairs.

    Each tag must have {"name": "some-name", "value": "some-value"} format. In the responses value is always a string. In the requests you can also provide null value to delete a tag. Other value types lead to 400 Bad Request response.

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    name (string)
    value (string)

    User group with inheritable previews

    The user group metadata as a JSON (with Inheritable Previews).

    UserGroupWithInheritable

    (object)

    Example JSON: for "UserGroupWithInheritable"

    {
  "id": "5",
  "parent_id": "1",
  "name": "A Child Usergroup",
  "children": [
    {
      "id": "2",
      "name": "Some child user group"
    },
    {
      "id": "3",
      "name": "Yet another child user group"
    }
  ],
  "settings": {
    "inherited_from": null,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": 42,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    },
    "inheritable_preview": {
      "inherited_from": "1",
      "data_retention_policy": {
        "idle_doc_timeout_preparation": null,
        "idle_doc_timeout_closed": null,
        "idle_doc_timeout_canceled": null,
        "idle_doc_timeout_timedout": null,
        "idle_doc_timeout_rejected": 23,
        "idle_doc_timeout_error": null,
        "immediate_trash": true
      }
    }
  },
  "contact_details": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    },
    "inheritable_preview": {
      "inherited_from": "1",
      "address": {
        "company_number": "5568166804",
        "company_name": "Scrive",
        "address": "Grev Turegatan 11A",
        "zip": "114 46",
        "city": "Stockholm",
        "country": "Sweden"
      }
    }
  },
  "tags": [
    {
      "name": "home-planet",
      "value": "Earth"
    }
  ]
}

    JSON representation of a User Group (with Inheritable Previews).

    This object has the following properties:

    id (string)

    parent_id (string)

    name (string)

    children (array)

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    id (string)
    name (string)

    settings (object)

    JSON representation of a User Group's Settings (with Inheritable Preview).

    The settings object has the following properties:

    inherited_from (string)
    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    inheritable_preview (object)

    The inheritable_preview object has the following properties:

    inherited_from (string)
    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    contact_details (object)

    JSON representation of a User Group's Contact Details (with Inheritable Preview).

    The contact_details object has the following properties:

    inherited_from (string)
    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    inheritable_preview (object)

    The inheritable_preview object has the following properties:

    inherited_from (string)
    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    tags (array)

    User defined set of name/value pairs.

    Each tag must have {"name": "some-name", "value": "some-value"} format. In the responses value is always a string. In the requests you can also provide null value to delete a tag. Other value types lead to 400 Bad Request response.

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    name (string)
    value (string)

    API error

    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.",
  "http_code": 400,
  "error_detail": {
    "parameter": "document",
    "value": "{\n  title:  \"document\"\n}",
    "parse_error": [
      "Invalid JSON: Error in $: Failed reading: satisfy. Expecting object key at 'title:document'"
    ]
  }
}

    The structure of errors returned by the Scrive Document API.

    This object has the following properties:

    error_type (string, enum)

    The value of this property must be one of the following enum values:

    • "action_not_permitted"
    • "conflict_error"
    • "document_action_forbidden"
    • "document_object_version_mismatch"
    • "document_state_error"
    • "endpoint_not_found"
    • "insufficient_privileges"
    • "invalid_authorisation"
    • "obsolete"
    • "payload_too_large"
    • "rate_limited"
    • "request_failed"
    • "request_parameters_invalid"
    • "request_parameters_missing"
    • "request_parameters_parse_error"
    • "resource_gone"
    • "resource_not_found"
    • "server_error"
    • "signatory_state_error"

    error_message (string)

    http_code (integer, enum)

    The value of this property must be one of the following enum values:

    • 400
    • 401
    • 403
    • 404
    • 409
    • 410
    • 413
    • 429
    • 500
    • 603

    error_detail (any)

    Arbitrary JSON value unless endpoint documentation specifies otherwise. This property is meant to to aid developers/API integrators to figure out what caused an error and it's not meant to be interpreted by API integration.

    Bulk send descriptor

    The bulk send data as a JSON.

    Bulk send descriptor

    (object)

    Example JSON: for "Bulk send descriptor"

    {
  "id": "314",
  "name": "Rent contract prolongation",
  "created_at": "2022-07-12T17:19:56.126709Z",
  "documents": [
    {
      "document_id": "7769",
      "status": "scheduled"
    },
    {
      "document_id": "7770",
      "status": "started"
    },
    {
      "document_id": "7770",
      "status": "cancelled"
    }
  ]
}

    Details about bulk send and its progress.

    This object has the following properties:

    id (string)

    Unique identifier of a bulk send.

    Will not change over time, and cannot be changed.

    name (string)

    Label provided during bulk send call.

    Usually, it will likely correlate with the name of the document.

    created_at (string)

    Date and time of bulk send creation.

    documents (array)

    List of related documents and their sendout status.

    All array elements must be of type:

    (object)

    This object has the following properties:

    document_id (string)

    Unique identifier of a document.

    status (string)

    Sendout status of a document.

    The value of this property must match exactly one of the following schemas:

    (string)

    Document is waiting to be started. Depending on the number of documents in the bulk send, this can take a few minutes.

    Value: "scheduled"

    (string)

    Document signing process was successfully started.

    Value: "started"

    (string)

    Document start was aborted due to unexpected errors.

    For more information, please contact Scrive support and include the bulk send ID and the document ID.

    Value: "cancelled"

    Bulk send list descriptor

    JSON array of recent bulk send calls.

    Bulk send list descriptor

    (array)

    Example JSON: for "Bulk send list descriptor"

    [
  {
    "id": "314",
    "name": "Rent contract prolongation",
    "created_at": "2022-07-12T17:19:56.126709Z"
  }
]

    Lists basic information about recent bulk send calls.

    All array elements must be of type:

    (object)

    This object has the following properties:

    id (string)

    Unique identifier of a bulk send.

    Will not change over time, and cannot be changed.

    name (string)

    Label provided during bulk send call.

    Usually, it will likely correlate with the name of the document.

    created_at (string)

    Date and time of bulk send creation.

    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,
      "signatory_role": "viewer",
      "signatory_status": "invitation_sent",
      "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",
      "authentications": {
        "view": {
          "name": "standard"
        },
        "sign": {
          "name": "standard"
        },
        "view_archived": {
          "name": "standard"
        }
      },
      "authentication_method_to_view": "standard",
      "authentication_method_to_view_archived": "standard",
      "authentication_method_to_sign": "standard",
      "confirmation_delivery_method": "none",
      "notification_delivery_method": "none",
      "allows_highlighting": false,
      "attachments": [],
      "highlighted_pages": [],
      "api_delivery_url": null
    },
    {
      "id": "189256",
      "user_id": null,
      "is_author": false,
      "is_signatory": true,
      "signatory_role": "signing_party",
      "signatory_status": "invitation_sent",
      "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",
      "authentications": {
        "view": {
          "name": "standard"
        },
        "sign": {
          "name": "onfido",
          "settings": {
            "report": "document_only",
            "identity_document_types": [
              "id_card",
              "passport"
            ],
            "identity_document_countries": null,
            "ui_locale": "en-US",
            "force_mobile_document_capture": true
          }
        },
        "view_archived": {
          "name": "standard"
        }
      },
      "authentication_method_to_view": "standard",
      "authentication_method_to_view_archived": "standard",
      "authentication_method_to_sign": "onfido",
      "confirmation_delivery_method": "none",
      "notification_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,
    "show_arrow": true
  },
  "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"
  },
  "experimental_features": {
    "signatory_status_summary": "invitations_sent"
  }
}

    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 (string,null, 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)

    Deprecated, please use signatory_role instead. If true, this party is a signatory to the document, otherwise they are a viewer or an approver and will not sign the document. If both is_signatory and signatory_role are present, is_signatory takes precedence if their values are inconsistent (this is done for backwards compatibility).

    signatory_role (string, enum)

    Signatory role: viewer, approver, or a signing party. Only signing parties can sign documents, viewers only have view access, and approvers can additionally approve or reject. Whether the approver is hidden or visible is controlled by the flag is_visible.

    The value of this property must be one of the following enum values:

    • "viewer"
    • "signing_party"
    • "approver"
    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.
    • SignatoryFieldFullName: Computed combination of the above two.
    • 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.
    • SignatoryFieldDate: A date input field.
    • SignatoryFieldSignDate: The date of signing of this 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.

    Each element of this array must match at least one of the following schemas:

    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.

    The value of this property 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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldFullName (object)

    Signatory field displaying full name of the respective signatory. Note: this field doesn't contain value of its own and when displaying the text will be derived from the "firstname" and "lastname" field values.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a full name field.

    The value of this property must be one of the following enum values:

    • "full_name"
    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldSignature (object)

    A signatory field for placing signature boxes on the document.

    This object has the following properties:

    type (string, enum, required)

    The value of this property 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 (read only)

    The value of this property must match at least one of the following schemas:

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

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property must be one of the following enum values:

    • 0
    fsrel (number, enum, required)

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

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    custom_validation

    The value of this property must match exactly one of the following schemas:

    (null)
    SignatoryFieldCustomValidation (object)

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

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

    description (string,null)

    Description of this field

    SignatoryFieldDate (object)

    Signatory field for dates. Optionally can impose restrictions on start and/or end date (either absolute or relative to document view).

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a date field.

    The value of this property must be one of the following enum values:

    • "date"
    name (string, required)

    A name for the date 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,null)

    Either a pre-filled value, or the value entered by the signatory. Must be specified as ISO8601 date.

    Default: null

    is_obligatory (boolean)

    Default: true

    should_be_filled_by_sender (boolean)

    Default: false

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    configuration (object, required)

    Definition of optional restriction imposed upon start and/or end date. Null means no restriction.

    The configuration object has the following properties:

    start_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    end_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    SignatoryFieldSignDate (object)

    Signatory field displaying sign date of the respective signatory.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a sign date field.

    The value of this property must be one of the following enum values:

    • "sign_date"
    value (string,null)

    Date when the signatory has signed or null if not yet signed. Formatted as ISO8601 date. Read only.

    Default: null

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    sign_order (integer)

    Default: 1

    sign_time (string,null, read only)
    seen_time (string,null, read only)
    deferred_time (string,null, read only)
    read_invitation_time (string,null, read only)
    rejected_time (string,null, read only)
    rejection_reason (string,null, 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,null)

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

    reject_redirect_url (string,null)

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

    email_delivery_status (string, enum)

    The current delivery status.

    The value of this property must be one of the following enum values:

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

    The current delivery status.

    The value of this property must be one of the following enum values:

    • "unknown"
    • "not_delivered"
    • "delivered"
    • "deferred"
    has_authenticated_to_view (boolean, read only)

    If a person has identified to view the document.

    csv (array,null)
    delivery_method (string, enum)

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface. Furthermore, pad delivery is referred to as "In-person".

    Default: "email"

    The value of this property must be one of the following enum values:

    • "email"
    • "mobile"
    • "email_mobile"
    • "pad"
    • "api"
    authentications (object)

    Authentication object replacing individual properties authentication_method_to_view, authentication_method_to_sign and authentication_method_to_view_archived. This object has to be fully defined when present and has lower priority than individual properties so to use it, you have remove those individual properties from the signatory object. Unlike individual authentication properties, this authentication object also supports provider specific settings.

    The authentications object has the following properties:

    view (object)

    This setting forces signatories to authenticate using the supplied identification method to view the document before signing.

    Will be overridden by authentication_method_to_view property when both are present.

    The view object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    sign (object)

    This setting forces user to authenticate to sign.

    Will be overridden by authentication_method_to_sign property when both are present.

    The sign object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"
    settings (object,null)

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to sign settings

    swisscom (object)

    See: Swisscom authentication to sign settings

    view_archived (object)

    This setting forces signatories to authenticate using the supplied identification method to view the document once it has been signed and resides in the e-archive.

    Will be overridden by authentication_method_to_view_archived property when both are present.

    The view_archived object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    authentication_method_to_view (string, enum)

    This setting forces signatories to authenticate using the supplied identification method to view the document before signing.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    authentication_method_to_view_archived (string, enum)

    This setting forces signatories to authenticate using the supplied identification method to view the document once it has been signed and resides in the e-archive.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    authentication_method_to_sign (string, enum)

    This setting forces user to authenticate to sign.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"
    • "smart_id_qes"
    confirmation_delivery_method (string, enum)

    Deliver a confirmation message about the document signing status by:

    • email an email including a file attachment of the signed document
    • mobile a text message with a link to the signed document
    • email_mobile both of the two above
    • email_link an email with a link to the signed document
    • email_link_mobile an email and a text message with a link to the signed document
    • none no delivery at all

    Default: "email"

    The value of this property must be one of the following enum values:

    • "email"
    • "mobile"
    • "email_mobile"
    • "email_link"
    • "email_link_mobile"
    • "none"
    notification_delivery_method (string, enum)

    Deliver a confirmation notification that the party signed/approved the document by:

    • email an email including a link to the document
    • mobile a text message including a link to the document
    • email_mobile both of the two above
    • none no delivery at all

    Default: "none"

    The value of this property 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

    can_forward (boolean)

    Whether the signatory can forward the signing process to someone else.

    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)

    A signatory attachment - 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.

    add_to_sealed_file (boolean)

    Should the file of this attachment be merged into the final sealed document?

    Default: true

    api_delivery_url (string,null)

    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

    The value of this property must match exactly one of the following schemas:

    (null)
    (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.

    This 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 (boolean)

    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.

    is_visible (bool,null)

    Determines if an approver or viewer is visible in verification page and sign view.

    This value is only used for approvers and viewers, it has to be null for signing_party signatories.

    Default: "null"

    document_roles (array)

    List of "roles" this signatory has within the document.

    The individual roles can be arbitrary texts (often in local language of the document). Those roles (if specified) will be part of the evidence log and also will be displayed in sign view (user signs/approves the document in the following roles).

    Default:
    []

    All array elements must be of type:

    (string)

    experimental (object)

    ⚠️ WARNING: EXPERIMENTAL ⚠️

    Experimental properties are not part of public API. Therefore they're not supported and are subject to change without prior notice.

    The experimental object has the following properties:

    signatory_status (string, enum, read only)

    The current status of the signatory in relation to the document.

    The statuses document_problem, document_draft, document_canceled, document_timedout and document_rejected are reflecting the status field of the underlying document for convenience.

    The value of this property must be one of the following enum values:

    • "document_problem"
    • "document_draft"
    • "document_canceled"
    • "document_timedout"
    • "document_rejected"
    • "waiting_for_prior_signatures"
    • "invitation_sent"
    • "invitation_delivery_problem"
    • "invitation_delivered"
    • "invitation_read"
    • "document_opened"
    • "document_deferred"
    • "document_signed"
    • "document_approved"
    • "confirmation_delivery_problem"

    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

    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 value of this property must match exactly one of the following schemas:

    (null)

    File (object)

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

    This object has the following properties:

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

    author_attachments (array, read only)

    List of author attachments.

    These documents are to be reviewed by the signatory parties, and are uploaded by the author of the document. 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,null, read only)

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

    auto_remind_time (string,null, 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". However if the document was started using bulk send feature, it will first transition into "awaiting_start", and shortly after that into "pending".

    Documents in "awaiting_start" cannot be modified, trashed or canceled.

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

    The value of this property must be one of the following enum values:

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

    days_to_sign (integer)

    Default: 90

    days_to_remind (integer,null)

    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.

    show_arrow (boolean)

    Whether to show the auto-scroll arrow on the signing page.

    show_form (boolean)

    Whether to show the fields as a form on the signing page.

    show_form_arrow (boolean)

    Whether to show the auto-scroll arrow on the form page.

    invitation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    sms_invitation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    confirmation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    sms_confirmation_message (string)

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

    Default is blank meaning that a default message will be used.

    Default: ""

    lang (string, enum)

    Currently supported language codes

    The value of this property must be one of the following enum values:

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

    api_callback_url (string,null)

    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)

    The value of this property must be one of the following enum values:

    • "company_shared"
    • "company_admin"
    • "signatory"

    signatory_id (string)

    experimental_features (object)

    ⚠️ WARNING: EXPERIMENTAL ⚠️

    Experimental properties are not part of public API. Therefore they're not supported and are subject to change without prior notice.

    The experimental_features object has the following properties:

    signatory_status_summary (string, enum, read only)

    The document status in relation to its signatories.

    The statuses document_template, document_problem, document_draft, document_signed, document_canceled, document_timedout and document_rejected are reflecting the status field of the underlying document for convenience.

    A document with document_opened has been opened by all of its signatories.

    A document with invitations_read has all of its signatories having read the invitations to sign or approve. Some might have opened the document as well, but not all.

    A document with invitations_delivered has all the invitations delivered.

    A document with invitation_delivery_problem has some invitation with a delivery problem.

    A document with invitation_sent has all invitations sent but not all delivered neither opened or read.

    When several signing stages (a.k.a. invitation orders) are defined for the document, only the signatories in the current and previous stages are taken into account to determine the status.

    The value of this property must be one of the following enum values:

    • "document_template"
    • "document_problem"
    • "document_draft"
    • "invitations_sent"
    • "invitations_delivered"
    • "invitation_delivery_problem"
    • "invitations_read"
    • "document_opened"
    • "document_signed"
    • "document_canceled"
    • "document_timedout"
    • "document_rejected"

    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". However if the document was started using bulk send feature, it will first transition into "awaiting_start", and shortly after that into "pending".

    Documents in "awaiting_start" cannot be modified, trashed or canceled.

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

    The value of this property must be one of the following enum values:

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

    Signatory

    (object)

    Example JSON: for "Signatory"

    {
  "id": "189256",
  "user_id": null,
  "is_author": false,
  "is_signatory": true,
  "signatory_role": "signing_party",
  "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": "full_name",
      "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": "sign_date",
      "value": null,
      "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",
  "authentications": {
    "view": {
      "name": "standard"
    },
    "sign": {
      "name": "onfido",
      "settings": {
        "report": "document_only",
        "identity_document_types": [
          "id_card",
          "passport"
        ],
        "identity_document_countries": null,
        "ui_locale": "en-US",
        "force_mobile_document_capture": true
      }
    },
    "view_archived": {
      "name": "standard"
    }
  },
  "authentication_method_to_view": "standard",
  "authentication_method_to_view_archived": "standard",
  "authentication_method_to_sign": "onfido",
  "confirmation_delivery_method": "none",
  "notification_delivery_method": "none",
  "allows_highlighting": true,
  "hide_personal_number": false,
  "attachments": [
    {
      "name": "Driving licence",
      "description": "A picture of driving licence",
      "required": true,
      "add_to_sealed_file": true
    }
  ],
  "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."
        }
      }
    ]
  },
  "is_visible": null,
  "document_roles": [
    "Director",
    "Board Member"
  ]
}

    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 (string,null, 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)

    Deprecated, please use signatory_role instead. If true, this party is a signatory to the document, otherwise they are a viewer or an approver and will not sign the document. If both is_signatory and signatory_role are present, is_signatory takes precedence if their values are inconsistent (this is done for backwards compatibility).

    signatory_role (string, enum)

    Signatory role: viewer, approver, or a signing party. Only signing parties can sign documents, viewers only have view access, and approvers can additionally approve or reject. Whether the approver is hidden or visible is controlled by the flag is_visible.

    The value of this property must be one of the following enum values:

    • "viewer"
    • "signing_party"
    • "approver"

    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.
    • SignatoryFieldFullName: Computed combination of the above two.
    • 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.
    • SignatoryFieldDate: A date input field.
    • SignatoryFieldSignDate: The date of signing of this 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.

    Each element of this array must match at least one of the following schemas:

    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.

    The value of this property 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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldFullName (object)

    Signatory field displaying full name of the respective signatory. Note: this field doesn't contain value of its own and when displaying the text will be derived from the "firstname" and "lastname" field values.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a full name field.

    The value of this property must be one of the following enum values:

    • "full_name"
    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldSignature (object)

    A signatory field for placing signature boxes on the document.

    This object has the following properties:

    type (string, enum, required)

    The value of this property 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 (read only)

    The value of this property must match at least one of the following schemas:

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

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property must be one of the following enum values:

    • 0
    fsrel (number, enum, required)

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

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    custom_validation

    The value of this property must match exactly one of the following schemas:

    (null)
    SignatoryFieldCustomValidation (object)

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

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

    description (string,null)

    Description of this field

    SignatoryFieldDate (object)

    Signatory field for dates. Optionally can impose restrictions on start and/or end date (either absolute or relative to document view).

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a date field.

    The value of this property must be one of the following enum values:

    • "date"
    name (string, required)

    A name for the date 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,null)

    Either a pre-filled value, or the value entered by the signatory. Must be specified as ISO8601 date.

    Default: null

    is_obligatory (boolean)

    Default: true

    should_be_filled_by_sender (boolean)

    Default: false

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    configuration (object, required)

    Definition of optional restriction imposed upon start and/or end date. Null means no restriction.

    The configuration object has the following properties:

    start_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    end_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    SignatoryFieldSignDate (object)

    Signatory field displaying sign date of the respective signatory.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a sign date field.

    The value of this property must be one of the following enum values:

    • "sign_date"
    value (string,null)

    Date when the signatory has signed or null if not yet signed. Formatted as ISO8601 date. Read only.

    Default: null

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    sign_order (integer)

    Default: 1

    sign_time (string,null, read only)

    seen_time (string,null, read only)

    deferred_time (string,null, read only)

    read_invitation_time (string,null, read only)

    rejected_time (string,null, read only)

    rejection_reason (string,null, 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,null)

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

    reject_redirect_url (string,null)

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

    email_delivery_status (string, enum)

    The current delivery status.

    The value of this property must be one of the following enum values:

    • "unknown"
    • "not_delivered"
    • "delivered"
    • "deferred"

    mobile_delivery_status (string, enum)

    The current delivery status.

    The value of this property must be one of the following enum values:

    • "unknown"
    • "not_delivered"
    • "delivered"
    • "deferred"

    has_authenticated_to_view (boolean, read only)

    If a person has identified to view the document.

    csv (array,null)

    delivery_method (string, enum)

    Note that api delivery is referred to as "Link" delivery in the Scrive Web interface. Furthermore, pad delivery is referred to as "In-person".

    Default: "email"

    The value of this property must be one of the following enum values:

    • "email"
    • "mobile"
    • "email_mobile"
    • "pad"
    • "api"

    authentications (object)

    Authentication object replacing individual properties authentication_method_to_view, authentication_method_to_sign and authentication_method_to_view_archived. This object has to be fully defined when present and has lower priority than individual properties so to use it, you have remove those individual properties from the signatory object. Unlike individual authentication properties, this authentication object also supports provider specific settings.

    The authentications object has the following properties:

    view (object)

    This setting forces signatories to authenticate using the supplied identification method to view the document before signing.

    Will be overridden by authentication_method_to_view property when both are present.

    The view object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    sign (object)

    This setting forces user to authenticate to sign.

    Will be overridden by authentication_method_to_sign property when both are present.

    The sign object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"
    settings (object,null)

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to sign settings

    swisscom (object)

    See: Swisscom authentication to sign settings

    view_archived (object)

    This setting forces signatories to authenticate using the supplied identification method to view the document once it has been signed and resides in the e-archive.

    Will be overridden by authentication_method_to_view_archived property when both are present.

    The view_archived object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"
    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    authentication_method_to_view (string, enum)

    This setting forces signatories to authenticate using the supplied identification method to view the document before signing.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"

    authentication_method_to_view_archived (string, enum)

    This setting forces signatories to authenticate using the supplied identification method to view the document once it has been signed and resides in the e-archive.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"

    authentication_method_to_sign (string, enum)

    This setting forces user to authenticate to sign.

    Default: "standard"

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"
    • "smart_id_qes"

    confirmation_delivery_method (string, enum)

    Deliver a confirmation message about the document signing status by:

    • email an email including a file attachment of the signed document
    • mobile a text message with a link to the signed document
    • email_mobile both of the two above
    • email_link an email with a link to the signed document
    • email_link_mobile an email and a text message with a link to the signed document
    • none no delivery at all

    Default: "email"

    The value of this property must be one of the following enum values:

    • "email"
    • "mobile"
    • "email_mobile"
    • "email_link"
    • "email_link_mobile"
    • "none"

    notification_delivery_method (string, enum)

    Deliver a confirmation notification that the party signed/approved the document by:

    • email an email including a link to the document
    • mobile a text message including a link to the document
    • email_mobile both of the two above
    • none no delivery at all

    Default: "none"

    The value of this property 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

    can_forward (boolean)

    Whether the signatory can forward the signing process to someone else.

    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)

    A signatory attachment - 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.

    add_to_sealed_file (boolean)

    Should the file of this attachment be merged into the final sealed document?

    Default: true

    api_delivery_url (string,null)

    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

    The value of this property must match exactly one of the following schemas:

    (null)

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

    This 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 (boolean)

    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.

    is_visible (bool,null)

    Determines if an approver or viewer is visible in verification page and sign view.

    This value is only used for approvers and viewers, it has to be null for signing_party signatories.

    Default: "null"

    document_roles (array)

    List of "roles" this signatory has within the document.

    The individual roles can be arbitrary texts (often in local language of the document). Those roles (if specified) will be part of the evidence log and also will be displayed in sign view (user signs/approves the document in the following roles).

    Default:
    []

    All array elements must be of type:

    (string)

    experimental (object)

    ⚠️ WARNING: EXPERIMENTAL ⚠️

    Experimental properties are not part of public API. Therefore they're not supported and are subject to change without prior notice.

    The experimental object has the following properties:

    signatory_status (string, enum, read only)

    The current status of the signatory in relation to the document.

    The statuses document_problem, document_draft, document_canceled, document_timedout and document_rejected are reflecting the status field of the underlying document for convenience.

    The value of this property must be one of the following enum values:

    • "document_problem"
    • "document_draft"
    • "document_canceled"
    • "document_timedout"
    • "document_rejected"
    • "waiting_for_prior_signatures"
    • "invitation_sent"
    • "invitation_delivery_problem"
    • "invitation_delivered"
    • "invitation_read"
    • "document_opened"
    • "document_deferred"
    • "document_signed"
    • "document_approved"
    • "confirmation_delivery_problem"

    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": []
    }
  ],
  "description": "Name field"
}

    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.

    The value of this property 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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    SignatoryFieldFullName

    (object)

    Example JSON: for "SignatoryFieldFullName"

    {
  "type": "full_name",
  "placements": [
    {
      "xrel": 0.29368421052631577,
      "yrel": 0.3444940476190476,
      "wrel": 0.10842105263157895,
      "hrel": 0.025297619047619048,
      "fsrel": 0.016842105263157894,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ]
}

    Signatory field displaying full name of the respective signatory. Note: this field doesn't contain value of its own and when displaying the text will be derived from the "firstname" and "lastname" field values.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a full name field.

    The value of this property must be one of the following enum values:

    • "full_name"

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    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": []
    }
  ],
  "description": "Phone number field"
}

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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": []
    }
  ],
  "description": "Signature field"
}

    A signatory field for placing signature boxes on the document.

    This object has the following properties:

    type (string, enum, required)

    The value of this property 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 (read only)

    The value of this property must match at least one of the following schemas:

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

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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": []
    }
  ],
  "description": "Company field"
}

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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": []
    }
  ],
  "description": "Checkbox field"
}

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property must be one of the following enum values:

    • 0
    fsrel (number, enum, required)

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

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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"
  ],
  "description": "Radio group field"
}

    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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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.

    The value of this property 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 value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field

    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'."
  },
  "description": "Custom name field"
}

    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.

    The value of this property 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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    custom_validation

    The value of this property must match exactly one of the following schemas:

    (null)

    SignatoryFieldCustomValidation (object)

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

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

    description (string,null)

    Description of this field

    SignatoryFieldDate

    (object)

    Example JSON: for "SignatoryFieldDate"

    {
  "type": "date",
  "name": "Date field",
  "value": null,
  "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": []
    }
  ],
  "configuration": {
    "start_date": {
      "type": "relative-to-doc-view",
      "value": 5
    },
    "end_date": {
      "type": "absolute",
      "value": "2020-01-01"
    }
  }
}

    Signatory field for dates. Optionally can impose restrictions on start and/or end date (either absolute or relative to document view).

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a date field.

    The value of this property must be one of the following enum values:

    • "date"

    name (string, required)

    A name for the date 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,null)

    Either a pre-filled value, or the value entered by the signatory. Must be specified as ISO8601 date.

    Default: null

    is_obligatory (boolean)

    Default: true

    should_be_filled_by_sender (boolean)

    Default: false

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    configuration (object, required)

    Definition of optional restriction imposed upon start and/or end date. Null means no restriction.

    The configuration object has the following properties:

    start_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    end_date (required)

    The value of this property must match exactly one of the following schemas:

    (null)
    DateConfig (object)

    Describes restriction imposed on start or end date of a signatory date field. The threshold is based on document view date, plus (or minus, if "value" is negative) the number of days defined in "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "relative-to-doc-view"
    value (integer)

    DateConfig (object)

    Describes restricted imposed on start or end date of a signatory date field. The threshold is the date specified by "value".

    This object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "absolute"
    value (string)

    Must be specified as ISO8601 date between 1900-01-01 and 2200-12-31.

    SignatoryFieldSignDate

    (object)

    Example JSON: for "SignatoryFieldSignDate"

    {
  "type": "sign_date",
  "value": "2021-10-03",
  "placements": [
    {
      "xrel": 0.29368421052631577,
      "yrel": 0.3444940476190476,
      "wrel": 0.10842105263157895,
      "hrel": 0.025297619047619048,
      "fsrel": 0.016842105263157894,
      "page": 1,
      "tip": "right",
      "anchors": []
    }
  ]
}

    Signatory field displaying sign date of the respective signatory.

    This object has the following properties:

    type (string, enum, required)

    Used to specify that this is a sign date field.

    The value of this property must be one of the following enum values:

    • "sign_date"

    value (string,null)

    Date when the signatory has signed or null if not yet signed. Formatted as ISO8601 date. Read only.

    Default: null

    placements (array)

    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)

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

    yrel (number)

    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 height, from 0 to 1.

    fsrel (number, required)

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

    page (integer)

    The page number for this placement, starting from 1.

    tip

    Default: null

    The value of this property must match at least one of the following schemas:

    (string, enum)

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

    The value of this property 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, required)
    index (integer, required)
    offset (object)

    The offset object has the following properties:

    x (number)

    Relative X offset from the anchored text position.

    y (number)

    Relative Y offset from the anchored text position.

    description (string,null)

    Description of this field.

    Authentication to view with settings

    (object)

    This object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "verimi"

    settings

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to view settings

    Authentication to sign with settings

    (object)

    This object has the following properties:

    name (string, enum, required)

    The value of this property must be one of the following enum values:

    • "standard"
    • "sms_pin"
    • "sms_otp"
    • "dk_mitid"
    • "dk_mitid_erhverv"
    • "fi_tupas"
    • "freja"
    • "nl_idin"
    • "no_bankid"
    • "onfido"
    • "onfido_document_check"
    • "onfido_document_and_photo_check"
    • "se_bankid"
    • "swisscom_qes"
    • "swisscom_qes_with_srs"
    • "verimi_qes"
    • "itsme"

    settings (object,null)

    Schema of this object depends on selected authentication name.

    The value of this property must match exactly one of the following schemas:

    onfido (object)

    See: Onfido authentication settings

    freja (object)

    See: Freja authentication to sign settings

    swisscom (object)

    See: Swisscom authentication to sign settings

    Onfido authentication settings

    (object)

    Example JSON: for "Onfido authentication settings"

    {
  "report": "document_and_video",
  "identity_document_types": [
    "passport",
    "id_card"
  ],
  "identity_document_countries": [
    "afg",
    "alb",
    "cck",
    "zwe"
  ],
  "ui_locale": null,
  "force_mobile_document_capture": false
}

    Onfido specific settings for authentication to view/sign/view archived.

    Default:
    { "report": "document_only", "identity_document_types": null, "identity_document_countries": null, "ui_locale": "en-US", "force_mobile_document_capture": true }

    This object has the following properties:

    report (required)

    The way user will authenticate with Onfido.

    The value of this property must match exactly one of the following schemas:

    (string)

    User will only provide photo of their identity document.

    Value: "document_only"

    (string)

    User will provide photo of their identity document and a photo of their face for comparison.

    Value: "document_and_photo"

    (string)

    User will provide photo of their identity document and a short video clip of their face for comparison.

    Value: "document_and_video"

    identity_document_types

    Restricts allowed identity documents by type.

    Currently only includes the types supported by EID Hub. The frontend will indicate what type of document should be used, however this does not stop the end-user from using a different type of document. Onfido will analyse the document and we will only accept document types that match this parameter. If not specified (null), any document type will be accepted, including those supported by Onfido but not listed here.

    For full list of supported document types by country, visit Onfido - supported documents.

    Default: null

    The value of this property must match exactly one of the following schemas:

    (null)

    Allows any supported document type

    (array)

    Non-empty list of allowed document types

    All array elements must be of type:

    (string, enum)

    The value of this property must be one of the following enum values:

    • "id_card"
    • "passport"
    • "driving_license"
    • "residence_permit"

    identity_document_countries

    Restricts allowed identity document by country. For list of supported document by country, visit Onfido - supported documents.

    Default: null

    The value of this property must match exactly one of the following schemas:

    (null)

    Allows any supported country

    (array)

    Non-empty list of allowed document countries specified using 3 letter country codes - Wikipedia - ISO_3166-1_alpha-3

    All array elements must be of type:

    (string, enum)

    The value of this property must be one of the following enum values:

    • "afg"
    • "alb"
    • "dza"
    • "asm"
    • "and"
    • "ago"
    • "aia"
    • "atg"
    • "arg"
    • "arm"
    • "abw"
    • "aus"
    • "aut"
    • "aze"
    • "bhs"
    • "bhr"
    • "bgd"
    • "brb"
    • "blr"
    • "bel"
    • "blz"
    • "ben"
    • "bmu"
    • "btn"
    • "bol"
    • "bih"
    • "bwa"
    • "bra"
    • "brn"
    • "bgr"
    • "bfa"
    • "bdi"
    • "khm"
    • "cmr"
    • "can"
    • "cpv"
    • "cym"
    • "caf"
    • "tcd"
    • "chl"
    • "chn"
    • "cxr"
    • "cck"
    • "col"
    • "com"
    • "cog"
    • "cod"
    • "cri"
    • "hrv"
    • "cub"
    • "cyp"
    • "cze"
    • "civ"
    • "dnk"
    • "dji"
    • "dma"
    • "dom"
    • "ecu"
    • "egy"
    • "slv"
    • "gnq"
    • "eri"
    • "est"
    • "eth"
    • "fro"
    • "fji"
    • "fin"
    • "fra"
    • "pyf"
    • "gab"
    • "gmb"
    • "geo"
    • "deu"
    • "gha"
    • "gib"
    • "grc"
    • "grl"
    • "grd"
    • "gum"
    • "gtm"
    • "ggy"
    • "gin"
    • "gnb"
    • "guy"
    • "hti"
    • "vat"
    • "hnd"
    • "hkg"
    • "hun"
    • "isl"
    • "ind"
    • "idn"
    • "irn"
    • "irq"
    • "irl"
    • "imn"
    • "isr"
    • "ita"
    • "jam"
    • "jpn"
    • "jey"
    • "jor"
    • "kaz"
    • "ken"
    • "kir"
    • "prk"
    • "kor"
    • "xkx"
    • "kwt"
    • "kgz"
    • "lao"
    • "lva"
    • "lbn"
    • "lso"
    • "lbr"
    • "lby"
    • "lie"
    • "ltu"
    • "lux"
    • "mac"
    • "mkd"
    • "mdg"
    • "mwi"
    • "mys"
    • "mdv"
    • "mli"
    • "mlt"
    • "mhl"
    • "mrt"
    • "mus"
    • "mex"
    • "fsm"
    • "mda"
    • "mco"
    • "mng"
    • "mne"
    • "msr"
    • "mar"
    • "moz"
    • "mmr"
    • "nam"
    • "nru"
    • "npl"
    • "nld"
    • "nzl"
    • "nic"
    • "ner"
    • "nga"
    • "mnp"
    • "nor"
    • "omn"
    • "pak"
    • "plw"
    • "pse"
    • "pan"
    • "png"
    • "pry"
    • "per"
    • "phl"
    • "pol"
    • "prt"
    • "pri"
    • "qat"
    • "rou"
    • "rus"
    • "rwa"
    • "blm"
    • "shn"
    • "kna"
    • "lca"
    • "maf"
    • "vct"
    • "wsm"
    • "smr"
    • "stp"
    • "sau"
    • "sen"
    • "srb"
    • "syc"
    • "sle"
    • "sgp"
    • "sxm"
    • "svk"
    • "svn"
    • "slb"
    • "som"
    • "zaf"
    • "ssd"
    • "esp"
    • "lka"
    • "sdn"
    • "sur"
    • "swz"
    • "swe"
    • "che"
    • "syr"
    • "twn"
    • "tjk"
    • "tza"
    • "tha"
    • "tls"
    • "tgo"
    • "ton"
    • "tto"
    • "tun"
    • "tur"
    • "tkm"
    • "tca"
    • "tuv"
    • "uga"
    • "ukr"
    • "are"
    • "gbr"
    • "usa"
    • "ury"
    • "uzb"
    • "vut"
    • "ven"
    • "vnm"
    • "vgb"
    • "vir"
    • "yem"
    • "zmb"
    • "zwe"

    ui_locale

    Controls locale of Onfido authentication process.

    Default: null

    The value of this property must match exactly one of the following schemas:

    (null)

    Tries to match the Onfido locale with locale of signed document. Uses English when no match is possible.

    (string, enum)

    The value of this property must be one of the following enum values:

    • "en-US"
    • "es-ES"
    • "de-DE"
    • "fr-FR"
    • "it-IT"
    • "pt-PT"

    force_mobile_document_capture (boolean, required)

    Forces desktop users to use a mobile device to take document photo.

    Freja authentication to view settings

    (object)

    Example JSON: for "Freja authentication to view settings"

    {
  "enforce_plus_registration_level": true
}

    Freja specific settings for authentication to view/view archived.

    This object has the following properties:

    enforce_plus_registration_level (bool)

    Whether or not plus registration level should be enforced

    Freja authentication to sign settings

    (object)

    Example JSON: for "Freja authentication to sign settings"

    {
  "enforce_plus_registration_level": true,
  "push_notification": null,
  "sign_title": "Rental agreement"
}

    Freja specific settings for authentication to sign.

    This object has the following properties:

    enforce_plus_registration_level (bool)

    Whether or not plus registration level should be enforced

    push_notification (object)

    Information to display in push notification

    Default: null

    The push_notification object has the following properties:

    title (string)

    Text of the push notification title

    text (string)

    Text of the push notification description

    sign_title (string)

    The title of the sign transaction

    Default: null

    Swisscom authentication to sign settings

    (object)

    Example JSON: for "Swisscom authentication to sign settings"

    {
  "language": "de",
  "registration_methods": [
    "InPerson",
    "VideoIdent",
    "RoboIdent"
  ]
}

    Swisscom specific settings (for authentication to sign).

    This object has the following properties:

    language

    Swisscom language code.

    Default: null

    The value of this property must match exactly one of the following schemas:

    (null)

    Tries to match the Swisscom locale with locale of signed document. Uses English when no match is possible.

    (string, enum)

    The value of this property must be one of the following enum values:

    • "en"
    • "de"
    • "fr"
    • "it"
    • "pl"

    registration_methods (array)

    Allowed Swisscom SRS (Smart Registration Service) registration methods (if any).

    Default:
    []

    Each element of this array must match at least one of the following schemas:

    (string)

    Registration in selected Swisscom Shops as a certified registration point for the qualified electronic signature.

    Value: "InPerson"

    (string)

    Online video call registration with live agent using passport or ID Card.

    Value: "VideoIdent"

    (string)

    Online registration using an ICAO compliant biometric passport or a German ID card.

    Value: "RoboIdent"

    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:
    []

    Each element of this array must match at least one of the following schemas:

    Filter by status (object)

    This object has the following properties:

    filter_by (string, enum)

    The value of this property 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". However if the document was started using bulk send feature, it will first transition into "awaiting_start", and shortly after that into "pending".

    Documents in "awaiting_start" cannot be modified, trashed or canceled.

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

    The value of this property must be one of the following enum values:

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

    Filter by mtime (object)

    This object has the following properties:

    filter_by (string, enum)

    The value of this property 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)

    The value of this property 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)

    The value of this property 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)

    The value of this property 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)

    The value of this property must be one of the following enum values:

    • "is_template"

    Only non-templates (object)

    This object has the following properties:

    filter_by (string, enum)

    The value of this property must be one of the following enum values:

    • "is_not_template"

    In trash (object)

    This object has the following properties:

    filter_by (string, enum)

    The value of this property 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)

    The value of this property 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)

    The value of this property 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)

    The value of this property 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)

    The value of this property 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"

    The value of this property must be one of the following enum values:

    • "ascending"
    • "descending"

    sort_by (string, enum, required)

    The value of this property 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.

    Each element of this array must match at least one of the following schemas:

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

    The value of this property must be one of the following enum values:

    • "initiated"
    • "draft"
    • "cancelled"
    • "rejected"
    • "timeouted"
    • "problem"
    • "deliveryproblem"
    • "sent"
    • "delivered"
    • "read"
    • "opened"
    • "signed"
    • "prolonged"
    • "sealed"
    • "extended"
    • "authenticationview"
    • "authenticated"
    • "approved"
    time (string)
    text (string)

    The text describing the action.

    party (string)

    The name of the party performing the action.

    Attachment

    (object)

    Example JSON: for "Attachment"

    {
  "id": "2",
  "title": "Terms and conditions",
  "user_id": "42",
  "time": "2018-06-21T08:25:22.644059Z",
  "shared": false,
  "file": "2"
}

    A pre-uploaded attachment which can later be used when creating or signing documents.

    This object has the following properties:

    id (string, read only)

    Unique identifier for an attachment.

    Will not change over time, and cannot be changed.

    title (string, read only)

    The title of the attachment.

    The title will be used when listing attachments.

    user_id (string, read only)

    The unique identifier of the authoring user.

    file (string, read only)

    The attachment’s file ID.

    shared (boolean)

    Sharing status.

    Whether the attachment is shared with the other members of the company.

    time (string, read only)

    Time at which the attachment was added.

    Attachment List Filter

    (array)

    Example JSON: for "Attachment List Filter"

    [
  {
    "filter_by": "text",
    "text": "keyword"
  }
]

    Parameter used to filter attachments for the list API call.

    Default:
    []

    Each element of this array must match at least one of the following schemas:

    Filter by text (object)

    This object has the following properties:

    filter_by (string, enum)

    The value of this property must be one of the following enum values:

    • "text"

    text (string)

    Attachment List Sorting

    (array)

    Example JSON: for "Attachment List Sorting"

    [
  {
    "sort_by": "title",
    "order": "ascending"
  }
]

    Parameter used to sort attachments for the list API call.

    All array elements must be of type:

    (object)

    This object has the following properties:

    order (string, enum)

    Default: "descending"

    The value of this property must be one of the following enum values:

    • "ascending"
    • "descending"

    sort_by (string, enum, required)

    Default: "time"

    The value of this property must be one of the following enum values:

    • "title"
    • "time"

    DataRetentionPolicy

    (object)

    Example JSON: for "DataRetentionPolicy"

    {
  "idle_doc_timeout_canceled": 45,
  "immediate_trash": true,
  "idle_doc_timeout_error": 67,
  "idle_doc_timeout_preparation": 32
}

    An object with data retention policy properties.

    This object has the following properties:

    immediate_trash (boolean)

    Option to delete documents in trash immediately

    idle_doc_timeout_preparation (integer)

    Number of days before moving documents in preparation to trash

    idle_doc_timeout_closed (integer)

    Number of days before moving closed documents to trash

    idle_doc_timeout_canceled (integer)

    Number of days before moving cancelled documents to trash

    idle_doc_timeout_timedout (integer)

    Number of days before moving timed out documents to trash

    idle_doc_timeout_rejected (integer)

    Number of days before moving rejected documents to trash

    idle_doc_timeout_error (integer)

    Number of days before moving documents with errors to trash

    DataRetentionPolicies

    (object)

    Example JSON: for "DataRetentionPolicies"

    {
  "company_data_retention_policy": {
    "immediate_trash": false
  },
  "data_retention_policy": {
    "idle_doc_timeout_canceled": 45,
    "immediate_trash": true,
    "idle_doc_timeout_error": 67,
    "idle_doc_timeout_preparation": 32
  }
}

    An object with data retention policies properties.

    This object has the following properties:

    company_data_retention_policy (object)

    An object with data retention policy properties.

    The company_data_retention_policy object has the following properties:

    immediate_trash (boolean)

    Option to delete documents in trash immediately

    idle_doc_timeout_preparation (integer)

    Number of days before moving documents in preparation to trash

    idle_doc_timeout_closed (integer)

    Number of days before moving closed documents to trash

    idle_doc_timeout_canceled (integer)

    Number of days before moving cancelled documents to trash

    idle_doc_timeout_timedout (integer)

    Number of days before moving timed out documents to trash

    idle_doc_timeout_rejected (integer)

    Number of days before moving rejected documents to trash

    idle_doc_timeout_error (integer)

    Number of days before moving documents with errors to trash

    data_retention_policy (object)

    An object with data retention policy properties.

    The data_retention_policy object has the following properties:

    immediate_trash (boolean)

    Option to delete documents in trash immediately

    idle_doc_timeout_preparation (integer)

    Number of days before moving documents in preparation to trash

    idle_doc_timeout_closed (integer)

    Number of days before moving closed documents to trash

    idle_doc_timeout_canceled (integer)

    Number of days before moving cancelled documents to trash

    idle_doc_timeout_timedout (integer)

    Number of days before moving timed out documents to trash

    idle_doc_timeout_rejected (integer)

    Number of days before moving rejected documents to trash

    idle_doc_timeout_error (integer)

    Number of days before moving documents with errors to trash

    OAuthAuthorization

    (object)

    This object has the following properties:

    apitoken (string)

    apisecret (string)

    accesstoken (string)

    accesssecret (string)

    UserStats

    (object)

    Example JSON: for "UserStats"

    {
  "stats": [
    {
      "date": "2019-01-03",
      "name": "Organisation total",
      "sent": 1,
      "closed": 1,
      "signatures": 1,
      "user_stats": [
        {
          "date": "2019-01-03",
          "email": "demo@scrive.com",
          "name": " ",
          "sent": 1,
          "closed": 1,
          "signatures": 1
        }
      ]
    }
  ]
}

    A JSON object with the statistics on usage: count of documents on different stages of the process

    This object has the following properties:

    stats (array)

    All array elements must be of type:

    (object)

    This object has the following properties:

    date (string)
    sent (integer)
    closed (integer)
    signatures (integer)
    user_stats (array)

    Only present when the withCompany flag is set

    All array elements must be of type:

    (object)

    This object has the following properties:

    date (string)
    email (string)
    name (string)
    sent (integer)
    closed (integer)
    signatures (integer)

    LoginToken

    (object)

    Example JSON: for "LoginToken"

    {
  "login_token": "a537e5e43d5b4095",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAzQAAAM0AQMAAABXvPU0AAAABlBMVEUAAAD///+l2Z/dAAAAAnRSTlP//8i138cAAAAJcEhZcwAACxIAAAsSAdLdfvwAAAL8SURBVHic7dpLbuswDAVQ70D736V34AJFLFKfpJ28B9A9HBiRLd6jIWHnuP5PHRwOh8PhcDgcDofD4XA4HA6Hw+FwOBwOh8PhcP6Cc8zV+oOWL9d15l3fy88BHA6Hw+Fw6jrp/ib9Tno5rQe3DwEcDofD4XDqO9G6ZyP4HkZ+F8DhcDgcDucxTl4ePfgc30608cLhcDgcDufZTsTt9x0bkcPhcDgczsOcXVx+J3F/wnjVmTN3ARwOh8PhcIo7Uw39v7qsARwOh8PhcEo7+4oRZK03mdutHA6Hw+FwKjpTVyzyHxsGNkaQacv6+YPD4XA4HE5JJ1pfdS5xkRnnyQdoPeXISw6Hw+FwOFWdiVjS7/5pyBjiesfxad7hcDgcDodTxckvIebXDD0uDhD7diMIh8PhcDicRzjRPyUty2MM3g4e04DC4XA4HA6npJNDhsxd625LHlWGo3A4HA6Hw6nqTA15GV1TyJl/LQe9OBwOh8PhFHc+zCFn77qD81HOvCWecjgcDofDqe9Mo8UxVo6LA1wLlscSDofD4XA41Z0sRkjL95bpIyqIYTOHw+FwOJz6zkKcY8M9gkzjxpCZH3A4HA6HwyntBJHfSdwhMYJMw0iePoZf7+YQDofD4XA4xZwl6crEMocMbfH0WorD4XA4HE5dZ3kxcTvLr3tzXN62cTgcDofDqevc40bUFJIfDaPKm3QOh8PhcDiPcV7p072rO63HfTrAz3MIh8PhcDicEs6Uvtjn5hSrM+VxOBwOh8Op6uxq15XtH8/I4XA4HA6ntHPMFUPGd8P0ReO+92HzxeFwOBwOp7zThid9mfuvhQh7OW3K43A4HA6HU9eJHctyqpYPMD27luJwOBwOh/Mgp/Xnw7gxvaLIbzGOcR+Hw+FwOJzHOcf49WIIycSVD/Vq43A4HA6H8whnx+6SdnPI7igcDofD4XCKO1Otc0hO31XrR7lPxuFwOBwOp7TzT4vD4XA4HA6Hw+FwOBwOh8PhcDgcDofD4XA4HM5znS/lqLjLlQGH4gAAAABJRU5ErkJggg==",
  "expiration_time": "2019-02-25 10:50:00.507433116 UTC"
}

    Returns a JSON containing login_token, qr_code and expiration_time.

    This object has the following properties:

    login_token (string)

    qr_code (string)

    expiration_time (string)

    Language Code

    (string, enum)

    Currently supported language codes

    The value of this property must be one of the following enum values:

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

    User

    (object)

    Example JSON: for "User"

    {
  "id": "1",
  "fstname": "Arthur",
  "sndname": "Dent",
  "email": "arthur.dent@scrive.com",
  "twofactor_active": false,
  "twofactor_is_mandatory": false,
  "webauthn_active": false,
  "personalnumber": "197910124242",
  "phone": "+444242424242",
  "companyadmin": true,
  "companyposition": "Hitchhiker",
  "lang": "en"
}

    JSON representation of a User.

    This object has the following properties:

    id (string)

    fstname (string)

    sndname (string)

    email (string)

    sysauth (string)

    home_folder_id (string)

    twofactor_active (boolean)

    twofactor_is_mandatory (boolean)

    webauthn_active (boolean)

    personalnumber (string)

    phone (string)

    companyadmin (boolean)

    companyposition (string)

    lang (string)

    UserGroup

    (object)

    Example JSON: for "UserGroup"

    {
  "id": "1",
  "parent_id": null,
  "name": "A Root Usergroup",
  "children": [
    {
      "id": "2",
      "name": "Some child user group"
    },
    {
      "id": "3",
      "name": "Yet another child user group"
    }
  ],
  "settings": {
    "inherited_from": null,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": 42,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    }
  },
  "contact_details": {
    "inherited_from": null,
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    }
  },
  "tags": [
    {
      "name": "alignment",
      "value": "chaotic good"
    }
  ]
}

    JSON representation of a User Group.

    This object has the following properties:

    id (string)

    parent_id (string)

    name (string)

    children (array)

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    id (string)
    name (string)

    settings (object)

    JSON representation of a User Group's Settings.

    The settings object has the following properties:

    inherited_from (string)

    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    contact_details (object)

    JSON representation of a User Group's Contact Details.

    The contact_details object has the following properties:

    inherited_from (string)

    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    tags (array)

    User defined set of name/value pairs.

    Each tag must have {"name": "some-name", "value": "some-value"} format. In the responses value is always a string. In the requests you can also provide null value to delete a tag. Other value types lead to 400 Bad Request response.

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    name (string)
    value (string)

    UserGroupWithInheritable

    (object)

    Example JSON: for "UserGroupWithInheritable"

    {
  "id": "5",
  "parent_id": "1",
  "name": "A Child Usergroup",
  "children": [
    {
      "id": "2",
      "name": "Some child user group"
    },
    {
      "id": "3",
      "name": "Yet another child user group"
    }
  ],
  "settings": {
    "inherited_from": null,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": 42,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": null,
      "idle_doc_timeout_error": null,
      "immediate_trash": false
    },
    "inheritable_preview": {
      "inherited_from": "1",
      "data_retention_policy": {
        "idle_doc_timeout_preparation": null,
        "idle_doc_timeout_closed": null,
        "idle_doc_timeout_canceled": null,
        "idle_doc_timeout_timedout": null,
        "idle_doc_timeout_rejected": 23,
        "idle_doc_timeout_error": null,
        "immediate_trash": true
      }
    }
  },
  "contact_details": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    },
    "inheritable_preview": {
      "inherited_from": "1",
      "address": {
        "company_number": "5568166804",
        "company_name": "Scrive",
        "address": "Grev Turegatan 11A",
        "zip": "114 46",
        "city": "Stockholm",
        "country": "Sweden"
      }
    }
  },
  "tags": [
    {
      "name": "home-planet",
      "value": "Earth"
    }
  ]
}

    JSON representation of a User Group (with Inheritable Previews).

    This object has the following properties:

    id (string)

    parent_id (string)

    name (string)

    children (array)

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    id (string)
    name (string)

    settings (object)

    JSON representation of a User Group's Settings (with Inheritable Preview).

    The settings object has the following properties:

    inherited_from (string)

    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    inheritable_preview (object)

    The inheritable_preview object has the following properties:

    inherited_from (string)
    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    contact_details (object)

    JSON representation of a User Group's Contact Details (with Inheritable Preview).

    The contact_details object has the following properties:

    inherited_from (string)

    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    inheritable_preview (object)

    The inheritable_preview object has the following properties:

    inherited_from (string)
    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    tags (array)

    User defined set of name/value pairs.

    Each tag must have {"name": "some-name", "value": "some-value"} format. In the responses value is always a string. In the requests you can also provide null value to delete a tag. Other value types lead to 400 Bad Request response.

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    name (string)
    value (string)

    UserGroupSettings

    (object)

    Example JSON: for "UserGroupSettings"

    {
  "inherited_from": null,
  "data_retention_policy": {
    "idle_doc_timeout_preparation": null,
    "idle_doc_timeout_closed": null,
    "idle_doc_timeout_canceled": 42,
    "idle_doc_timeout_timedout": null,
    "idle_doc_timeout_rejected": null,
    "idle_doc_timeout_error": null,
    "immediate_trash": false
  }
}

    JSON representation of a User Group's Settings.

    This object has the following properties:

    inherited_from (string)

    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    UserGroupSettingsWithInheritable

    (object)

    Example JSON: for "UserGroupSettingsWithInheritable"

    {
  "inherited_from": null,
  "data_retention_policy": {
    "idle_doc_timeout_preparation": null,
    "idle_doc_timeout_closed": null,
    "idle_doc_timeout_canceled": 42,
    "idle_doc_timeout_timedout": null,
    "idle_doc_timeout_rejected": null,
    "idle_doc_timeout_error": null,
    "immediate_trash": false
  },
  "inheritable_preview": {
    "inherited_from": 1,
    "data_retention_policy": {
      "idle_doc_timeout_preparation": null,
      "idle_doc_timeout_closed": null,
      "idle_doc_timeout_canceled": null,
      "idle_doc_timeout_timedout": null,
      "idle_doc_timeout_rejected": 23,
      "idle_doc_timeout_error": null,
      "immediate_trash": true
    }
  }
}

    JSON representation of a User Group's Settings (with Inheritable Preview).

    This object has the following properties:

    inherited_from (string)

    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    inheritable_preview (object)

    The inheritable_preview object has the following properties:

    inherited_from (string)

    data_retention_policy (object)

    The data_retention_policy object has the following properties:

    idle_doc_timeout_preparation (integer)

    Number of days to retain the document after preparation

    idle_doc_timeout_closed (integer)

    Number of days to retain the document after closed

    idle_doc_timeout_canceled (integer)

    Number of days to retain the document after canceled

    idle_doc_timeout_timedout (integer)

    Number of days to retain the document after timedout

    idle_doc_timeout_rejected (integer)

    Number of days to retain the document after rejected

    idle_doc_timeout_error (integer)

    Number of days to retain the document after error

    immediate_trash (boolean)

    UserGroupContactDetails

    (object)

    Example JSON: for "UserGroupContactDetails"

    {
  "inherited_from": null,
  "address": {
    "company_number": "5568166804",
    "company_name": "Scrive",
    "address": "Grev Turegatan 11A",
    "zip": "114 46",
    "city": "Stockholm",
    "country": "Sweden"
  }
}

    JSON representation of a User Group's Contact Details.

    This object has the following properties:

    inherited_from (string)

    address (object)

    The address object has the following properties:

    company_number (string)

    company_name (string)

    address (string)

    zip (string)

    city (string)

    country (string)

    UserGroupContactDetailsWithInheritable

    (object)

    Example JSON: for "UserGroupContactDetailsWithInheritable"

    {
  "inherited_from": "1",
  "address": {
    "company_number": "5568166804",
    "company_name": "Scrive",
    "address": "Grev Turegatan 11A",
    "zip": "114 46",
    "city": "Stockholm",
    "country": "Sweden"
  },
  "inheritable_preview": {
    "inherited_from": "1",
    "address": {
      "company_number": "5568166804",
      "company_name": "Scrive",
      "address": "Grev Turegatan 11A",
      "zip": "114 46",
      "city": "Stockholm",
      "country": "Sweden"
    }
  }
}

    JSON representation of a User Group's Contact Details (with Inheritable Preview).

    This object has the following properties:

    inherited_from (string)

    address (object)

    The address object has the following properties:

    company_number (string)

    company_name (string)

    address (string)

    zip (string)

    city (string)

    country (string)

    inheritable_preview (object)

    The inheritable_preview object has the following properties:

    inherited_from (string)

    address (object)

    The address object has the following properties:

    company_number (string)
    company_name (string)
    address (string)
    zip (string)
    city (string)
    country (string)

    User Group ID and Name

    (object)

    Example JSON: for "User Group ID and Name"

    {
  "id": "4",
  "name": "Dunder Mifflin Paper Company, Inc."
}

    Contains the ID and name of a user group

    This object has the following properties:

    id (string)

    Unique identifier for a user group.

    Will not change over time, and cannot be changed.

    name (string)

    The name of the user group.

    User Group ID and Name Sorting

    (array)

    Example JSON: for "User Group ID and Name Sorting"

    [
  {
    "sort_by": "name",
    "order": "descending"
  }
]

    Parameter used to sort results of the list API call.

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    order (string, enum)

    The value of this property must be one of the following enum values:

    • "ascending"
    • "descending"

    sort_by (string, enum, required)

    The value of this property must be one of the following enum values:

    • "id"
    • "name"

    User Group ID and Name Filter

    (array)

    Example JSON: for "User Group ID and Name Filter"

    [
  {
    "filter_by": "name",
    "value": "keyword"
  }
]

    Parameter used to filter user groups for the list API call.

    Default:
    []

    Each element of this array must match at least one of the following schemas:

    Filter by name (object)

    This object has the following properties:

    filter_by (string, enum)

    The value of this property must be one of the following enum values:

    • "name"

    value (string)

    Tags

    (array)

    Example JSON: for "Tags"

    [
  {
    "name": "founded",
    "value": "1846"
  },
  {
    "name": "status",
    "value": "busy"
  }
]

    User defined set of name/value pairs.

    Each tag must have {"name": "some-name", "value": "some-value"} format. In the responses value is always a string. In the requests you can also provide null value to delete a tag. Other value types lead to 400 Bad Request response.

    Default:
    []

    All array elements must be of type:

    (object)

    This object has the following properties:

    name (string)

    value (string)

    AccessRole

    (object)

    Example JSON: for "AccessRole"

    {
  "id": "8",
  "is_generated": false,
  "role_type": "user_group_admin",
  "source": {
    "type": "user",
    "id": "2"
  },
  "target": {
    "type": "user_group",
    "id": "11"
  }
}

    JSON representation of an Access Role.

    This object has the following properties:

    id (string)

    is_generated (boolean)

    role_type (string, enum)

    The value of this property must be one of the following enum values:

    • "user"
    • "user_group_member"
    • "user_admin"
    • "user_group_admin"
    • "document_admin"

    source (object)

    The source object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "user"
    • "user_group"

    id (string)

    target (object)

    The target object has the following properties:

    type (string, enum)

    The value of this property must be one of the following enum values:

    • "user"
    • "user_group"
    • "folder"

    id (string)

    Folder

    (object)

    Example JSON: for "Folder"

    {
  "id": "1",
  "name": "Root folder",
  "home_for_user": null,
  "home_for_user_group": "10",
  "parent_id": null,
  "children": [
    {
      "id": "2",
      "name": "Subfolder of 1",
      "home_for_user": "33",
      "home_for_user_group": null,
      "children": [
        {
          "id": "3",
          "name": "Subfolder of 2",
          "home_for_user": "44",
          "home_for_user_group": null
        }
      ]
    }
  ]
}

    JSON representation of a Folder.

    This object has the following properties:

    id (string, required)

    name (string, required)

    home_for_user (string)

    If the folder is a home folder for a user this field contains the ID of that user. Otherwise it's null.

    home_for_user_group (string)

    If the folder is a home folder for a user group this field contains the ID of that group. Otherwise it's null.

    parent_id (string)

    Optional property. If present contains either the ID of the parent folder or null if the requested folder is root.

    children (array)

    Optional property. If present contains either the immediate children or all descendant folders.

    All array elements must be of type:

    (Folder)

    Document validation error

    (object)

    Example JSON: for "Document validation error"

    {
  "can_start": false,
  "errors": [
    {
      "details": {},
      "type": "missing_document_file"
    },
    {
      "details": {
        "field": {
          "type": "personal_number"
        },
        "signatory_id": "199"
      },
      "type": "invalid_authentication_to_view_info"
    },
    {
      "details": {
        "field": {
          "type": "first_name"
        },
        "signatory_id": "200"
      },
      "type": "invalid_authentication_to_view_info"
    },
    {
      "details": {
        "field": {
          "type": "last_name"
        },
        "signatory_id": "200"
      },
      "type": "invalid_authentication_to_view_info"
    },
    {
      "details": {
        "field": {
          "type": "mobile"
        },
        "signatory_id": "199"
      },
      "type": "invalid_invitation_delivery_info"
    },
    {
      "details": {
        "field": {
          "type": "mobile"
        },
        "signatory_id": "199"
      },
      "type": "field_obligatory_for_sender"
    },
    {
      "details": {
        "field": {
          "type": "personal_number"
        },
        "signatory_id": "199"
      },
      "type": "field_obligatory_for_sender"
    },
    {
      "details": {
        "field": {
          "type": "first_name"
        },
        "signatory_id": "200"
      },
      "type": "field_obligatory_for_sender"
    },
    {
      "details": {
        "field": {
          "type": "last_name"
        },
        "signatory_id": "200"
      },
      "type": "field_obligatory_for_sender"
    }
  ]
}

    Defines the structure of single document validation error returned by endpoint related to document starting.

    This object has the following properties:

    type (string, enum)

    The error identifier.

    Description templates of each error type for presentation to user can be found at Validation error templates.

    The value of this property must be one of the following enum values:

    • "approver_cannot_have_field_placement"
    • "approver_cannot_have_non_standard_sign_authentication"
    • "authentication_to_sign_method_disabled"
    • "authentication_to_view_archived_method_disabled"
    • "authentication_to_view_method_disabled"
    • "author_attachments_feature_disabled"
    • "author_cannot_be_approver"
    • "author_cannot_use_forwarding"
    • "bulk_send_empty_recipient_list"
    • "bulk_send_feature_disabled"
    • "bulk_send_multiple_matching_fields"
    • "bulk_send_no_matching_field"
    • "bulk_send_no_matching_signatory_found"
    • "bulk_send_non_text_field"
    • "bulk_send_target_signatory_is_an_author"
    • "bulk_send_too_many_recipients"
    • "cannot_use_document_roles_with_forwarding"
    • "confirmation_delivery_method_disabled"
    • "custom_sms_text_feature_disabled"
    • "document_is_template"
    • "document_roles_feature_disabled"
    • "field_obligatory"
    • "field_obligatory_for_sender"
    • "forwarding_feature_disabled"
    • "invalid_authentication_to_sign_info"
    • "invalid_authentication_to_view_archived_info"
    • "invalid_authentication_to_view_info"
    • "invalid_confirmation_delivery_info"
    • "invalid_date_config"
    • "invalid_invitation_delivery_info"
    • "invalid_notification_delivery_info"
    • "invalid_value"
    • "invitation_delivery_method_disabled"
    • "missing_document_file"
    • "no_signing_party"
    • "notification_delivery_method_disabled"
    • "qes_incompatible_signing_method"
    • "qes_missing_attachment"
    • "qes_signatory_field_cannot_be_editable_by_signatory"
    • "qes_signatory_field_cannot_be_editable_in_signview"
    • "qes_signatory_non_author_field"
    • "signatory_attachment_feature_disabled"

    details (object)

    Details identifying source of error.

    Usually only properties related to specific error are present. Some errors like missing_document_file which relates to overall document state (as opposed to specific signatory and field) have no properties.

    Errors related to specific party always contain signatory_id property.

    The details object has the following properties:

    field (object)

    Identifies a field of party.

    The field object has the following properties:

    type (string, enum)

    Field type

    The value of this property must be one of the following enum values:

    • "first_name"
    • "last_name"
    • "company"
    • "company_number"
    • "email"
    • "mobile"
    • "personal_number"
    • "text"
    • "checkbox"
    • "radio_group"
    • "signature"
    • "date"
    name (string)

    Field name - only for named fields (text, checkbox, radio_group, signature, date)

    signatory_id (string)

    Unique identifier for a party.

    delivery_method (string)

    Identifier of delivery method (invalid_*_delivery_info, *_delivery_method_disabled).

    authentication_method (string)

    Identifier of authentication method (invalid_authentication_*, authentication_*_method_disabled).

    attachment_name (string)

    Identifier of attachment (qes_missing_attachment).

    recipient_index (integer)

    Index into recipient_list of bulk send parameter.

    Only present for bulk send calls, indicates which recipient caused the document error.

    Authentication field setting

    (object)

    Legacy alternative is to send simply the value (not as JSON string). In that case force_obligatory parameter always defaults to null.

    This object has the following properties:

    value (text)

    Value for the field.

    force_obligatory (bool)

    Whether the field must be obligatory. When selected authentication already required field to be obligatory, the false value has no effect as the field will be always obligatory.

    Ommiting this field or setting it to null tries to preserve current obligatoriness of the field.

    Other document settings may also override this option. (E.g. when you change authentication to sign with phone number field set to force_obligatory=false and the phone number is required by invitation delivery method, the phone number field will be mandatory anyway).

    Default: null

    Bulk send recipient info

    (array)

    Example JSON: for "Bulk send recipient info"

    [
  {
    "document_title": "Rent contract prolongation - Arthur Dent",
    "first_name": "Arthur",
    "last_name": "Dent",
    "email": "arthur.dent@example.org",
    "custom_fields": {
      "occupation": "Hitchhiker"
    }
  },
  {
    "document_title": "Rent contract prolongation - Ford Prefect",
    "first_name": "Ford",
    "last_name": "Prefect",
    "email": "ford.prefect@example.org",
    "custom_fields": {
      "occupation": "Researcher for the Hitchhiker's Guide to the Galaxy"
    }
  },
  {
    "document_title": "Rent contract prolongation - Zaphod Beeblebrox",
    "first_name": "Zaphod",
    "last_name": "Beeblebrox",
    "email": "zaphod.beeblebrox@example.org",
    "custom_fields": {
      "occupation": "Galactic President"
    }
  }
]

    JSON array describing recipients for the bulk send.

    All array elements must be of type:

    (object)

    Bulk send recipient details. All fields are optional, but depending on the document setup, not providing necessary fields can prevent the document from being started.

    If a field is provided, it will overwrite the value of a related signatory link field.

    All the fields referenced in this object have to exist, otherwise the bulk send will refuse to start the document. However you don't have to reference all the signatory fields that are present.

    Currently, only text fields are supported by the bulk send.

    This object has the following properties:

    document_title (string)

    Modifies the title of the document started by the bulk send.

    first_name (string)

    Modifies the first name field of the signatory.

    last_name (string)

    Modifies the last name field of the signatory.

    email (string)

    Modifies the email field of the signatory.

    mobile (string)

    Modifies the mobile field of the signatory.

    personal_number (string)

    Modifies the personal number field of the signatory.

    company (string)

    Modifies the company name field of the signatory.

    company_number (string)

    Modifies the company number field of the signatory.

    custom_fields (object)

    Mapping of custom field names and their values.

    The property name can refer to any text or multi-line custom text field.