Skip to content

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 SignSignatureAPINotes
OAuth 2.0 bearer token (API usage)API key in the X-API-Key headerNo 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 URLEvery request goes to https://api.signatureapi.com/v1.
AgreementEnvelopeDocuments plus recipients. Creating an envelope sends it.
transientDocuments upload, then fileInfos[].transientDocumentId (API usage)POST /v1/uploads, then the document urlSame two steps. Files on a supported host need no upload.
participantSetsInfo with memberInfos, order and roleRecipients with a type and a key you chooseWith routing: "sequential", recipients act in the order of the recipients array. See Routing.
Role SIGNERsignerSigns the documents.
Role APPROVERapproverApproves without signing. See Approver.
Role FORM_FILLERpreparerFills in fields before the signers. See Preparer.
Role SHARENo equivalentSigners receive the signed PDF by email by default. Send copies to other people from your app.
state (AUTHORING, DRAFT, IN_PROCESS)No state to setThe envelope goes from processing to in_progress on its own. See the envelope lifecycle.
formFieldGenerators with anchorTextInfo (API usage)Places with placeholders or fixed_positionsA 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 templatesKeep 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_inThe 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 schemeEach delivery carries an HMAC signature to verify. Endpoints are set up in the Dashboard.
AGREEMENT_WORKFLOW_COMPLETED (events)envelope.completed, then deliverable.generatedDownload the signed PDF after deliverable.generated.
combinedDocument and the audit report (API usage)DeliverableOne PDF with the signed documents and, for the standard type, the audit log.
Developer Edition account (developer guide)Test modeSame 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:

HTTP
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:

HTTP
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 eventSignatureAPI event
AGREEMENT_CREATEDenvelope.created
AGREEMENT_ACTION_REQUESTEDrecipient.sent
AGREEMENT_WORKFLOW_COMPLETEDenvelope.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 data at send time.
  • No SHARE participants. Send the signed PDF to other people from your app after deliverable.generated.

Migration checklist

  1. Create a test API key in the Dashboard and replace the OAuth flow with the X-API-Key header.
  2. Replace transient document uploads with POST /v1/uploads, or link files on a supported host.
  3. Map participant roles to recipient types, and text tags or form field generators to places.
  4. Convert library templates to DOCX files with {{field}} merge fields.
  5. Add a webhook endpoint in the Dashboard and switch from the client ID echo to signature verification.
  6. Run your flows in test mode, then switch to a live key.