mobile-logo

This document describes how to use Autenti API v1 to send a document and check its status:

  1. Authorize (in: clientId and clientSecret – parameters from company account settings (API tab); out: access_token and identity_id).
  2. Create new document (in: access_token and identity_id from previous step + document description, receivers and viewers; out: documentId).
  3. Upload file to the document (in: access_token, identity_id and documentId from previous step + binary PDF file).
  4. Send the document and SMS (in: access_token, identity_id and documentId).
  5. Check document status and download (in: access_token, identityId, documentId; out: document status and URL). Push notifications to callback URL are also available.
  6. Send a reminder.
  7. Withdraw / Cancel.

 

Before you start coding:

  • Login to app.autenti.com using your company account (administrative privileges required), go to “Account settings” à “API” and click “Generate API access”.
  • Copy client id and secret.
  • Select a person that represents the company. That person will be shown as the person signing the document on behalf of the company. That persons’ e-mail must be used in both methods (/oauth/token – email and /documents/add/ – sender_email).

 

API URL – v1

https://app.autenti.eu
TLS version

1.2

 

Good practices:

  • REST API is based on the HTTP protocol. Each API call returns a status which may be a success („200 OK”) or a failure (almost anything else). The client should always check the status and proceed to the next step only after successful call. The call should be retried after failed response (status code 4xx or 5xx) and after timed out.
  • If you receive “401 Unauthorized” response it means that the token has expired and you must authorize again and retry the request with a new access_token.
  • If you execute many requests please authorize only once per email/identity until a token will expire.
  • There may be errors if you will operate on the same document simultaneously in many sessions.
  • Check size of the response, if you get an empty response (0 bytes) please retry the request.

Go to API settings in web application and click „Generate API” to get clientId and clientSecret:

 

 

URI

/oauth/token
method

POST
headers

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

User-Agent: any
payload

client_id={clientId}&client_secret={clientSecret}
&grant_type=company_key&[email protected]
response

200 OK

{

    access_token : ‘3f2c097c-xxxx-4b58-9c7c-ab399c5d8254’,

    token_type : ‘bearer’,

    refresh_token : ‘42e3244f-xxxx-44c1-8593-74140cbca0a8’,

    expires_in : ‘43199’,

    identity_id : ‘xxx’

}
example

curl -X POST -H „Content-Type: application/x-www-form-urlencoded” -d ‚client_id={clientId}&client_secret={clientSecret} &grant_type=company_key&[email protected]’ https://app.autenti.eu/oauth/token
note

This method returns access_token and identity_id which are used in next steps.

  • email – (optional) if there is more than one email allowed in account settings for using API than it must be provided which one will be used for the authentication (it affects returned identity_id), email address should be urlescaped (e.g. “+” character)

All parameters should be sent as POST data (payload), not GET.
URI

/api/identities/{identityId}/documents/add
method

POST
headers

Authorization: Bearer {access_token}

Content-Type: application/json; charset=UTF-8
payload

{

   ‘title’ : ‘Document title’,

   ‘message’ : ‘Test message’,

   ‘status’ : ‘NEW’,

   ‘sender_email’ : ‘[email protected]’,

   ‘receivers’ : [

      {

         ‘email’ : ‘[email protected]’,

         ‘phone_number’ : ‘600400300’,

         ‘user_first_name’ : ‘John’,

         ‘user_last_name’ : ‘Doe’,

         ‘company_name’ : ‘‘,

         ‘company_nip’ : ‘‘,

         ‘company_country’ : ‘PL’,

         ‘with_company’ : false

      }

   ],

   ‘viewers’ : [

      {

         ‘email’ : ‘[email protected]’

      }

   ]

}
response

200 OK

{
’id’ : ‘123’ //this is documentId
}
note

This method creates a new document and returns its id. Files are attached in next step.

