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.

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.

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

Code	Description
201	The document metadata as a JSON.
400	The parameter `file` could not be parsed.

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

Code	Description
201	The document metadata as a JSON.
409	The document is not a template.

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

Code	Description
201	The document metadata as a JSON.

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

Code	Description
200	The document metadata as a JSON.
409	The document status should be `Preparation`.

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

Code	Description
200	The document metadata as a JSON.
400	The parameter `file` could not be parsed.
409	The document status should be `Preparation`.

Parameter	Description	Type	In
`document_id` required	Unique identifier for a document. Will not change.	integer int64	path
`attachments` required	List of author attachments. The list provided will replace any existing attachments (if any). Therefore, to add an attachment to an existing list, you would need to first fetch the existing attachments `file_id` and use it for this call. Note: The JSON structure has two variants, one with `file_param` and the other with `file_id`. `file_param` refers to a named parameter that must also be included in this API call. This is the suggested way to include files. `file_id` refers to a file in the Scrive system. You must have the rights to access the `file_id` to use it. Must be of type Author Attachments.	string application/json	formData
`{attachment_name}` optional	The named file parameters Any `file_param` in the `attachments` JSON must be supplied as named file parameters. If converting from API version 1, it is convenient to name these parameters `attachment_1`, `attachment_2`, etc, and reference them as such in the `attachments` JSON. Although it is possible to use any HTTP compatible naming scheme.	file application/pdf	formData
`incremental` optional default: `false`	If set to `true`, this will make the API set the given author attachments leaving all already set attachments intact. For each given attachment, if there already is one with the same name, it will get overwritten, otherwise, the attachment will be added.	boolean	formData
`object_version` optional	If provided, will check the document `object_version` and only perform the operation if these match. Otherwise you will get a `HTTP 409`.	integer	formData

Code	Description
200	The document metadata as a JSON.
409	The document status should be `Preparation`.

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

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.

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

Code	Description
200	The document metadata as a JSON.
409	`document_state_error` with error messages: The document state must be 'Preparation'. Document is a template, templates can not be started. Document must have a file before it can be started. The document has missing or invalid data. Some information about what is missing or invalid in the document is given.

Parameter	Description	Type	In
`document_id` required	Unique identifier for a document. Will not change.	integer int64	path

Code	Description
200	The document metadata as a JSON.

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

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

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

Code	Description
200	PNG image, `content-type: image/png`.
409	`document_state_error` with message The document state must be 'Pending'.

Parameter	Description	Type	In
`offset` optional default: `0`	Starting offset for documents to return. If offset is larger than the total number of matching documents, an empty list is returned.	integer int32	query
`max` optional default: `100`	Maximum number of documents to return. Server may cap to a lower value. Default value may change without notice.	integer int32	query
`filter` optional default: `[]`	List of filtering options. You can supply a list of filtering options to apply. Only documents that match all filters will be returned. Therefore, it is easy to apply a set of filters that will return no documents. If not supplied, the default is not to apply any filter, i.e. `[]`. Must be of type List Filter, for example: `[ { "filter_by":"status", "statuses": ["preparation","pending"] } ]`	string application/json	query
`sorting` optional default: `[ { "sort_by":"mtime", "order":"descending" } ]`	List of sorting options. You can supply a list of sorting options, which will be applied to list of documents in the order you provided. If not supplied, the default is `[ { "sort_by":"mtime", "order":"descending" } ]`, i.e., sort by modification time, newest first. Must be of type List Sorting.	string application/json	query

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.

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

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.

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

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.

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: `da`, `de`, `el`, `en`, `es`, `et`, `fi`, `fr`, `is`, `it`, `lt`, `lv`, `nl`, `no`, `pt`, `sv`	string	query

Code	Description
200	The list of history items for this document. Will be in reverse-chronological order and an array of History Items.

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

Code	Description
202	A callback will be triggered for the document if a User or Document callback URL was set.
409	Can not send callbacks for documents in Preparation.

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

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

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

