API Usage

The Acrobat Sign API allows you to quickly build client-side applications that can utilize the signing functionalities offered by Acrobat Sign. This guide contains the most common scenarios in which you can use the API.

Using the Acrobat Sign REST APIs, you can build elegant and scalable client-side applications in any scripting language that supports REST-based API calls. This section provides information on the API endpoint, request headers, request body, and the response.

A 3-step basic signing workflow involves:

Send for Signing (Create an Agreement)

Your CRM or document management system can send/upload documents for signing, either automatically or through user-initiated actions. When the document gets signed by all the parties, a PDF copy of the signed document(agreement) can be retrieved by your application.

_images/sign_devguide_1.png

While getting the authorization code from the Acrobat Sign service, you also received the API access point as part of a query parameter (See Add an Authorization Request link)

https://myserver.com/?
    code=CBNCKBAThIsIsNoTaReAlcs_sL4K32wCzs4N&
    api_access_point=https://api.na1.echosign.com/&
    web_access_point=https://secure.na1.echosign.com/

For all future service calls, Acrobat Sign sends the requests to this access point.

Upload a document

To upload a PDF document for signing, send a POST request to the transientDocuments endpoint. This is a multipart request consisting of filename, MIME type, and the file stream. You will get back an ID as a response that uniquely represents the document. Your application needs to specify the recipients and other sending options required for sending the document for signing. Your application can also specify a callback URL that will be used by Acrobat Sign to notify when the signature process is complete.

POST /api/rest/v6/transientDocuments HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer MvyABjNotARealTokenHkYyi
Content-Type: multipart/form-data
Content-Disposition: form-data; name=";File"; filename="MyPDF.pdf"

<PDF CONTENT>

You will get the following JSON body containing the transientDocumentId that will uniquely represent the uploaded document:

{
    "transientDocumentId":"3AAABLblqZhBVYbgJbl--NotArEaLID_zjaBYK"
}

The document uploaded through this call is termed as a transient document since it is available only for 7 days after the upload.

You can only upload one file at a time through this request.

TRY IT OUT

Send the document

Once you have uploaded the document, send the document to all the related parties for signing. For this to happen, you need to create an agreement.

For creating an agreement, send a POST request to the /agreements endpoint with the following JSON body:

POST /api/rest/v6/agreements HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer 3AAABLblNOTREALTOKENLDaV
Content-Type: application/json

{
    "fileInfos": [{
        "transientDocumentId": "<copy-transient-from-the-upload-document-step>"
    }],
    "name": "MyTestAgreement",
    "participantSetsInfo": [{
        "memberInfos": [{
            "email": "signer@somecompany.com"
        }],
        "order": 1,
        "role": "SIGNER"
    }],
    "signatureType": "ESIGN",
    "state": "IN_PROCESS"
}

Replace the value for the following attributes with the correct values:

Attribute

Description

transientDocumentId

The unique ID representing the uploaded document.

name

The name of the agreement.

email

Recipient’s email address.

signatureType

The type of signature you would like to request. The possible values are ESIGN and WRITTEN.

order

Index indicating the position at which this signing group needs to sign. Signing group to sign at first place is assigned 1 as index.

role

Role of the participant set. The possible values are: SIGNER, APPROVER, ACCEPTOR, CERTIFIED_RECIPIENT, FORM_FILLER or DELEGATE_TO_SIGNER, DELEGATE_TO_APPROVER, DELEGATE_TO_ACCEPTOR, DELEGATE_TO_CERTIFIED_RECIPIENT, DELEGATE_TO_FORM_FILLER, or SHARE.

state

The state in which the agreement should land. The possible values are AUTHORING, DRAFT, or IN_PROCESS. You can use a) DRAFT to incrementally build the agreement before sending out, b) AUTHORING to add or edit form fields in the agreement, c) IN_PROCESS to immediately send the agreement. You can use the PUT /agreements/{agreementId}/state endpoint to transition an agreement between the above-mentioned states. An allowed transition would follow this sequence: DRAFT -> AUTHORING -> IN_PROCESS -> CANCELLED.

You will get the following response containing the id:

{
    "id": "<an-adobe-sign-generated-id>"
}

The returned agreementId must be used to refer to the agreement in all subsequent API calls. This ID must be used to retrieve up-to-date status of the agreement, either by polling or when Acrobat Sign notifies your application of any status change.

TRY IT OUT

Check the Document Signing Status

