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 http://oauth.net/). 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:
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.
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.