Code	Description
200	The document metadata as a JSON.
400	The `days` parameter must be a number between 1 and 90.
409	The document has not timed out. Only timed out documents can be prolonged.

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

Code	Description
200	The document metadata as a JSON.
409	The document state is not `Pending`.

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

Code	Description
200	The document metadata as a JSON.
409	Pending documents can not be trashed or deleted.

Parameter	Description	Type	In
`document_ids` required	List of document IDs to trash.	string application/json	formData

Code	Description
200	A JSON object containing the total number of `trashed` documents, and an array of documents.
409	Pending documents can not be trashed or deleted.

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

Code	Description
200	The document metadata as a JSON.
409	Pending documents can not be trashed or deleted.

Parameter	Description	Type	In
`document_ids` required	List of document IDs to delete.	string application/json	formData

Code	Description
200	A JSON object containing the total number of `deleted` documents, and an array of documents.
409	Pending documents can not be trashed or deleted.

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

Code	Description
202	The call succeeded, an email to the given address has been queued.
409	The document status should be `Closed`.

] } ``` 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](#document-3) documentation for details)._ ### 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" ```json { "id": "8222115557375075439", "title": "Contract for Magnus", "parties": [ { "id": "189255", "user_id": "1404", "is_author": true, "is_signatory": false, "signatory_role": "viewer", "fields": [ { "type": "name", "order": 1, "value": "Gregory", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [] }, { "type": "name", "order": 2, "value": "Davids", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [] }, { "type": "email", "value": "noreply@scrive.com", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company", "value": "Scrive", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] } ], "sign_order": 1, "sign_time": null, "seen_time": null, "read_invitation_time": null, "rejected_time": null, "rejection_reason": null, "sign_success_redirect_url": null, "reject_redirect_url": null, "email_delivery_status": "unknown", "mobile_delivery_status": "unknown", "has_authenticated_to_view": false, "csv": null, "delivery_method": "pad", "authentication_method_to_view": "standard", "authentication_method_to_view_archived": "standard", "authentication_method_to_sign": "standard", "confirmation_delivery_method": "none", "allows_highlighting": false, "attachments": [], "highlighted_pages": [], "api_delivery_url": null }, { "id": "189256", "user_id": null, "is_author": false, "is_signatory": true, "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": "email", "value": "noemail@scrive.com", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "mobile", "value": "", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company", "value": "Scrive", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company_number", "value": "", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "signature", "name": "Signature 1", "signature": "195174", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.07894736842105263, "yrel": 0.09962825278810408, "wrel": 0.2736842105263158, "hrel": 0.0758364312267658, "fsrel": 0.0168, "page": 1, "tip": "right", "anchors": [] } ] } ], "sign_order": 1, "sign_time": "2017-01-13T10:38:49.590815Z", "seen_time": "2017-01-13T10:38:33.1783Z", "read_invitation_time": null, "rejected_time": null, "rejection_reason": null, "sign_success_redirect_url": null, "reject_redirect_url": null, "email_delivery_status": "unknown", "mobile_delivery_status": "unknown", "has_authenticated_to_view": false, "csv": null, "delivery_method": "pad", "authentication_method_to_view": "standard", "authentication_method_to_view_archived": "standard", "authentication_method_to_sign": "standard", "confirmation_delivery_method": "none", "allows_highlighting": true, "attachments": [], "highlighted_pages": [ { "page": 1, "file_id": "195173" } ], "api_delivery_url": null } ], "file": { "name": "contract.pdf", "id": "195124" }, "sealed_file": { "name": "contract.pdf", "id": "195172" }, "author_attachments": [], "ctime": "2017-01-13T10:38:17.916324Z", "mtime": "2017-01-13T10:38:49.590815Z", "timeout_time": "2017-04-13T22:59:59Z", "auto_remind_time": null, "status": "closed", "days_to_sign": 90, "days_to_remind": null, "display_options": { "show_header": true, "show_pdf_download": true, "show_reject_option": true, "allow_reject_reason": true, "show_footer": true, "document_is_receipt": false, "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" } } ```

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.

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

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

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

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

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:

`value` `(string)`

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

Default: ""

`is_obligatory` `(boolean)`

Default: true

`should_be_filled_by_sender` `(boolean)`

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldEmailMobile `(object)`

A signatory field for email addresses and mobile numbers.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldStandard `(object)`

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

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

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldCheckbox `(object)`

A signatory field for placing checkboxes on the document.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify that this is a checkbox field.

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:

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

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

`index` `(integer)`

SignatoryFieldRadiogroup `(object)`

A signatory field for placing radio buttons on the document.

This object has the following properties:

`type` `(string, enum, required)`

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

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:

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

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

`index` `(integer)`

SignatoryFieldCustomText `(object)`

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

This object has the following properties:

`type` `(string, enum, required)`

Used to specify that this is a custom text field.

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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

`sign_order` `(integer)`

Default: 1

`sign_time` `(string,null, read only)`

`seen_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"

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

`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"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"verimi"
"nl_idin"

`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"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"verimi"
"nl_idin"

`authentication_method_to_sign` `(string, enum)`

Default: "standard"

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

"standard"
"sms_pin"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"onfido_document_check"
"onfido_document_and_photo_check"

`confirmation_delivery_method` `(string, enum)`

Options allow delivery of the signed document as

email an attachment in email or
mobile a link in a text message or
email_mobile both of the two above or
email_link a link in an email or
email_link_mobile a link in both an email and a text message or
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"

`allows_highlighting` `(boolean)`

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

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

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

Default: false

`hide_personal_number` `(boolean)`

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

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

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

Default: false

`highlighted_pages` `(array, read only)`

A list of highlights performed by the signatory.

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`page` `(integer)`

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

`file_id` `(string)`

The file_id for an image of the highlights.

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

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

`attachments` `(array)`

Default:
[]

All array elements must be of type:

`(object)`

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

This object has the following properties:

`name` `(string)`

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

`description` `(string)`

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

`required` `(boolean)`

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

Default: true

`file_id` `(string)`

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

`file_name` `(string)`

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

`api_delivery_url` `(string,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.

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

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

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

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

"da"
"de"
"el"
"en"
"es"
"et"
"fi"
"fr"
"is"
"it"
"lt"
"lv"
"nl"
"no"
"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)`

## UserGroup The user group metadata as a JSON. ### UserGroup `(object)` > ### Example JSON: for "UserGroup" ```json { "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 The user group metadata as a JSON (with Inheritable Previews). ### UserGroupWithInheritable `(object)` > ### Example JSON: for "UserGroupWithInheritable" ```json { "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.

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`name` `(string)`

`value` `(string)`

## APIError The JSON structured errors returned by the API. ### API Error `(object)` > ### Example JSON: for "API Error" ```json { "error_type": "request_parameters_parse_error", "error_message": "The parameter 'document' could not be parsed. Please refer to our API documentation. Error details: Invalid JSON", "http_code": 400 } ```

The structure of errors returned by the Scrive Document API.

This object has the following properties:

`error_type` `(string, enum)`

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

"server_error"
"request_failed"
"endpoint_not_found"
"invalid_authorisation"
"insufficient_privileges"
"resource_not_found"
"document_action_forbidden"
"request_parameters_missing"
"request_parameters_parse_error"
"request_parameters_invalid"
"document_object_version_mismatch"
"document_state_error"
"signatory_state_error"
"action_not_permitted"
"conflict_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
500
603

# Definitions ## Document `(object)` > ### Example JSON: for "Document" ```json { "id": "8222115557375075439", "title": "Contract for Magnus", "parties": [ { "id": "189255", "user_id": "1404", "is_author": true, "is_signatory": false, "signatory_role": "viewer", "fields": [ { "type": "name", "order": 1, "value": "Gregory", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [] }, { "type": "name", "order": 2, "value": "Davids", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [] }, { "type": "email", "value": "noreply@scrive.com", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company", "value": "Scrive", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] } ], "sign_order": 1, "sign_time": null, "seen_time": null, "read_invitation_time": null, "rejected_time": null, "rejection_reason": null, "sign_success_redirect_url": null, "reject_redirect_url": null, "email_delivery_status": "unknown", "mobile_delivery_status": "unknown", "has_authenticated_to_view": false, "csv": null, "delivery_method": "pad", "authentication_method_to_view": "standard", "authentication_method_to_view_archived": "standard", "authentication_method_to_sign": "standard", "confirmation_delivery_method": "none", "allows_highlighting": false, "attachments": [], "highlighted_pages": [], "api_delivery_url": null }, { "id": "189256", "user_id": null, "is_author": false, "is_signatory": true, "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": "email", "value": "noemail@scrive.com", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "mobile", "value": "", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company", "value": "Scrive", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company_number", "value": "", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "signature", "name": "Signature 1", "signature": "195174", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.07894736842105263, "yrel": 0.09962825278810408, "wrel": 0.2736842105263158, "hrel": 0.0758364312267658, "fsrel": 0.0168, "page": 1, "tip": "right", "anchors": [] } ] } ], "sign_order": 1, "sign_time": "2017-01-13T10:38:49.590815Z", "seen_time": "2017-01-13T10:38:33.1783Z", "read_invitation_time": null, "rejected_time": null, "rejection_reason": null, "sign_success_redirect_url": null, "reject_redirect_url": null, "email_delivery_status": "unknown", "mobile_delivery_status": "unknown", "has_authenticated_to_view": false, "csv": null, "delivery_method": "pad", "authentication_method_to_view": "standard", "authentication_method_to_view_archived": "standard", "authentication_method_to_sign": "standard", "confirmation_delivery_method": "none", "allows_highlighting": true, "attachments": [], "highlighted_pages": [ { "page": 1, "file_id": "195173" } ], "api_delivery_url": null } ], "file": { "name": "contract.pdf", "id": "195124" }, "sealed_file": { "name": "contract.pdf", "id": "195172" }, "author_attachments": [], "ctime": "2017-01-13T10:38:17.916324Z", "mtime": "2017-01-13T10:38:49.590815Z", "timeout_time": "2017-04-13T22:59:59Z", "auto_remind_time": null, "status": "closed", "days_to_sign": 90, "days_to_remind": null, "display_options": { "show_header": true, "show_pdf_download": true, "show_reject_option": true, "allow_reject_reason": true, "show_footer": true, "document_is_receipt": false, "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" } } ```

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

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

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

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

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

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

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:

`value` `(string)`

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

Default: ""

`is_obligatory` `(boolean)`

Default: true

`should_be_filled_by_sender` `(boolean)`

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldEmailMobile `(object)`

A signatory field for email addresses and mobile numbers.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldStandard `(object)`

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

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

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldCheckbox `(object)`

A signatory field for placing checkboxes on the document.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify that this is a checkbox field.

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:

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

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

`index` `(integer)`

SignatoryFieldRadiogroup `(object)`

A signatory field for placing radio buttons on the document.

This object has the following properties:

`type` `(string, enum, required)`

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

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:

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

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

`index` `(integer)`

SignatoryFieldCustomText `(object)`

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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

`sign_order` `(integer)`

Default: 1

`sign_time` `(string,null, read only)`

`seen_time` `(string,null, read only)`

`read_invitation_time` `(string,null, read only)`

`rejected_time` `(string,null, read only)`

`rejection_reason` `(string,null, read only)`

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

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

`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"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"verimi"
"nl_idin"

`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"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"verimi"
"nl_idin"

`authentication_method_to_sign` `(string, enum)`

Default: "standard"

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

"standard"
"sms_pin"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"onfido_document_check"
"onfido_document_and_photo_check"

`confirmation_delivery_method` `(string, enum)`

Options allow delivery of the signed document as

email an attachment in email or
mobile a link in a text message or
email_mobile both of the two above or
email_link a link in an email or
email_link_mobile a link in both an email and a text message or
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"

`allows_highlighting` `(boolean)`

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

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

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

Default: false

`hide_personal_number` `(boolean)`

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

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

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

Default: false

`highlighted_pages` `(array, read only)`

A list of highlights performed by the signatory.

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`page` `(integer)`

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

`file_id` `(string)`

The file_id for an image of the highlights.

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

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

`attachments` `(array)`

Default:
[]

All array elements must be of type:

`(object)`

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

This object has the following properties:

`name` `(string)`

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

`description` `(string)`

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

`required` `(boolean)`

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

Default: true

`file_id` `(string)`

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

`file_name` `(string)`

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

`api_delivery_url` `(string,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.

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

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.

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

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

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

"da"
"de"
"el"
"en"
"es"
"et"
"fi"
"fr"
"is"
"it"
"lt"
"lv"
"nl"
"no"
"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)`

## Document Status `(string, enum)`

The current document status.

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

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

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

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

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

## Signatory `(object)` > ### Example JSON: for "Signatory" ```json { "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": "email", "value": "noemail@scrive.com", "is_obligatory": false, "should_be_filled_by_sender": false, "editable_by_signatory": false, "placements": [] }, { "type": "mobile", "value": "", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company", "value": "Scrive", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "company_number", "value": "", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [] }, { "type": "signature", "name": "Signature 1", "signature": "195174", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.07894736842105263, "yrel": 0.09962825278810408, "wrel": 0.2736842105263158, "hrel": 0.0758364312267658, "fsrel": 0.0168, "page": 1, "tip": "right", "anchors": [] } ] } ], "sign_order": 1, "sign_time": "2017-01-13T10:38:49.590815Z", "seen_time": "2017-01-13T10:38:33.1783Z", "read_invitation_time": null, "rejected_time": null, "rejection_reason": null, "sign_success_redirect_url": null, "reject_redirect_url": null, "email_delivery_status": "unknown", "mobile_delivery_status": "unknown", "has_authenticated_to_view": false, "csv": null, "delivery_method": "pad", "authentication_method_to_view": "standard", "authentication_method_to_view_archived": "standard", "authentication_method_to_sign": "standard", "confirmation_delivery_method": "none", "allows_highlighting": true, "hide_personal_number": false, "attachments": [], "highlighted_pages": [ { "page": 1, "file_id": "195173" } ], "api_delivery_url": null, "consent_module": { "title": "Handling of personal information", "questions": [ { "title": "Do you agree for your information to be processed?", "positive_option": "Yes, I agree with the processing of my data.", "negative_option": "No, I do not agree with any processing of my data.", "response": null, "detailed_description": { "title": "More information", "text": "Long extra information regarding the question can go here, and can be separated using newlines.\n\nThis is useful for long terms and conditions that come along with a question." } } ] } } ```

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

This object has the following properties:

`id` `(string, read only)`

Unique identifier for a party.

Will not change over time, and cannot be changed.

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

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

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

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

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

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

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:

`value` `(string)`

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

Default: ""

`is_obligatory` `(boolean)`

Default: true

`should_be_filled_by_sender` `(boolean)`

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldEmailMobile `(object)`

A signatory field for email addresses and mobile numbers.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldStandard `(object)`

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

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

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

SignatoryFieldCheckbox `(object)`

A signatory field for placing checkboxes on the document.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify that this is a checkbox field.

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:

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

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

`index` `(integer)`

SignatoryFieldRadiogroup `(object)`

A signatory field for placing radio buttons on the document.

This object has the following properties:

`type` `(string, enum, required)`

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

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:

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

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

`index` `(integer)`

SignatoryFieldCustomText `(object)`

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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

`sign_order` `(integer)`

Default: 1

`sign_time` `(string,null, read only)`

`seen_time` `(string,null, read only)`

`read_invitation_time` `(string,null, read only)`

`rejected_time` `(string,null, read only)`

`rejection_reason` `(string,null, read only)`

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

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

`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"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"verimi"
"nl_idin"

`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"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"verimi"
"nl_idin"

`authentication_method_to_sign` `(string, enum)`

Default: "standard"

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

"standard"
"sms_pin"
"se_bankid"
"no_bankid"
"dk_nemid"
"fi_tupas"
"onfido_document_check"
"onfido_document_and_photo_check"

`confirmation_delivery_method` `(string, enum)`

Options allow delivery of the signed document as

email an attachment in email or
mobile a link in a text message or
email_mobile both of the two above or
email_link a link in an email or
email_link_mobile a link in both an email and a text message or
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"

`allows_highlighting` `(boolean)`

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

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

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

Default: false

`hide_personal_number` `(boolean)`

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

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

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

Default: false

`highlighted_pages` `(array, read only)`

A list of highlights performed by the signatory.

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`page` `(integer)`

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

`file_id` `(string)`

The file_id for an image of the highlights.

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

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

`attachments` `(array)`

Default:
[]

All array elements must be of type:

`(object)`

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

This object has the following properties:

`name` `(string)`

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

`description` `(string)`

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

`required` `(boolean)`

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

Default: true

`file_id` `(string)`

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

`file_name` `(string)`

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

`api_delivery_url` `(string,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.

## SignatoryFieldName `(object)` > ### Example JSON: for "SignatoryFieldName" ```json { "type": "name", "order": 1, "value": "John", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.26105263157894737, "yrel": 0.0975609756097561, "wrel": 0.07894736842105263, "hrel": 0.024390243902439025, "fsrel": 0.01263157894736842, "page": 1, "tip": "right", "anchors": [] } ] } ```

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

This object has the following properties:

`type` `(string, enum, required)`

Used to specify that this is a name field.

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:

`value` `(string)`

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

Default: ""

`is_obligatory` `(boolean)`

Default: true

`should_be_filled_by_sender` `(boolean)`

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

## SignatoryFieldEmailMobile `(object)` > ### Example JSON: for "SignatoryFieldEmailMobile" ```json { "type": "mobile", "value": "+461234567890", "is_obligatory": false, "should_be_filled_by_sender": false, "editable_by_signatory": false, "placements": [ { "xrel": 0.09052631578947369, "yrel": 0.2700892857142857, "wrel": 0.09157894736842105, "hrel": 0.025297619047619048, "fsrel": 0.016842105263157894, "page": 1, "tip": "right", "anchors": [] } ] } ```

A signatory field for email addresses and mobile numbers.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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

Default: false

`placements` `(array)`

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

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

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

Default:
[]

All array elements must be of type:

`(object)`

This object has the following properties:

`xrel` `(number, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

## SignatoryFieldSignature `(object)` > ### Example JSON: for "SignatoryFieldSignature" ```json { "type": "signature", "name": "Signature 1", "signature": "9215148251416996589", "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.3510526315789474, "yrel": 0.1796747967479675, "wrel": 0.2736842105263158, "hrel": 0.08292682926829269, "fsrel": 0.0168, "page": 1, "tip": "right", "anchors": [] } ] } ```

A signatory field for placing signature boxes on the document.

This object has the following properties:

`type` `(string, enum, required)`

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

## SignatoryFieldStandard `(object)` > ### Example JSON: for "SignatoryFieldStandard" ```json { "type": "company", "value": "Scrive AB", "is_obligatory": false, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.09052631578947369, "yrel": 0.2700892857142857, "wrel": 0.09157894736842105, "hrel": 0.025297619047619048, "fsrel": 0.016842105263157894, "page": 1, "tip": "right", "anchors": [] } ] } ```

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

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

This object has the following properties:

`type` `(string, enum, required)`

Used to specify what type of field this is.

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

## SignatoryFieldCheckbox `(object)` > ### Example JSON: for "SignatoryFieldCheckbox" ```json { "type": "checkbox", "name": "Checkbox Name", "is_checked": true, "is_obligatory": true, "should_be_filled_by_sender": false, "placements": [ { "xrel": 0.17526315789473684, "yrel": 0.3382113821138211, "wrel": 0.011538, "hrel": 0, "fsrel": 0, "page": 1, "tip": "left", "anchors": [] } ] } ```

A signatory field for placing checkboxes on the document.

This object has the following properties:

`type` `(string, enum, required)`

Used to specify that this is a checkbox field.

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:

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

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

`index` `(integer)`

## SignatoryFieldRadiogroup `(object)` > ### Example JSON: for "SignatoryFieldRadiogroup" ```json { "type": "radiogroup", "name": "Large Radio buttons", "selected_value": "Radio button 2", "placements": [ { "xrel": 0.7405263157894737, "yrel": 0.3796747967479675, "wrel": 0.025263, "hrel": 0, "fsrel": 0, "page": 1, "tip": "right", "anchors": [] }, { "xrel": 0.7405263157894737, "yrel": 0.4008130081300813, "wrel": 0.021052, "hrel": 0, "fsrel": 0, "page": 1, "tip": "right", "anchors": [] }, { "xrel": 0.7410526315789474, "yrel": 0.4211382113821138, "wrel": 0.014736, "hrel": 0, "fsrel": 0, "page": 1, "tip": "right", "anchors": [] } ], "values": [ "Radio button 1", "Radio button 2", "Radio button 3" ] } ```

A signatory field for placing radio buttons on the document.

This object has the following properties:

`type` `(string, enum, required)`

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

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:

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

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

`index` `(integer)`

## SignatoryFieldCustomText `(object)` > ### Example JSON: for "SignatoryFieldCustomText" ```json { "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'." } } ```

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, required)`

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

`yrel` `(number, required)`

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

`wrel` `(number, required)`

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

`hrel` `(number, required)`

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

`fsrel` `(number, required)`

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

`page` `(integer, required)`

The page number for this placement, starting from 1.

`tip`

Default: null

The 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)`

`index` `(integer)`

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

## List Filter `(array)` > ### Example JSON: for "List Filter" ```json [ { "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".

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"
"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" ```json [ { "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" ```json [ { "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" ```json { "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"

`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" ```json { "id": "2", "title": "Terms and conditions", "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.

`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" ```json [ { "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)`

## DataRetentionPolicy `(object)` > ### Example JSON: for "DataRetentionPolicy" ```json { "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" ```json { "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" ```json { "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" ```json { "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:

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

## User `(object)` > ### Example JSON: for "User" ```json { "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" } ```

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

`personalnumber` `(string)`

`phone` `(string)`

`companyadmin` `(boolean)`

`companyposition` `(string)`

`lang` `(string)`

## UserGroup `(object)` > ### Example JSON: for "UserGroup" ```json { "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.

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" ```json { "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.

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" ```json { "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" ```json { "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" ```json { "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" ```json { "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)`

## Tags `(array)` > ### Example JSON: for "Tags" ```json [ { "name": "founded", "value": "1846" }, { "name": "status", "value": "busy" } ] ```

User defined set of name/value pairs.

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" ```json { "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)`

`allowed_actions` `(object)`

The allowed_actions object has the following properties:

`document` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

`folder_policy` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

`user` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

`user_group` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

`user_group_policy` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

`user_personal_token` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

`user_policy` `(array)`

All array elements must be of type:

`(string, enum)`

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

"create"
"delete"
"read"
"update"

## Folder `(object)` > ### Example JSON: for "Folder" ```json { "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:

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

Code	Description
201	The document metadata as a JSON.
409	Documents that are in Preparation, Pending, or Closed can not be restarted.

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

Parameter	Description	Type	In
`attachment_id` required	Identifier for the attachment.	integer int64	path
`filename` optional	Optional filename parameter.	string	path

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

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

Code	Description
200	A JSON with the `twofactor_active` flag and `totp_valid` flag
400	2-factor code from QR code is invalid

Code	Description
200	The user was deleted succesfully. The body is empty
400	Email parameter isn't provided or doesn't match the user's email

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: `da`, `de`, `el`, `en`, `es`, `et`, `fi`, `fr`, `is`, `it`, `lt`, `lv`, `nl`, `no`, `pt`, `sv`	string	formData

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

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

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

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)

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

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

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)

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

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

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

id (string, read only)

title (string)

parties (array)

Signatory (object)

id (string, read only)

user_id (string,null, read only)

is_author (boolean, read only)

is_signatory (boolean)

signatory_role (string, enum)

fields (array)

SignatoryFieldName (object)

type (string, enum, required)

order (integer, enum, required)

value (string)

is_obligatory (boolean)

should_be_filled_by_sender (boolean)

placements (array)

(object)

xrel (number, required)

yrel (number, required)

wrel (number, required)

hrel (number, required)

fsrel (number, required)

page (integer, required)

tip

(string, enum)

(null)

anchors (array)

(object)

text (string)

index (integer)

SignatoryFieldEmailMobile (object)

type (string, enum, required)

value (string)

is_obligatory (boolean)

should_be_filled_by_sender (boolean)

editable_by_signatory (boolean)

placements (array)

(object)

xrel (number, required)

yrel (number, required)

wrel (number, required)

hrel (number, required)

fsrel (number, required)

page (integer, required)

tip

(string, enum)

(null)

anchors (array)

(object)

text (string)

index (integer)

SignatoryFieldSignature (object)

type (string, enum, required)

name (string, required)

signature (read only)

(null)

(string)

is_obligatory (boolean)

should_be_filled_by_sender (boolean)

placements (array)

(object)

xrel (number, required)

yrel (number, required)

wrel (number, required)

hrel (number, required)

fsrel (number, required)

page (integer, required)

tip

(string, enum)

(null)

anchors (array)

(object)

text (string)

index (integer)

SignatoryFieldStandard (object)

type (string, enum, required)

value (string)

is_obligatory (boolean)

should_be_filled_by_sender (boolean)

`id` `(string, read only)`

`title` `(string)`

`parties` `(array)`

Signatory `(object)`

`id` `(string, read only)`

`user_id` `(string,null, read only)`

`is_author` `(boolean, read only)`

`is_signatory` `(boolean)`

`signatory_role` `(string, enum)`

`fields` `(array)`

SignatoryFieldName `(object)`

`type` `(string, enum, required)`

`order` `(integer, enum, required)`

`value` `(string)`

`is_obligatory` `(boolean)`

`should_be_filled_by_sender` `(boolean)`

`placements` `(array)`

`(object)`

`xrel` `(number, required)`

`yrel` `(number, required)`

`wrel` `(number, required)`

`hrel` `(number, required)`

`fsrel` `(number, required)`

`page` `(integer, required)`

`tip`

`(string, enum)`

`(null)`

`anchors` `(array)`

`(object)`

`text` `(string)`

`index` `(integer)`

SignatoryFieldEmailMobile `(object)`

`type` `(string, enum, required)`

`value` `(string)`

`is_obligatory` `(boolean)`

`should_be_filled_by_sender` `(boolean)`

`editable_by_signatory` `(boolean)`

`placements` `(array)`

`(object)`

`xrel` `(number, required)`

`yrel` `(number, required)`

`wrel` `(number, required)`

`hrel` `(number, required)`

`fsrel` `(number, required)`

`page` `(integer, required)`

`tip`

`(string, enum)`

`(null)`

`anchors` `(array)`

`(object)`

`text` `(string)`

`index` `(integer)`

SignatoryFieldSignature `(object)`

`type` `(string, enum, required)`

`name` `(string, required)`

`signature` `(read only)`

`(null)`

`(string)`

`is_obligatory` `(boolean)`

`should_be_filled_by_sender` `(boolean)`

`placements` `(array)`

`(object)`

`xrel` `(number, required)`

`yrel` `(number, required)`

`wrel` `(number, required)`

`hrel` `(number, required)`

`fsrel` `(number, required)`

`page` `(integer, required)`

`tip`

`(string, enum)`

`(null)`

`anchors` `(array)`

`(object)`

`text` `(string)`

`index` `(integer)`

SignatoryFieldStandard `(object)`

`type` `(string, enum, required)`

`value` `(string)`

`is_obligatory` `(boolean)`

`should_be_filled_by_sender` `(boolean)`