Revv APIs

This article provides information about Revv’s APIs that enable any application supporting HTTPS requests to create and send documents. The main features of Revv Public API are as follows:

Document and template management

• Create documents
• List all your documents and templates
• Retrieve your documents by using their IDs
• Set the fields of your documents 
• Clone already-created documents that you have already created
• Track the activities of your documents

Sending documents

• Share your documents privately through emails
• Send documents for Fill and eSign
• Send documents for acceptance
• Send documents for approval
• Generate the Magic link for documents

Template management

• View the list of all the active templates
• View the list of all templates

Folder management

• Create folders in your account
• List all the folders that you have created
• Delete any folders in your account
• Move your documents to folders

Contact management

• Add or update contacts in your account
• View the list of all your contacts
• Retrieve your contacts using their IDs or emails
• Delete your contacts

Webhooks (automated in-app messages)

• An automated message is triggered when:
  • A document's stage is changed
  • A document is closed, that is, the document is signed by all signers
  • A document is signed by each recipient

Authentication of Revv API

Revv API follows the OAuth 2.0 authentication process. Each API request requires an access_token as a part of the authentication header. 

Note: OAuth 2.0 is the industry-standard protocol for authentication. It focuses on client developers’ simplicity while providing specific authorization flows for web applications, desktop applications, and many more devices.

The process of authentication is as follows:

Setting up an application

1. Log into Revv using your credentials.
2. Click the Settings icon.
3. Click Revv API.
   
4. Click Add oAuth application.
5. Enter the name of the application that you want to create and click Next. 
6. Enter the Redirect URL and click Create. 
7. Once the URL is verified, the system generates Client ID and Client Secret.
   Note: If you edit the Redirect URL, Client ID and Client Secret do not change. However, when you update the URL, the page is refreshed and Client Secret is lost. It is recommended that you copy Client Secret on your computer because once the page is refreshed, it is not generated again. 
8. Click Add oAuth Client.

The client is successfully added. 

Authorization

This is a one-time browser-based request to associate a Revv user with API requests. You can find Client ID from your Revv account within Settings. 

1. Generate the following URL to authorize your application to use Revv API:
   https://{{url}}/build/api/auth/clients/token?client_id={Client-ID}&client_secret={Client-Secret}&redirect_uri=https://sample-callbackurl.com 
2. Click Authorizeto allow your application to:
   • Create documents on your behalf
   • Send documents on your behalf
   • Download signed documents

These steps return an authorization code that is required to generate a parameter called, access_token.

Note: The authorization fails if you enter an incorrect Client ID or Client Secret.

Creating an access token

The authorization code is used to authorize a user and return access_token. Use this access token as a header in all your API requests.

Refresh access token (Link to API request action)

The access_token parameter eventually expires and your application gets a 401 unauthorized response. You must store the refresh_token parameter that is returned while creating an access token and is also used to create a new access_token.

GET Access Token

https://{{url}}/build/api/auth/clients/token?client_id={Client-ID}&client_secret={Client-Secret}&redirect_uri=https://sample-callbackurl.com&code={Authorize-code}&grant_type=authorization_code

This API used to generate the access_token for the client. The access token is used for all other APIs to check whether the application is authenticated or not.

Params

1. client_id: This is generated in Revv's setting page after adding the client.
2. client_secret: This is generated on the same page at the time of client addition in the application.
3. redirect_url: This is the callback URL provided by the client application owner. The authorized code is sent to this URL.
4. code: It is sent on the redirect URL after a successful authorization.
5. grant_type: It is an authorization_code for this API.

Response Status Code: 200

Headers

Content-Type: application/x-www-form-urlencoded

Params

• client_id: {Client-ID}
• client_secret: {Client-Secret}
• redirect_uri: https://sample-callbackurl.com
• code: {Authorize-code}
• grant_type: authorization_code

GET Refresh Token

https://{{url}}/build/api/auth/clients/token?refresh_token={refresh-token}&grant_type=refresh_token

This API used to generate access_token from refresh_token.

Params

1. refresh_token: This is generated in Access Token API call.
2. grant_type: refresh_token

Response Status Code: 200

Headers

Content-Type: application/x-www-form-urlencoded

Params

• refresh_token: {refresh-token}
• grant_type: refresh_token