Acrobat Sign can return the current status of the agreement and a complete history of events that have happened on that particular agreement. The simplest mechanism is for your application to provide a webhook URL when sending the document for signature. Acrobat Sign will then ping your webhook with the appropriate event whenever the agreement status changes.

_images/sign_devguide_2.png

You can also get the current status of an agreement by sending a GET request to /agreements/{agreementid}:

GET /api/rest/v6/agreements/3AAABLblqZNOTREALAGREEMENTID5_BjiH HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer 3AAANOTREALTOKENMS-4ATH

You need to provide your access token in the Authorization header and the agreementId in the API call itself. You will get the following JSON response:

{
  "id": "<an-adobe-sign-generated-id>",
  "name": "MyTestAgreement",
  "participantSetsInfo": [{
    "memberInfos": [{
      "email": "signer@somecompany.com",
      "securityOption": {
        "authenticationMethod": "NONE"
      }
    }],
    "role": "SIGNER",
    "order": 1
  }],
  "senderEmail": "sender@somecompany.com",
  "createdDate": "2018-07-23T08:13:16Z",
  "signatureType": "ESIGN",
  "locale": "en_US",
  "status": "OUT_FOR_SIGNATURE",
  "documentVisibilityEnabled": false
}

By default, the webhook URL is called whenever an event involving a particular transaction occurs in Acrobat Sign. The webhook event includes the ID of the agreement whose status has changed, the current status of the agreement, and information on the event that resulted in the callback. Your application logic can evaluate the received status and decide whether to perform an action in the calling system.

In addition to HTTPS GET, Acrobat Sign also alternatively supports PUT for receiving events about the signature process. Included in the request will be the completed signed PDF. Acrobat Sign uses an PUT request to return the signed PDF. Please ensure that your application can correctly handle such a request. Please contact Adobe Support or your assigned Client Success Manager to get your account configured to receive PUT events.

The second mechanism to reflect the most current or up-to-date status of an agreement sent for signature is for your application to periodically poll Acrobat Sign regarding the agreement’s status. The upside of polling is that it can be used in cases where your calling application is behind your firewall and not accessible from the Internet, thus enabling Acrobat Sign to complete a callback. The down side of polling is that you have to create a scheduling mechanism within your application to periodically query the status of all documents that were not yet signed, check whether the document’s status has changed, and update your system accordingly. If you choose to use polling, we recommend you have different policies based on document “age”. In other words, you would reduce the frequency of polling for documents not signed after a certain number of days.

TRY IT OUT

Send Reminders

A signing reminder can be sent to all the signers if they have not signed the agreement. When you send a reminder, the signers will get the same notification email that was originally sent.

_images/sign_devguide_3.png
POST /api/rest/v6/agreements/{agreementId}/reminders HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer 3AAABLblNOTREALTOKENLDaV
Content-Type: application/json
{
  "recipientParticipantIds": [
    "<id of a participant>."
  ],
  "nextSentDate": "< The date when the reminder is scheduled to be sent next.>",
  "status": "< valid status of reminder (ACTIVE)>"
}

Note that you need to provide the agreementId in the request URL. You will get the following response from the server:

{
   id: <An identifier of the reminder resource created on the server>
}

TRY IT OUT

Download the Agreement

Once an agreement is signed, your application can retrieve the signed copy of the PDF and store that within your application.

_images/sign_devguide_4.png

The signed agreement can also be retrieved by sending a GET request to /agreements/{agreementId}/combinedDocument. This will return a single combined PDF document for the documents associated with the agreement. To retrieve any supporting document, you can send a GET request to /agreements/{agreementId}/documents. This will return the IDs of all the main and supporting documents of an agreement.

The returned document ID can be used in the /agreements/{agreementId}/documents/{documentId} call to retrieve the file stream of a document of the agreement. Depending on your application, you can also retrieve the form field data that your signer may have filled in to the document when signing the document by sending a GET request to /agreements/{agreementId}/formData. The data can be used to update your calling application with the information provided by the signer during signing.

Send the following GET request to retrieve the signed agreement:

GET /api/rest/v6/agreements/3AAA5NOTREALIDiH/combinedDocument HTTP/1.1
Host: api.na1.echosign.com:443
Authorization: Bearer 3AAABLblqZhB9BF

The response body will contain the content of the PDF file, which you can save locally through your application.

