Attores API tutorial

Attores Pte Ltd
5 min readOct 14, 2016

--

First of all, you need to create a developer account at dashboard.attores.com/keys. Please note that this page is deactivated by default for everybody. We will only activate it for paying subscribers.

For this guide we have also made a few assumptions —

  1. The developer using this API already has the functionality of generating PDF contracts in his app
  2. This guide was written for people who have a basic technical background and understand how to use a REST API.

(You can contact us for more info at gaurang@attores.com and narayan@attores.com)

http://docs.attores.com/

There are two ways of using the Digital Signing 2.0 services offered by Attores through our API.

Scenario 1 —

  • You already have an app built (either a web app or a mobile app)
  • You are generating PDF contracts in your app
  • You are generating the signature images to be placed on those PDFs

Scenario 2 —

  • You have an app built already (either a web app or a mobile app)
  • You have PDF contracts in your app which need to be signed by your users

Scenario 3 —

  • You have an app built already (a web app)
  • You have PDF documents which need to be signed by your users, but you want embedded signing, without the need for the users to leave the website

Based on which category you fall into, there are two ways in which you can use our API

Track 1 —

If you think that you check all the boxes in Scenario 1, you need to use just one endpoint to notarize your signing transactions on the blockchain — sendBlockchainTxn.

You can look at the documentation in the link above and understand how to send a GET request to this endpoint.

This is what the request looks like, when testing through the Postman app

Using Postman to send a GET request to the endpoint — sendBlockchainTxn

Track 2 —

If you think that your app fits in the Scenario 2 mentioned above, you need to follow these three steps —

Step 1 —

First, you will need to Upload your document to our secure servers. Rest assured — we keep your documents in an encrypted format when they are at rest using AES-256 encryption algorithm and we also use a SSL tunnel while uploading your documents.

For this, you need to call the Upload endpoint — uploadPDF. You can find the documentation on the above link. This POST request will return an ID of the document and a MD5 hash. Make sure save both these details since you would be needing them in the next step.

This is what the request looks like, when testing through the Postman app

Using Postman to send a POST request to the API endpoint — uploadPDF

Step 2 —

Now it is time to use the ID and the hash of the document that you received in the previous step and use it to generate a signing request. Please note that you’ll need to generate a signing request for each of the users who need to sign this document.

You need to send a GET request to this endpoint — sendSignRequest. You will find the API documentation at the above link. This endpoint will send an email to the user specified by the email sent in the GET request, and take him to a new page, where he can sign. Once he “Finalizes” the signature, he will be redirected to the redirect URL mentioned in one of the parameters. We will also notify your app at the ‘notifyURL’, so that you can take subsequent actions.

This is what the request looks like, when testing through the Postman app

Using Postman to send a GET request to the endpoint — sendSignRequest

Step 3—

The next step is to download the PDF (if you want). You can call the downloadSignedPDF endpoint from Attores API. This endpoint will stream the PDF to your app, and then you can display it on your UI.

This is what the request looks like, when testing through the Postman app

Using Postman to send a GET request to the endpoint — downloadSignedPDF

Track 3 —

If you think that your app fits in the Scenario 3 mentioned above, you need to follow these three steps —

Step 1 —

First, you will need to Upload your document to our secure servers. Rest assured — we keep your documents in an encrypted format when they are at rest using AES-256 encryption algorithm and we also use a SSL tunnel while uploading your documents.

For this, you need to call the Upload endpoint — uploadPDF. You can find the documentation on the above link. This POST request will return an ID of the document and a MD5 hash. Make sure save both these details since you would be needing them in the next step.

Using Postman to send a POST request to the API endpoint — uploadPDF

Step 2 —

Now it is time to use the ID and the hash of the document that you received in the previous step and use it to generate a signing request. Please note that you’ll need to generate a signing request for each of the users who need to sign this document.

You need to send a GET request to this endpoint — sendSignRequest.

The main difference between Track 2 and Track 3 is that, you will have to send an additional parameter (embeddedSigning = true), which sending the GET request. This will return a URL in the response body, which you can display in an iFrame (the signing page from Attores).

Once he “Finalizes” the signature, he will be redirected to the redirect URL mentioned in one of the parameters. We will also notify your app at the ‘notifyURL’, so that you can take subsequent actions.

This is what the request looks like, when testing through the Postman app

Using Postman to send a GET request to the endpoint — sendSignRequest

Step 3 —

The next step is to download the PDF (if you want). You can call the downloadSignedPDF endpoint from Attores API. This endpoint will stream the PDF to your app, and then you can display it on your UI.

This is what the request looks like, when testing through the Postman app

Using Postman to send a GET request to the endpoint — downloadSignedPDF

--

--