Please refer to `Document` in the [Definitions](#definitions) for a
detailed description of all the fields available, and their use.
## Templates
It is possible to set up template documents to be used with the "new
document from template" API call.
Any document in preparation can be made into a template by executing an
update call and setting the `"template"` field to be `true`. This cannot be
reversed once set, and templates cannot direclty be made into documents for
signing.
Templates have the same JSON structure as regular documents and can also be
updated.
In particular, their `"id"` can be used to
[create a new document from a template](#new-document-from-template).
Updating a template will only affect documents created from a template
*after* the template was updated.
Finally, using the list call, it is possible to list all your available
templates by setting the appropriate filters.
## Parties
Every Document has an array field named `parties`.
This defines the signing and viewing parties to a document, their details,
how the document is to be delivered to them, an extra authentication that
must be performed, etc.
It is possible to add an extra party to a Document in preparation using the
`update` call.
Simply add an extra empty object (*i.e.* `{ }`) to the list of existing
parties and the Scrive API will return an additional party populated using
default values.
Each party has a unique `id`, which we refer to as the `signatory_id`.
As with Documents, not all fields may be changed using the `update` call.
For details of this data structure, please refer to `Signatory` in the
[Definitions](#definitions).
## Callbacks
The Scrive eSign system can trigger API callbacks when some significant
property of a Document changes, as for example, when a signing party signs
the Document.
For callbacks to be triggered, you need to set the `api_callback_url` value
on the Document.
You can also trigger callbacks manually using the `callback` API call (this
call has no effect if the `api_callback_url` is not set).
For certain use cases it is possible to instead have a "User callback
scheme" defined.
You will need to contact us to set this up, and setting callbacks on
Documents is the preferred solution.
The Scrive eSign system will perform an `HTTP POST` request, with the
following `POST` parameters:
* `document_id`: As the name implies, the unique Document ID
* `document_json`: The Document JSON, see [Definitions](#definitions)
* `document_signed_and_sealed`: A boolean `true` or `false`, which indicates
whether the document has been signed and sealed with a digital signature
There will generally be two callbacks executed with
`document_signed_and_sealed` set to `true`.
The first will be shortly after all signing parties have signed the document
and Scrive has applied a digital signature, and the second will be
issued when a keyless signature has been applied to the document.
This usually happens between 15-30 days after the original signing date.
We guarantee to make *at least* one callback when the Document status
changes to one of the following values:
* `pending`
* `closed`
* `canceled`
* `timedout`
* `rejected`
We cannot guarantee to make only one callback per status change, and we may
trigger callbacks for changes not listed here.
Furthermore, a callback does not indicate _what_ changed in a document, it
simply tells you the current state of a document.
Finally, callbacks will not be triggered for documents that have been
deleted.
The Scrive eSign system will look at the HTTP response code returned by the
callback URL.
If it is not an HTTP `2xx` response, then the callback will be retried in
increasing intervals, the first after 5 minutes.
After 10 failed attempts, we will no longer attempt the callback.
We may modify the specifics of this behaviour without notice.
# Authentication
The Scrive Document API supports OAuth 1.0 and personal access credentials
based on this.
Where your application needs to perform actions on behalf of Users, the
recommended approach is to use the full OAuth workflow.
## Personal Access Credentials
> You can retrieve personal access credentials for a user account using a
> special endpoint and supplying their login details.
>
> Using cURL, you can do:
```bash
curl -X POST 'https://{server_address}/api/v2/getpersonaltoken' \
--data-urlencode 'email={user_email}' \
--data-urlencode 'password={user_password}'
```
> Replacing `{server_address}`, `{user_email}` and `{user_password}` to
> the appropriate values.
>
> Or, if you are using the `login_token` method:
```bash
curl -X POST 'https://{server_address}/api/v2/getpersonaltoken' \
--data-urlencode 'login_token={login_token}'
```
> Replacing `{server_address}`, `{login_token}` to the appropriate values.
>
> These two methods will both return the personal access tokens as a JSON:
```json
{
"apitoken" : "987dfsd312sd76sh_123"
, "apisecret" : "c47b87126dsacbhb"
, "accesstoken" : "2d1287dassg22jke_114"
, "accesssecret" : "12876adsdhght665"
}
```
> Then, given the following example personal access credentials:
>
> * Client credentials identifier:
> `apitoken = 123`
> * Client credentials secret:
> `apisecret = abc`
> * Token credentials identifier:
> `accesstoken = 456`
> * Token credentials secret:
> `accesssecret = cde`
>
> The following authorisation header can be used:
>
> `Authorization: oauth_signature_method="PLAINTEXT", oauth_consumer_key="123", oauth_token="456", oauth_signature="abc&cde"`
Instead of OAuth, clients may access the Scrive API using personal access
credentials.
A user can create personal access credentials in the [Scrive Account
Section](https://scrive.com/account#api-dashboard) through the web
interface, or using a dedicated API call, as described in the right column.
Only one personal token is available per user.
Such credentials can be used instead of OAuth client and token credentials
in API calls.
The personal access credentials are associated with the user and can be
used instead of any other OAuth privileges, they are intended for special
cases where OAuth is not a viable option, or for getting started quickly in
a sandbox environment.
There are two ways to use this endpoint. One is to provide the username and
password of the user you are creating the personal access credentials for.
The other is to provide a `login_token`. These are temporary tokens created
by the `gettokenforpersonalcredentials` endpoint. These are demonstrated in
the sidebar.
## OAuth
Managing API access is done through a Scrive user account, and each user
account may have zero or more client credentials.
These client credentials are managed in the [Integration settings
tab](https://scrive.com/account#api-dashboard) of the user account
settings.
These client credentials may be used to request privileges from users.
Users, in turn, can approve or deny granting such privileges.
They may also remove privileges as they see fit, from the Integration
settings tab.
The OAuth authorisation sequence allows you to request privileges from a
user and retrieve token credentials.
Once these have been approved, you may use the token credentials to make
API requests on behalf of the user.
### OAuth privileges
The current API version accepts the following privileges names:
`DOC_CREATE`, `DOC_CHECK`, and `DOC_SEND`.
Permission levels required for each API call are described on a per call
basis.
### OAuth and Cookies
As the Scrive eSign web interface uses the Scrive API, all API calls
support two modes of authentication: OAuth based, and browser cookie based.
If the `Authorization` header is set, any browser cookies are ignored.
### OAuth 1.0 Workflow
> ### OAuth Workflow using cURL
> Here we provide some examples using the cURL command.
>
> **1. Temporary credentials request using cURL and response:**
```bash
$ curl 'https://${host}/oauth/temporarycredentials?privileges=DOC_CREATE%2BDOC_SEND' \
-H 'Authorization: oauth_realm="Scrive",oauth_signature_method="PLAINTEXT",oauth_consumer_key="4d224b89875b39af_2",oauth_signature="f446cae781995b05&aaaaaa",oauth_callback="http://www.mywebsite.com/scrive"'
oauth_token=b0d6be3270a2b3ad_8&oauth_token_secret=dac0ec76e037c01d&oauth_callback_confirmed=true
```
> **2. Now redirect the user to:**
```
https://${host}/oauth/authorization?oauth_token=b0d6be3270a2b3ad_8
```
> If the user grants access to your application, they will be redirected to:
```
http://www.mywebsite.com/scrive?=&oauth_token=b0d6be3270a2b3ad_8&oauth_verifier=6382be3e8fcafd94
```
> **3. You should now request for an OAuth token using all the information:**
```
$ curl '${host}/oauth/tokencredentials' \
-H 'Authorization: oauth_realm="Scrive",oauth_signature_method="PLAINTEXT",oauth_consumer_key="4d224b89875b39af_2",oauth_signature="f446cae781995b05&dac0ec76e037c01d",oauth_token="b0d6be3270a2b3ad_8",oauth_verifier="6382be3e8fcafd94"'
oauth_token=0e870aa5ff434d5a_2&oauth_token_secret=22adb49346ba7674
```
> You should now be able to perform an API call, for example:
```
curl -X POST '${host}/api/v2/documents/new' \
-H 'Authorization: oauth_realm="Scrive",oauth_signature_method="PLAINTEXT",oauth_consumer_key="4d224b89875b39af_2",oauth_signature="f446cae781995b05&22adb49346ba7674",oauth_token="0e870aa5ff434d5a_2"'
```
The OAuth workflow consists of three steps, which we will describe in turn:
1. Temporary credentials request and response
2. Authorisation redirect
3. Token request and response
**1. Temporary Credentials**
You must first request temporary credentials using the client credentials
identifier and secret from your account’s [Integration settings
tab](https://scrive.com/account#api-dashboard).
To do so you must issue a `GET` request to
`https://${host}/oauth/temporarycredentials?privileges=${privileges}` with
the following parameters in the `authorization` header:
* `oauth_signature_method="PLAINTEXT"`
* `oauth_consumer_key="${consumer_key}"`
* `oauth_signature="${consumer_secret}&aaaaaa"`
* `oauth_callback="${oauth_callback_url}"`
`${privileges}` must be separated by a `+`, for example
`"DOC_CREATE+DOC_SEND"` (or `%2B` when URL encoded).
You can set `${oauth_callback_url}` to what you like, but it must be set.
The `oauth_signature` must be appended with a dummy `&aaaaaa` at this
stage, it will be replaced with other tokens later.
The reponse should include an `oauth_token`, `oauth_token_secret`, and
`oauth_callback_confirmed=true`.
**2. Authorisation redirect**
You must now redirect the User to
`https://${host}/oauth/authorization?oauth_token=${oauth_token}` using the
`oauth_token` from the previous step.
The user will be asked to grant you the requested privileges, displaying
your company name.
If they accept, they will be redirected to:
* `${oauth_callback}?=&oauth_token=${oauth_token}&oauth_verifier=${oauth_verifier}`
If they reject, the redirection will be to:
* `${oauth_callback}?=&oauth_token=${oauth_token}&denied=true`
Therefore, you should be able to inspect the redirection to the callback
URL.
**3. Token request**
Now you should have the following pieces of information:
* `oauth_consumer_key`
* `oauth_token`
* `oauth_verifier`
We then use `oauth_signature_method="PLAINTEXT"` and construct a new
`oauth_signature` from the client credentials secret and temporary
credentials secret:
* `oauth_signature_method="PLAINTEXT"`
* `oauth_signature="${consumer_secret}&${oauth_token_secret}"`
Finally, we wrap all of this into the `Authorization` header to
`https://${host}/oauth/tokencredentials` and get back an `oauth_token` and
`oauth_token_secret`.
We can now make API calls on behalf of the User by including the finalised
tokens in the `Authorization` header:
* `oauth_consumer_key`
* `oauth_token`
* `oauth_signature_method="PLAINTEXT"`
* `oauth_signature`
# Errors
> Error responses will contain a JSON response body, structured as follows:
```plaintext
{
"error_type": "$error_type$"
, "error_message": "$error_message$"
, "http_code": $http_code$
}
```
> For example:
```json
{
"error_type": "resource_not_found"
, "error_message": "The resource was not found. A document with id $id$ was not found."
, "http_code": 404
}
```
Scrive uses HTTP status codes to indicate the success or failure of an API
request.
HTTP response codes in the `2xx` range indicate that the API call completed
successfully.
The `4xx` range indicates an error, either due to missing, incomplete, or
not applicable information (e.g. missing or invalid parameters, invalid
authorisation, etc.).
When a request is well formed, but does not satisfy necessary conditions,
then we will return a `409` code.
For example, when trying to start the signing process for a document that
has already been signed.
Codes in the `5xx` range suggest an error with Scrive’s eSign system, they
could also indicate planned system downtime, and will be rare.
The following table of error responses applies to all API calls, there may
be additional errors which are specific to the respective API calls, but
will follow the same structure.
| HTTP code | Reason | Error Type and Message |
|---|---|---|
| 400 Bad Request | Obligatory parameters were missing |
The parameter(s) |
| 400 Bad Request | Parameter(s) could not be parsed |
The parameter(s) 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. |
Error message should detail what is wrong with the parameter(s). |
| 401 Unauthorised | No or invalid access credentials |
No valid access credentials were provided. Please refer to our API documentation. |
| 403 Forbidden | Insufficient access privileges for request |
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 |
You do not have permission to perform this action on the document. |
| 404 Not Found | Non existent API endpoint |
The endpoint was not found. See our website for API documentation. |
| 404 Not Found | The endpoint exists but the resource was 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 |
The document has a different |
| 500 Server Error | Other unexpected server error |
We encountered an unexpected error.
Please contact Scrive support and include as much details about
what caused the error, including the |