Note that the agreement can be downloaded even before it gets signed. Provide the versionId attribute when invoking GET /agreements/{agreementId}/combinedDocument/ to get the correct version of the agreement. For example, when the agreement is sent to two entities for signing, and when only one entity signs, the document can still be downloaded. If the versionId is not specified, the document in the latest state is returned.

TRY IT OUT

Create a Widget

To create a widget through the API, you must first call /transientDocuments, then send a POST request to upload the document. This is a multipart request consisting of filename, MIME type, and the file stream. The returned transientDocumentId is to be used to refer to the document in the widget creation call (/widgets, POST). The API endpoint, in addition to the widget key, returns an embed-code, which can be used for embedding the widget within your application, as well as a URL at which the widget gets hosted. The URL can be posted within your application for users to navigate to for signing a document.

POST /api/rest/v6/widgets HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer 3AAABLblqZNotRelaTOKEN
Content-Type: application/json
{
    "name": "MyTestWidget",
    "widgetParticipantSetInfo": {
        "memberInfos": [{
            "email": ""
        }],
    "role": "A valid role of the widget signer (SIGNER/APPROVER)"
    },
    "state": "A valid state in which the widget should land (ACTIVE/AUTHORING/DRAFT)"
}

You will get the following JSON response:

{
    id: <The unique identifier of widget which can be used to retrieve the data entered by the signers.>
}

Now, the Widget URL can be circulated to the parents for signing. At any time, to get information about the Widget, send a GET request to /widgets/{widgetId}.

GET /api/rest/v6/widgets/3AAANotTheRealID6o HTTP/1.1
Host: api.na1.echosign.com

You will get a JSON response containing details about the widget, including participants’ information and status.

You can also send a GET request to /widgets/{widgetId}/formData to retrieve the data entered (by the parents) in the document when it got signed.

Each time a widget is signed by a person, a separate instance of a document gets created. To get the agreements created using the widget, call /widgets/{widgetID}/agreements GET where widgetID is the key returned by the service while creating the widget. To retrieve the data filled by the users at the time of signing the widget, call GET /widgets/{widgetID}/formData. The service returns data in comma-separated value (CSV) file format. The first line includes the column header names, and each row represents a distinct instance of the widget.

TRY IT OUT

Get the Signing URL

When the agreement is ready for signing, invoke GET /agreements/{agreementId}/signingUrls to get the signing URL:

GET /api/rest/v6/agreements/3AANotRealIDQN8_gg/signingUrls HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer 3AAABLblqZNotRelaTOKEN

You will get the following JSON response containing the signing URL:

{
  "signingUrlSetInfos": [
    {
      "signingUrls": [
        {
          "email": "FJ@MYCOMPANY.COM",
          "esignUrl": "https://secure.na1.echosign.com/public/apiesign?pid=CBFNotTheRealIDw3w*"
        }
      ]
    }
  ]
}

Getting the signing URL becomes useful for scenarios involving in-person signing. Load the signing URL in a browser window on a mobile device and get the agreement signed in-person.

TRY IT OUT

API Throttling

To prevent your API from being overwhelmed by too many requests, Adobe throttles requests to your API.

When a request is throttled, the client will receive an HTTP 429 “Too Many Requests” response with an error message appropriate to the request. When a request gets back an HTTP 429 response, it means the user has consumed over the limit of allowed resources in a certain period of time. It could be a violation of per-minute, -hour, or -day limit. The user will be allowed to make more requests in the next minute, hour, or day (depending on which threshold was crossed).

Each request made to Acrobat Sign is evaluated based on the amount of system resources it will consume. Different parameters passed to the same endpoint might contribute a different amount of resource consumption. Your service package (small business, business, enterprise) directly influences your transaction rate. Higher tiers of service have higher throttle thresholds.

REST API Response

{
"code":"THROTTLING_TOO_MANY_REQUESTS",
"message":"<error_message_with_wait_time> (apiActionId=<api_action_id>)"
"retryAfter": <wait_time_in_seconds>
}

Also, a Retry-After HTTP header will be added into the response (see RFC-7231 Section 7.1.3)

Retry-After: <wait_time_in_seconds>

is the minimum time in seconds the client must wait until it can make the next request. When the retryAfter timer expires, the client’s resource count is reset to 0 for the over-limit threshold. Therefore, the client can send the request again and it should go through without being blocked.

Steps to take when throttled

It is recommended that developers design workflows that can handle the Http 429 exceptions gracefully and use the retry-time from either the response body or from the “Retry-After” header to recover from such errors.