Migrate to SignatureAPI
Migrate from Adobe Acrobat Sign
Map Adobe Acrobat Sign agreements, transient documents, participant sets, form fields, webhooks and signing URLs to SignatureAPI envelopes and ceremonies.
This guide maps the parts of an Adobe Acrobat Sign REST API v6 integration to SignatureAPI, with a before-and-after flow for sending a document. Acrobat Sign facts link to Adobe’s developer documentation.
Concept map
| Acrobat Sign | SignatureAPI | Notes |
|---|---|---|
| OAuth 2.0 bearer token (API usage) | API key in the X-API-Key header | No token exchange or refresh. A key_test_ key works in test mode, a key_live_ key in live mode. See Authentication. |
Regional apiAccessPoint from the base URIs call (best practices) | One base URL | Every request goes to https://api.signatureapi.com/v1. |
| Agreement | Envelope | Documents plus recipients. Creating an envelope sends it. |
transientDocuments upload, then fileInfos[].transientDocumentId (API usage) | POST /v1/uploads, then the document url | Same two steps. Files on a supported host need no upload. |
participantSetsInfo with memberInfos, order and role | Recipients with a type and a key you choose | With routing: "sequential", recipients act in the order of the recipients array. See Routing. |
Role SIGNER | signer | Signs the documents. |
Role APPROVER | approver | Approves without signing. See Approver. |
Role FORM_FILLER | preparer | Fills in fields before the signers. See Preparer. |
Role SHARE | No equivalent | Signers receive the signed PDF by email by default. Send copies to other people from your app. |
state (AUTHORING, DRAFT, IN_PROCESS) | No state to set | The envelope goes from processing to in_progress on its own. See the envelope lifecycle. |
formFieldGenerators with anchorTextInfo (API usage) | Places with placeholders or fixed_positions | A placeholder is the text [[place_key]]; the place renders over it. |
| Text tags in the document (text tags) | Placeholders [[place_key]] | The place, not the tag, sets the type and the recipient. |
Library templates (libraryDocumentId) and mergeFieldInfo (API FAQ) | DOCX document templates | Keep the DOCX file in your storage and send values in the document’s data. No template object is stored on the API side. |
signingUrls returning esignUrl (API usage) | Custom authentication and embeddable_in | The ceremony URL comes back on the recipient. See Embedding in a Web Application. |
Webhooks with the X-AdobeSign-ClientId echo (webhook APIs) | Webhooks signed with the Standard Webhooks scheme | Each delivery carries an HMAC signature to verify. Endpoints are set up in the Dashboard. |
AGREEMENT_WORKFLOW_COMPLETED (events) | envelope.completed, then deliverable.generated | Download the signed PDF after deliverable.generated. |
combinedDocument and the audit report (API usage) | Deliverable | One PDF with the signed documents and, for the standard type, the audit log. |
| Developer Edition account (developer guide) | Test mode | Same account, a test key. Test envelopes are free, send no emails and are not legally binding. |
Send a document for signature
Before. Acrobat Sign uploads the file as a transient document, then creates the agreement in IN_PROCESS state (API usage). Adobe’s sample has no signature field; you add one with formFieldGenerators or a text tag in the file:
POST /api/rest/v6/agreements HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json
{
"fileInfos": [{ "transientDocumentId": "<id>" }],
"name": "MyTestAgreement",
"participantSetsInfo": [{ "memberInfos": [{ "email": "signer@somecompany.com" }], "order": 1, "role": "SIGNER" }],
"signatureType": "ESIGN",
"state": "IN_PROCESS"
}After. The same envelope in SignatureAPI, with the signature field included. The document is a URL, and the field is a place assigned to the recipient by key:
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
"places": [
{ "key": "client_signature", "type": "signature", "recipient_key": "client" }
],
"fixed_positions": [
{ "place_key": "client_signature", "page": 1, "top": 172, "left": 210 }
]
}
],
"recipients": [
{ "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane.doe@example.com" }
]
}For a private file, upload it first with POST /v1/uploads and put the returned url in the document. If your files use text tags, replace each tag with a placeholder such as [[client_signature]] and drop fixed_positions.
Embedded signing
Acrobat Sign returns signing URLs from GET /agreements/{id}/signingUrls, and Adobe recommends polling the agreement until it is ready before you ask for them (best practices). SignatureAPI works the same way: give the recipient custom authentication and your page’s origin in embeddable_in, wait until the envelope is in_progress, then read recipients[].ceremony.url and load it in an iframe with embedded=true. The tutorials build the whole flow in seven languages.
Webhooks
Acrobat Sign confirms an endpoint by sending X-AdobeSign-ClientId and expecting it echoed back on each request (webhook APIs). SignatureAPI needs no echo. Instead, verify each delivery: compute an HMAC-SHA256 over webhook-id.webhook-timestamp.body with the endpoint’s signing secret and compare it with webhook-signature. See Webhooks.
| Acrobat Sign event | SignatureAPI event |
|---|---|
AGREEMENT_CREATED | envelope.created |
AGREEMENT_ACTION_REQUESTED | recipient.sent |
AGREEMENT_WORKFLOW_COMPLETED | envelope.completed |
Event names come from Adobe’s events reference. Every SignatureAPI event is listed in Events.
What works differently
- API keys instead of OAuth. There are no scopes, refresh tokens or regional hosts to manage.
- No agreement state to drive. Creating an envelope starts it; there is no authoring step through the API.
- The file is the template. DOCX templates live in your storage, filled from
dataat send time. - No
SHAREparticipants. Send the signed PDF to other people from your app afterdeliverable.generated.
Migration checklist
- Create a test API key in the Dashboard and replace the OAuth flow with the
X-API-Keyheader. - Replace transient document uploads with
POST /v1/uploads, or link files on a supported host. - Map participant roles to recipient types, and text tags or form field generators to places.
- Convert library templates to DOCX files with
{{field}}merge fields. - Add a webhook endpoint in the Dashboard and switch from the client ID echo to signature verification.
- Run your flows in test mode, then switch to a live key.