Attributes:

  • sender_email – it must match with email used in /oauth/token method or if there is only one email allowed in account settings for using API it must match with that email
  • receivers – array of one or more signatories
  • viewers – array of one or more observers
  • phone_number – 9 digits (only polish mobile numbers), necessary with requireSmsCode=true in /start method
  • company_name* and company_nip** – necessary with option with_company set to true
  • company_country – 2 letter country code (e.g. PL)
  • * if with_company=true and company_name is null and company_nip is provided, then application will try to search Autenti database for the company name
  • ** if company_country is null or is set to ”PL” than company_nip must be valid polish NIP, for other countries NIP is not validated
errors

{

   „errors” : [

      {

         „recipient”:”[email protected]”,

         „type”:”WRONG_NIP”,

         „value”:”1234123412″

      },

      {

         „recipient”:”from+fake_company_user_autenti.com”,

         „type”:”WRONG_EMAIL”,

         „value”:”from+fake_company_user_ autenti.com”

      },

      {

         „recipient”:”[email protected]”,

         „type”:”EMPTY_COMPANY_NAME”,

         „value”:””

      },

      {

         „recipient”:”[email protected]”,

         „type”:”EMPTY_COMPANY_NIP”,

         „value”:””

      },

      {

         „recipient”:”[email protected]”,

         „type”:”INVALID_COMPANY_COUNTRY_CODE”,

         „value”:”EN”

      }

   ],

   „exception”:”InvalidDocumentRecipientException”,

   „error”:null

}
URI

/api/identities/{identityId}/documents/{documentId}/upload-file
method

POST
headers

Authorization: Bearer {access_token}

Content-Type: multipart/form-data; boundary=BOUNDARY

Content-Length: {PDF_DATA_LENGTH}
payload

–BOUNDARY

Content-Disposition: form-data; name=Filename; filename=”Filename.pdf”

Content-Type: application/pdf

………………………………….PDF_BINARY_DATA…………………………

–BOUNDARY–
response

200 OK
example

var headers = {

  ‚Authorization’ : ‚Bearer ‚ + access_token

};

var boundary = ‚MYBOUNDARY’;

var requestBody = Utilities.newBlob(‚–‚ + boundary + “\r\n” + ‚Content-Disposition: form-data; name=Filename; filename=”Filename.pdf”’ + “\r\n” + ‚Content-Type: application/pdf’ + “\r\n\r\n”).getBytes();

requestBody = requestBody.concat(PDF_DATA);

requestBody = requestBody.concat(Utilities.newBlob(“\r\n“ + boundary + “–\r\n”).getBytes());

var options = {

  ‚method’  : ‚POST’,

  ‚contentType’ : ‚multipart/form-data; boundary=’ + boundary,

  ‚headers’ : headers,

  ‚payload’ : requestBody,

  ‚ContentLength’ : PDF_DATA_LENGTH

};

UrlFetchApp.fetch(url + ‚/api/identities/’ + identity_id + ‚/documents/’ + document_id + ‚/upload-file’, options);
note
  • Max. file size: 10MB
  • PDF_DATA – binary content of the PDF file
  • PDF_DATA_LENGHT – size of the PDF file
  • Please don’t send “Expect” header (or set it empty).
URI

/api/identities/{identityId}/documents/{documentId}/start
method

POST
headers

Authorization: Bearer {access_token}

Content-Type: application/json; charset=UTF-8
payload

{
‘senderAutosign’ : false,

  ‘requireSmsCode’ : false,

  ‘redirectUrl’ : ‘https://xxx’
}
response

200 OK
note

It sends URL to the document by email to receivers and viewers.

  • senderAutosign – (optional) if set true than the document will be automatically signed by the identity with sender_email = email (it requires providing email in /oauth/token and the same sender_email in /documents/add) – using this option requires Autenti permit and additional formal declarations to Autenti from the client
  • requireSmsCode – (optional) if set true receivers get also SMS with PIN code necessary to sign the document and phone_number is required in /documents/add method
  • redirectUrl – (optional) redirects user after signature to provided URL (it should be urlescaped), the URL may contain the following variables: $firstName$, $lastName$, $email$, $phone$, $documentId$
  • redirectLastSignerOnly – (optional, default true), if set false redirects all signing users, not only the last one

