Scrive API



This document defines the preliminary API to access the Scrive service programmatically.

The API affords the following actions:

  • Requesting authorization to create and send documents on behalf of a Scrive user
  • Creating, sending and checking state of documents on behalf of a Scrive user

The above actions should be carried out within reasonable security precautions.


The Scrive API is in use by many clients and can be extended as necessary to meet the demands of customers. However, Scrive is dedicated to following best practices, standards, and sound design principles. Scrive is also dedicated to ensure backward compatibility for existing clients while evolving the API. To this end API access is through a versioned URL to support seamless migration of customers to future improved versions of the API. This document describes version number 1 of the API, and if Scrive finds it necessary to introduce an incompatible new version of the API, the version number will be bumped. For a limited amount of time, both the current version and the new version will be supported. Once all customers have migrated to the new version, the old version of the API will be retired.

The Scrive API is accessed over HTTPS. In general, the Scrive API uses a RESTful approach. REST means that the API consists of resources identified by URLs. The resources are modified not through Remote Procedure Calls but through POSTing (or PUTting) a file with a well-defined format. This documentation defines the format of the files that our API will understand. In general, Scrive uses JSON for API messages as much as possible.

The Scrive API allows one user account to act on behalf of another user account using OAuth version 1.0 (see OAuth is a standard for granting authorizations without the exchange of passwords. A Scrive user can grant or revoke privileges to any number of services.

For scenarios where the full generality of OAuth is overkill, the Scrive API supports a simplified Personal Access mechanism, in which credentials are associated with one particular account, and can be used to access that account without OAuth handshake or explicit passwords on the client side.

Standards used in the Scrive API:

  • SSL
  • OAuth
  • JSON
  • MIME

These standard technologies are typically available for any programming platform.

Common Terms Defined

  • Client – The system accessing Scrive through the API.
  • User – The person associated with a registered Scrive user account.
  • Privilege – A permission granted to a client by a user.
  • Document – PDF files and metadata describing signing process.
  • Client credentials – Credentials that a client uses to authorize and identify itself to the Scrive API.
  • Token credentials – Granted by a user, associated with the user and a set of permissions, and used by a client to perform API calls on behalf of the user.

API demo

As a complement to this documentation Scrive provides an online demo that can be accessed at It can be used to test all API calls as well as whole OAuth workflow. Since it is written entirely in JavaScript, it is easy to inspect details of each call with Firebug or Chrome DevTools. We don’t recommend using the demo with Internet Explorer browsers.

New versions of API

New versions of the API will be introduced when changes would make the existing API not backward compatibile. This means that it is possible for the API to be extended with new calls and existing calls extended with additional parameters without increasing API version. A new API version will also not be introduced if a new optional or readonly field is added to any of JSONs described in this documentation or when new delivery and authentification methods are introduced.


OAuth is the means by which the API Client may act on behalf of an existing User, for instance to create a document. The Scrive API uses OAuth version 1.0.

API Client access is managed through a Scrive user account (called the API client account). Each API client account may have zero or more client credentials (also called consumer keys and secrets). These client credentials may be managed in the Account section of the API client user account. Typically, client credentials are created once as part of developing a client using the Scrive API.

The client credentials may be used by the client to request privileges from zero or more users. Users can approve or deny privileges using OAuth. Users may also remove privileges at a later time. Users manage their API settings in the API tab.

The purpose of the OAuth request sequence is to request a set of privileges from a user and retrieve token credentials associated with the user and the set of privileges.

Once a privilege request has been approved, the client may use the token credentials to make API requests on behalf of the user.

The token credentials represent all granted privileges for a user for a given set of client credentials.

OAuth requests in the Scrive API

Since all requests use SSL (HTTPS), the Scrive API only accepts the PLAINTEXT signature method. To construct the oauth_signature parameter, concatenate the following values:

  • encoded client shared secret
  • “&” character
  • encoded token shared secret


client shared secret = “ab34cde3”
token shared secret = “b23b2cde3”
oauth_signature = “ab34cde3&b23b2cde3”

Sometimes the client or token shared secret are empty, but the & is still required.

OAuth 1.0 Overview

There are three endpoints (URLs) that the client should be aware of.

Temporary Credential Request

Used by the client to obtain temporary credentials.

Request parameters:

oauth_consumer_key – client credentials identifier
oauth_signature_method – always PLAINTEXT
oauth_callback – the callback the User will be redirected to
oauth_signature – the signature using the shared secret(s)
privileges – the requested privileges, separated by “+”

Request Example:

GET /oauth/temporarycredentials HTTP/1.1
Authorization: OAuth realm="Scrive",

Response Example:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

Resource Owner Authorization

The user is redirected to a URL constructed by the client. Query parameters are added to the above URL and the user makes a GET request.

Request parameters:

oauth_token – the same oauth_token returned in the response above (temporary credentials)

Request example

GET /oauth/authorization?oauth_token=789_12

Scrive will verify the request, authorize the user, confirm privileges with the user, and redirect the user back to the callback given in the Temporary Credential Request.

Scrive will construct a URL from the callback URL by adding the following query parameters.

Callback parameters:

oauth_token – the same oauth_token above
oauth_verifier – OAuth verification code

Token Request

After the callback has been requested, the client makes a final GET request to Scrive to get the token credentials used to authenticate API requests. Once the token credentials have been obtained, they never expire. The token credentials should be saved by the client to avoid the OAuth flow in the future. A user can view and delete his associated token credentials in the Account Section.

Example request:

GET /oauth/tokencredentials HTTP/1.1
Authorization: OAuth realm="Example",

Response parameters:

oauth_token – The token credentials identifier
oauth_token_secret – The token credentials secret

Example Response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

We use the PLAINTEXT method of signature since we use SSL.

When the user denies a request

If the user denies an authorization request, Scrive will redirect the user to the callback URL with a query parameter denied=true.

Example redirect (assuming callback URL is

HTTP/1.1 302 OK

API Calls using OAuth Token Credentials

Given an access token, the client can perform API calls if a suitable authorization header is provided. The header should contain the client credentials as well as the token credentials.


Authorization: OAuth realm="Example",

API Calls using Personal Access Credentials

Instead of using OAuth, clients may access the Scrive API using personal access credentials. A user can create personal access credentials in the Scrive Account Section or using a dedicated call.


Only one personal token is available per user. Such credentials can be used instead of OAuth client and token credentials in API calls. The personal access credentials are associated with the user and can be used instead of any other OAuth priviliges.

Personal tokens are intended for special integrations, and storing them outside of Scrive system is equivalent to storing a users password. Because of this we recommend not using Personal Tokens if it can be avoided.


Given the personal access credentials

Client credentials identifier: 123
Token credientials identifier: 234
Client credentials secret: 345
Token credentials secret: 456

a valid authorization header is


OAuth and Cookies

Since Scrive API is used internally by Scrive web system, all API calls support two kinds of authentification - one based on OAuth tokens and one based on browser cookies. The distinction is made based on the existance of the Authorization header in the request. If such a header is set, cookies set by the browser will be ignored.

Available privileges

The current API version accepts following privileges names: DOC_CREATE, DOC_CHECK, DOC_SEND. Details on what permission is required for what API call can be found in next section.


Scrive is a service for signing documents electronically. Therefore, we start by stating that there is a type called Document that represents any document that is to be signed. The goal of the Scrive API is to allow the user to perform an operation on the users document(s) without accessing the web interface. The Oauth authorization mechanism, defined in the previous previous chapter, is used to provide external services with access to the API in order to perform such operations on behalf of the user. To understand what operations are available and how they can be useful we need to shortly describe how Documents work.

Document life cycle overview

Documents in Scrive have only one simple life-cycle path. The life cycle starts when a document is created. For example a document can be created based on a PDF file. The newly created document is called a Draft and the author can set some of its properties, like names of signatories or that it should be signed using E-legitimation authorization. At this point any property of the document can be changed. When the user is done working with the draft, the user can inform Scrive that the document is ready to be signed. After that, the document becomes Pending and the only actions that can be performed on it are signing or rejecting by individual signatories. When all signatories have signed it (or one of them has rejected it), the document becomes Closed (or Rejected) and it cannot be changed anymore. A pending document can also be withdrawn by the author, and then becomes Canceled.

Although there are a lot of details connected to the document signing work-flow, this path does not change and is a core concept of Scrive.

Overview of API calls

The current version of Scrive offers five calls that allow a user to create documents, modify them, allow signatories to sign them, and determine the status of the documents. The API will not provide any automated way to sign a document as this is an action that due to security reasons should be performed through the Scrive web interface.

Name Description
Create from file Create new draft based on PDF file
Create from template Create new draft based on existing template in Scrive system
Change main file Changes PDF associated with draft
Update Change properties of a draft
Ready Move drafts to pending state
Cancel Cancel a pending document
Get Check state of a document
List Get list of available documents
Delete Delete a document
Remind Send out reminders to signatories
Download main file Downloads main file of document. Result of this call depends on state of document
Download file Downloads any file associated with document

API calls and connection to document life cycle

All API calls are HTTPS requests authorized using OAuth authorization from previous chapter. This means that each request has to have an authorization header added with proper token values set. JSON is used as the data exchange format. The only exception to that is sending files, which uses MIME. The response code for an API call will always be 20x on success, and 40x or 50x on failure.

Working with JSON

Documents in the API are represented by JSON objects. JSON is a cross-platform standard for communicating structured data. When using JSON in the Scrive API, a few guidelines should be followed to ensure future compatibility:

  • When receiving JSON data from the server, the client should ignore object keys that it does not recognize. New keys may be added in the future. By ignoring them, a client will not cease to function if the API changes.

  • When receiving JSON, the order of key/value pairs in an object is unimportant. Objects should be treated as associative arrays or dictionaries.

  • When sending JSON, the absence of a value for a particular key indicates to the server that the default value should be used. The default value will be indicated in the documentation.

  • Some keys are specifically ignored by the server, depending on the request. For example, the modification time cannot be set directly, so it is ignored if passed in as part of the request. This allows the same format to be used for both creating a document and receiving information about a document. Which keys are ignored will be specified in the documentation. There are also a few common problems with JSON that deserve mentioning:

  • JSON keys and JSON strings, unlike JavaScript strings, should be surrounded by double-quotes, not single-quotes.

  • Numeric values and Boolean values should not be surrounded with quotes.

  • JSON uses Unicode for encoding text, and the API deploys UTF-8 encoding.

Documents structure

Most of API calls return a JSON document structure, and the Update call takes it as a parameter. Only the most important parts of this structure are described in this document, and the exact description is available on request. Note that in the future this structure can be extended by adding new fields.

Sample document structure JSON:

"title":"Important contract",
"file": {
  "id": "9222873639019431193",
  "name": "Anställningsavtal.pdf"
"sealedfile": null,
  "id" : "1223"
  "signorder" : 1,
  "signdate" : null,
  "authentication" : "standard",
  "delivery" : "api",
"tags": [{ "name":"tn","value":"tv" }],
"apicallbackurl": null,
"objectversion" : 4

Document fields description

Name Description
Unique ID of document
Title of document
Current status of document. Possible values are: Preparation (status of all Drafts), Pending (status of all Pending documents), one of Closed, Canceled, Timedout, Rejected that represent documents closed for different reasons (Closed status is for signed document only) and DocumentError, that represents some error in the Scrive system.
List of persons that will somehow be involved in document signing. Not all of them need to sign a document. Some may just have a right to view it.
Original file for document.
Sealed file for document. Available only if document is closed.
Way of signing the document by signatories. This field at document level agregates authentication methods of all signatories. Possible values are standard, eleg and mixed. mixed is used when more then one authentication method is used across the whole document. E-legitimation authentication may require some software to be installed by signatories.
Way of delivering the document to signatories. This field at document level agregates delivery methods of all signatories. Possible values are email, pad, mobile, email_mobile, api and mixed. mixed is used when more then one delivery method is used across the whole document.
True if a document is a template. A template is a draft that can’t be moved to pending, but can be used to create new drafts. Possible values are true and false.
HTML message that is sent as a part of sign-invitation email, if one should be sent for this document.
Language that should be used when showing a document for signing. Possible values are sv, se, en and gb.
Array of tags connected to document that can be used for further filtering or as meta-data storage. Each tag is a JSON object with fields name and value set.
Document version
URL that server will access on certain document-status changes.

Document id does not change and is a unique way of document identification.

Each document has a set of signatories. At least one signatory,corresponding to the author, is always connected to a document. In case of a document created by the API this is always the user that authorized API calls. Note that signatories do not have to be a ‘signing party’ of a document.

The signatory order does matter and the first element always represents the author. Each signatory has at least three fields : signs, a boolean that indicates if the signatory is supposed to sign, author that is true only for first one on the list, and fields, a collection of signatory details, like name or email. Fields have type, name, value and placements. Document version value is a number that grows as a document changes. Almost all changes to a document increase this value, and most of API calls that alter a document can take it as additional parameter to detect conflicts.

If apicallbackurl is set on any change of document, Scrive will do a HTTP POST request to given adress, with document id passed as a parameter.

File descriptions are JSON objects with id and name fields. id value can be used to download a file from server.

Signatory fields description

Name Description
Unique identifier of 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.
List of fields
true if a signatory is supposed to sign a document.
true if a signatory is author of document. Only one author per document is allowed.
Way of signing the document by signatory. Possible values are standard and eleg.
Way of delivering the document to signatory. Possible values are email, pad, mobile, email_mobile and api.
Number indicating order of signing. Signatories with a lower number sign before ones with higher number.
Time of signing a document by given signatory.
Link that a signatory can use to sign a document. It is only provided if signatory delivery method is set to api and document is ready for signing.
If this field is set, after signing a document, signatory will be redirected to given adress.

Each signatory has a list of fields. Fields can be seen as type, name and value tripples that are connected with given signatory. Available field types are standard, text, checkbox and signatue. Fields of standard type have a special meaning in the system.

Standard Field Types

Standard Field Name Description
First name of signatory
Last name of signatory
Email address of signatory
Mobile phone number of signatory. If delivery with text messages is used, this value should be precede with `+` and country code
Name of the signatory’s company
Company number of signatory
Personal number of signatory

Fields are identified by name and type combination. The field’s value is either provided by the author, or the signatory will be asked to fill it in. placements is a list of places where the value of the field should be printed on the PDF file after the document is signed.

If api delivery method has been set and document has been sent already, the field signlink will be set for every signatory. This is the same link that is sent by email in the standard Scrive signing process. The link will not contain the host part (so the value will be /s/123 instead of

The best way to learn more about the document structure is to create a document in Scrive using the web interface and get the JSON describing such document using the Check API call.

API Calls

General notes

Most API calls that change existing documents can take the object version as an aditional parameter. If it is provided and it does not match current document object version, the api call will fail with 409 response code.

Create from file

Used to create new draft based on a given PDF file.

Required privilege: DOC_CREATE
Method : POST
URL: /api/v1/createfromfile

Parameters: PDF file. Request Content-Type must be multipart/mixed, and file is provided as a part with Content-Type: application/pdf;name=”file”.

Returns: Document structure of the newly created document

Create from template

Used to create a new draft based on an existing template. A template id is provided as a part of the URL.

Required privilege: DOC_CREATE
Method : POST
URL: /api/v1/createfromtemplate/$templateid$

Parameters: None.

Returns: Document structure of the newly created document

Change file

Change a PDF file of a draft. A document id is provided as part of the URL. A file is provided in the same way as for the Create from file call.

Required privilege: DOC_CREATE
Method : POST
URL: /api/v1/changemainfile/$documentid$

Parameters: PDF file*.

Returns: Document structure of the changed document.

If no file is provided the current file will be detached from document. This call will alter the title of document to the name of the uploaded file.


Alter some values of a draft. Document id is provided as a part of URL.

Required privilege: DOC_CREATE
Method : POST
URL: /api/v1/update/$documentid$

Parameters: Document structure retrieved by a previous API call in which some fields may have been altered. It should be passed either as a POST parameter named json, or as Content-Type: application/json;name=”json” part of Content-Type: multipart/mixed request.

Returns: Document structure of the changed document

Part of the document structure is read-only. The rest can be modified. The following things are among the fields that can be altered by this call:

  • signatories’ field values, types, and placements, except the name and email address of the author. Fields provided for signatories will replace existing ones new signatories can be added or existing ones can be removed. New signatories actually replace the old ones except for the author
  • title of document
  • invitation message
  • days to sign document limit
  • lang
  • authorization method
  • delivery method
  • callback URL: a URL that will be accessed by the service through a POST request when the document status changes to one of Pending, Closed, Timedout, Rejected, Canceled, or whenever the document is updated by the update API call. There may be other changes to the document that cause the callback URL to be accessed.

Fields with illegal values will generate a bad-request response. Fields that are omitted in an update request will be kept unchanged. Read-only fields will be filtered out, so any attempt to modify a read-only field will be silently ignored.

Note that sending exactly same structure that was returned from one of the other API calls will work fine. The suggested way of working with drafts is to get the document structure using an API call (Create or Check), change the received JSON, and send it back using the update call. This assumes that the document is only manipulated by the client to avoid concurrent update problems. To lower the risk for getting an inconsistent document state between client and server, the following must be noted:

  • Manipulation of a document should only be carried out by one client at a time.
  • There is no server-side detection of concurrent updates from multiple clients to the same document.
  • The document returned in the response to an Update request must be used as the new client state. This is particularly important since neither concurrent updates nor attempts to modify read-only fields are detected by the server.
  • If objectversion is provided and it does not mach, but document can not be altered, the update call will succeed and response will be 2XX.
  • authorization and delivery at document level will override authorization and delivery set at signatory level. If you are trying to change delivery method per signatory, make sure that you will set authorization and delivery at document level to mixed.


Makes a document available for signing. If delivery is set to email, invitation mails will be sent to signatories.

Required privilege: DOC_SEND
Method : POST
URL: /api/v1/ready/$documentid$

Parameters: None.

Returns: Document structure of the pending document.

There is a set of requirements that need to be satisfied before a document can be made available for signing. Currently, the requirements are:

  • A PDF has to be attached to the document as a main file. This should be the case if the document was created from file, or created from a template that had a file attached.
  • If delivery method for signatory is set to email, it must have an email field with a proper value.
  • If delivery method for signatory is set to mobile, it must have an mobile field with a proper value.
  • If delivery method for signatory is set to email_mobile, it must have email and mobile fields with proper values.


Cancels a pending document.

Required privilege: DOC_SEND
Method : POST
URL: /api/v1/cancel/$documentid$

Parameters: None.

Returns: Document structure of the canceled document.


Check current state of document.

Required privilege: DOC_CHECK
Method : GET
URL: /api/v1/get/$documentid$

Parameters: None.

Returns: JSON structure for the selected document.


Lists documents that are available to the user.

Required privilege: DOC_CHECK
Method : GET
URL: /api/v1/list

Parameters: List of tags for filtering (optional).

Returns: Lists of documents available for a user in the Scrive system. These are not only documents sent by the user, but also ones that were sent to the user. Response is a JSON object representing a list structure. If the tags parameter is provided, only documents matching all given tags will be returned.

List structure is a JSON object where a list field holds a list of values returned by the call, and paging fields hold extra paging information.

For the purposes of this document it is only important that the list field is an array of objects, each of them have a field called fields that is also an object, and it has the id field set to document identifier.

The tags parameter is a JSON array. Each object in this array has two fields set (name and value) that correspond to name and value of a tag.



HTTP GET: /api/v1/list?tags=[{"name":"tname", "value": "tvalue"}]




Deletes a document.

Required privilege: DOC_SEND
Method : DELETE
URL: /api/v1/delete/$documentid$

Parameters: None.

Returns: Empty JSON object.

Deleted objects will not show up in calls to the List API call, and may be physically removed from the service at some later point in time. No further API calls should be performed on deleted objects.


Send out reminder emails to signatories of a pending document.

Required privilege: DOC_SEND
Method : POST
URL: /api/v1/remind/$documentid$

Parameters: None.

Returns: Document structure of the document.

Download main file

Downloads the main PDF file from a document. If the document is closed, the downloaded file will be stamped, sealed and digitally signed. If not, all fields added through the Scrive design view will be printed on the PDF.

Required privilege: DOC_CHECK
Method : GET
URL: /api/v1/downloadmainfile/$documentid$/anyfilename.pdf

Parameters: None.

Returns: The specified document’s main PDF file.

The intention of this call is to provide a proper preview for a document while signing. The returned file should be stored to be sure that the document is closed. After document is signed, it may take up to few seconds before the original PDF is digitaly stamped. Due to this, in same case 420 error code may be returned. This does not indicate any problem, and the api call should be just repeated until the final file is ready.

Download file

Downloads the PDF file based on document id and file id.

Required privilege: DOC_CHECK
Method : GET
URL: /api/v1/downloadfile/$documentid$/anyfilename.pdf

Parameters: None.

Returns: PDF file.

Managing users

Creating a User

If the user does not have a Scrive account, he or she will be able to create one quickly in the permissions page. For legal purposes, Scrive must confirm the email address of the Scrive user and all Scrive users must sign the TOS before using our service (signing or sending a document). However, the process has been streamlined to avoid unnecessary difficulty and can be done from within the permissions page.

Managing token credentials and privileges

A Scrive user may manage token credentials and privileges by browsing to /oauth/dashboard on the Scrive server.

Granted Privileges

A user may remove privileges associated with token credentials.

Personal Access Credentials

A user may generate personal access credentials with which he may access his account using the API without using the OAuth flow.

Client credentials

A user may generate new and delete existing client credentials. These are used by client software to initiate the OAuth flow.