Skip to main content
Deutsch Deutsch (Deutschland) svenska svenska (Sverige)

Scrive API overview

Basics of a Scrive process

The core entity in any process in Scrive is the document. The document can actually in a sense be seen as the process. Any integration will deal with documents - creating them, modifying them and "starting" them as in "starting the signing process".

This means that the minimal process contains the following steps:

  1. create a document
  2. start the signing process

Usually, there is at least one more step involved: defining who will sign the document. This means who will:

  1. create a document
  2. add/change signatories or signatory information
  3. start the signing process

Below, we will look at what the steps correspond to in API endpoint terms.

The document concept

A document in Scrive is the combination of a JSON string that holds information about a document/process and, optionally, a PDF file. The information is often called metadata and consists of things such as the unique ID of the document, time stamps for events, the list of signatories, "placements" (i.e., fields on the PDF that can be populated), etc.

There is always a JSON for a document. A PDF only needs to exist when starting the signing process.

Creating a document

There are two ways of creating a new process/document. The intuitive way is of course to upload a PDF document. This is done using the /api/v2/documents/new call. The call works like POSTing a multipart/form-data body.

If the same agreement is used many times, the second way of creating a document may be easier: use a Scrive template. This involves some preparation in that one must log in to Scrive and create a template. Once saved, the ID of the template can be found in the URL. This ID is used to create a new document rather than uploading a file programmatically. The relevant API call is /api/v2/documents/newfromtemplate/{document_id} where the template ID is substituted for {document_id}.

Regardless of which method is used to create a document, Scrive will return a JSON file that represents the document. The JSON will include a document ID that represents the newly created document/process. (Both the actual PDF file and much of the metadata in the JSON can be changed at any time before starting the signing process.)

Updating a document

Once a new document ID exists for a document/process, it is possible to change it. The API endpoint for this is /api/v2/documents/{document_id}/update. The endpoint expects a document JSON as payload. Use the JSON you received in the creation step, modified as needed for the updates you wish to make.

Typical changes are:

  • Name/e-mail/phone number of signatory/-ies.
  • Delivery method for signatory/-ies.
  • Setting a callback URL (to get notifications on document status; see below).
  • Populating custom fields in documents started from templates.
  • Removing fields entirely.

To change/set the PDF file used in the process, make a call to /api/v2/documents/{document_id}/setfile.

Starting the signing process

Once everything is in place, start the signing process by making a call to /api/v2/documents/{document_id}/start. Scrive will then start sending out invitations to sign as defined in the document JSON and start calling the callback URL if one was set.

Important

  • Don't implement a full OAUTH workflow for API integrations unless specifically required by your use case. Use the tokens found in your Scrive account (from the top menu, click Account, then click Integration settings) and build the Auth header yourself instead.
  • While it is possible to "get" a document using the API, this should not be used to poll Scrive for documents to determine their status. Instead, set a callback URL for all documents before starting the signing process and Scrive will POST the document JSON to that URL on each relevant change to the document/process. Multiple events near each other in time will be bundled into a single call.
  • Use templates if possible - this lets you place fields, in particular the signing box, using a GUI. Once a new document/process has been created from the template, you can replace the actual PDF if needed.
  • Anchors can be used to anchor a field to a text in a PDF, in case the location of the field needs to change depending on the content of the PDF.
  • You can place extra fields in a template and remove them before starting the signing process.
  • Many integrated customers download and then delete signed ("closed") documents based on signed_and_sealed callback notification. However, keyless signature/sealing is applied only once per month, so if you want a keyless seal, wait for the second signed_and_sealed callback for a specific document before deleting it from Scrive.
  • Support at integrations@scrive.com is always there for you. This is not an outsourced support function with no developer contact. Quite the opposite, in fact.

 

 

Related articles