Get one document:

 

URI

/api/identities/{identityId}/documents/{documentId}
method

GET
headers

Authorization: Bearer {access_token}

Content-Type: application/json; charset=UTF-8
payload

–
response

200 OK

{

  „status” : „ACCEPTED”,

  „files” : [

    { extension=pdf, filename=xxx, file_type=DOCUMENT_SIGNED,

    id=xxx, href=https://app.autenti.eu/api/download/XXX,

    hash=XXX }

  ],

„sender_identities”: [ ],

„receivers”: [ ]

}
note
  • Statuses: NEW, PROCESSING, CANCELED, REJECTED, TERMINATED, ACCEPTED.
  • File types: DOCUMENT_PART (source files), DOCUMENT_MERGED_SOURCES, DOCUMENT_CERTIFICATE, DOCUMENT_SIGNED (this one if the final signed document).
  • Only when the status is ACCEPTED, this method returns also URL to signed document (file_type: DOCUMENT_SIGNED).
  • To download the document, it is also necessary to include in a header valid access token: “Authorization: Bearer {access_token}”.

 

Get a list of documents:

 

URI

/api/identities/{identityId}/documents? documentIds={documentId1,documentId2,documentIdX…}
method

GET
headers

Authorization: Bearer {access_token}

Content-Type: application/json; charset=UTF-8
payload

–
response

200 OK

{

   „count”:4,

   „list”:[

      {

         „id”:2001,

         „title”:”Document one”,

         „message”:null,

         „status”:”ACCEPTED”,

         „files”:[

            {

               „id”:3001,

               „filename”:”2016-11-10-Some-document.pdf”,

               „hash”:”xxxxxx-xxx-xxx-xxx-xxx”,

               „extension”:”pdf”,

               „href”:”https://app.autenti.eu/api/download/xxxxxxxxxxxx”,

               „mime_type”:”application/pdf”,

               „file_type”:”DOCUMENT_SIGNED”

            }, …

         ],

         „person”:{

            „name”:”John”,

            „surname”:”Doe”

         },

         „created_date”:”2016-11-10T22:28:32.357+0100″,

         „sender_identities”:[ … ],

         „sender_email”:”[email protected]”,

         „viewers”:[

            { … }

         ],

         „receivers”:[

            { … }

         ]

      },

      { … } // subsequent documents

   ]

}
note

The method is like the single document version (a) but returns a list.
example

curl -X GET -H „Content-Type: application/x-www-form-urlencoded” -H „Authorization: Bearer xxxxxx-xxx-xxx-xxx-xxx” https://app.autenti.eu/api/identities/{identityId}/documents?documentIds= 2001,2002,2003,2004

 

To setup push notifications go to API settings in web application and enter callback URL:

 

method

POST
body

{
„id”:83112,
„status”:”ACCEPTED”,
„end_date”:”2018-07-26T14:47:53+0200″
}
note
  • JSON notification is sent in request body, its format is identical like in the method for checking document status.
  • If there is “?json=” parameter in notification URL, JSON data will be additionally provided in request params of URL (urlencoded).
URI

/api/identities/{identityId}/documents/{documentId}/remind
method

POST
headers

Authorization: Bearer {access_token}
payload

[email protected]
response

200 OK
example

curl -X POST -H „Authorization: Bearer 6e7871f7-xxxx-481e-84ec-894d19bb7871” https://app.autenti.eu/api/identities/33/documents/250
/remind?email=john%[email protected]
Note
  • email – must be urlescaped
URI

/api/identities/{identityId}/documents/{documentId}/cancel
method

POST
headers

Authorization: Bearer {access_token}
response

200 OK

{

 „response” : „Document id: ” + id + ” cancelled.”

}
note

The method is available only for the sender of a document and only for documents in PROCESSING state (it is not available for ACCEPTED).