Migrating and Updating Apps

Updating API authentication methods

Adobe is committed to providing a safe and secure product experience for our customers by adhering to the latest industry-standard security protocols. As a part of that process, on December 2021, Adobe Acrobat Sign ended support for older API authentication models that allowed sending a username and password in the API call.

To move to a secure authentication model:

• Use REST APIs: Acrobat Sign APIs are now restricted to REST APIs. You can try out the REST API here.

• Use OAuth: To enable an end user to use your client app with Acrobat Sign, have the end-user authenticate with Adobe. The recommended way for authenticating end users with Acrobat Sign is the standard OAuth protocol.

The general recommendation is that every user in the organization should directly authenticate with Adobe while using your client app to have their unique access tokens issued. SAML configuration with Acrobat Sign in your user’s organization provides an easy way to do so. However, there might be enterprise use-cases where only a single admin is required to authenticate with Adobe and other users in this organization can just use the client without an Adobe login. This is possible via Adobe’s OAUTH modifiers. Modifiers enable clients to call APIs with admins’ OAUTH token and actual regular user’s identity in “x-api-user” header.

Migrating From SOAP

Applications using the legacy Acrobat Sign SOAP APIs should migrate to the more functional and secure v6 REST APIs.

SOAP to REST mapping

The tables below maps SOAP endpoints to their REST equivalents. Both endpoints link directly to the full method description.

General-purpose Methods

SOAP Endpoint	REST Endpoint
getBaseUris	/baseUris, GET

Note

Base URIs: API calls starting v5 of REST API must be made on a specific base URL obtained either from the api_access_point returned from the OAuth workflow or by making a call to the GET /baseUris endpoint.

Document Methods

SOAP Endpoint	REST Endpoint
sendDocument	/agreements, POST

SenderInfo is represented through x-api-user. Files are specified through /transientDocuments.

SOAP Endpoint	REST Endpoint
sendDocumentInteractive	/agreements/{agrId}/views, POST

From v6 onwards, the interactive views can be specified and obtained from the POST /agreements/{agrId}/views endpoint for the interactive behavior.

SOAP Endpoint	REST Endpoint
sendDocumentMegaSign	/megaSigns, POST

MegaSign allows sending the same agreement to multiple recipients and creating a separate instance of agreement for each recipient.

SOAP Endpoint	REST Endpoint
createLibraryDocument	/libraryDocuments, POST

SOAP Endpoint	REST Endpoint
createLibraryDocumentInteractive	/libraryDocuments/{libraryDocumentId}, POST

From v6 onwards, the interactive views can be specified and obtained from the POST /agreements/{agrId}/views endpoint for the interactive behavior.

SOAP Endpoint	REST Endpoint
sendReminder	/agreements/{agrId}/reminders, POST

SOAP Endpoint	REST Endpoint
removeDocument	/agreements/{agrId}/documents, DELETE

To delete the documents of agreements, use the DELETE /agreements/{agrId}/documents endpoint; and to remove it from Manage Page(GET /agreements), use PUT /agreements/{agrId}/visibility

SOAP Endpoint	REST Endpoint
cancelDocument	/agreements/{agrId}/state, PUT

Cancel: Called by sender.

SOAP Endpoint	REST Endpoint
rejectDocument	/agreements/{agrId}/members/participantSets/{psId}/participants/{pId}/reject, PUT

Reject: Called by current signer.

SOAP Endpoint	REST Endpoint
replaceSigner	/agreements/{agreementId}/members/participantSets/{participantSetId}, PUT

Replace: Called by sender. Both the original signer and new one can sign.

SOAP Endpoint	REST Endpoint
delegateSigning	/agreements/{agrId}/members/participantSets/{psId}/ participants/{pId}/delegatedParticipantSet, POST

Delegate: Called by signer. Both the delegator and delegatee can sign.

SOAP Endpoint	REST Endpoint
notifyDocumentVaulted	/agreements/{agreementId}/vaulted, PUT

Status Methods

SOAP Endpoint	REST Endpoint
getDocumentInfo	/agreements/{agrId}, GET

In SOAP API, getDocumentInfo, getDocuments, getAuditTrail etc. work on documentKeys, which can be an ID for an agreement, widget, or library document. The REST API demarcates these as separate resources (cleaner design and strongly typed) and hence, based on the kind of resource you are working on, there is a corresponding /libraryDocuments, /widgets to these. Example: /widgets/{widgetId}, GET will getDocumentInfo for widgetId, and similarly for documents, audit trail, etc.

SOAP Endpoint	REST Endpoint
getDocumentInfosByExternalId	/agreements, GET query = externalId

externalId can be used to map your internal IDs to Acrobat Sign IDs.

SOAP Endpoint	REST Endpoint
getDocuments	/agreements/{agrId}/documents, GET

REST returns a list of document IDs that can be provided to the following endpoint to get a document stream.

SOAP Endpoint	REST Endpoint
getDocumentUrls	/agreements/{agrId}/combinedDocument/url, GET

Retrieve the URL of the combined document.

SOAP Endpoint	REST Endpoint
getDocumentUrls	/agreements/{agrId}/documents/{docId}/url, GET

Retrieve the URL of an individual document.

SOAP Endpoint	REST Endpoint
getDocumentImageUrls	/agreements/{agrId}/documents/imageUrls, GET

Retrieve the image URLs of all visible pages of an agreement.

SOAP Endpoint	REST Endpoint
getDocumentImageUrls	/agreements/{agrId}/documents/{docId}/imageUrls, GET

Retrieve image URLs of a specified documentID.

SOAP Endpoint	REST Endpoint
getSupportingDocuments	/agreements/{agrId}/documents, GET

Can also specify the content format.

SOAP Endpoint	REST Endpoint
getFormData	/agreements/{agrId}/formData, GET

Returns a CSV file stream.

SOAP Endpoint	REST Endpoint
getAuditTrail	/agreements/{agrId}/auditTrail, GET

SOAP Endpoint	REST Endpoint
getSigningUrl	/agreements/{agrId}/signingUrls, GET

User Methods

SOAP Endpoint	REST Endpoint
createUser	/users, POST

SOAP Endpoint	REST Endpoint
verifyUser	/users/{userId}, GET

The REST equivalent can be used to see if the user exists, but does not support password verification.

SOAP Endpoint	REST Endpoint
searchUserDocuments	TBD

SOAP Endpoint	REST Endpoint
getDocumentEventsForUser	/agreement/{agrId}/events, GET

SOAP Endpoint	REST Endpoint
getEmbeddedView	/agreements/{agrId}/views, POST

Use the name = DOCUMENT to get the embedded view of an agreement.

SOAP Endpoint	REST Endpoint
getUserDocuments	/agreements, GET

SOAP Endpoint	REST Endpoint
getMyDocuments	/agreements, GET

Use x-api-user for specifying the user whose agreements are to be retrieved.

SOAP Endpoint	REST Endpoint
getLibraryDocumentsForUser	/libraryDocuments, GET

SOAP Endpoint	REST Endpoint
getMyLibraryDocuments	/libraryDocuments, GET

Use x-api-user for specifying the user whose library documents are to be retrieved.

SOAP Endpoint	REST Endpoint
getWidgetsForUser	/widgets, GET

SOAP Endpoint	REST Endpoint
getMyWidgets	/widgets, GET

Use x-api-user for specifying the user whose widgets are to be retrieved.

SOAP Endpoint	REST Endpoint
getMegaSignDocument	/megaSigns/{megaSignId}/agreements, GET

Get all child agreement IDs of the parent MegaSign.

SOAP Endpoint	REST Endpoint
getUsersInAccount	/users, GET

SOAP Endpoint	REST Endpoint
createGroup	/groups, POST

SOAP Endpoint	REST Endpoint
deleteGroup	/groups/groupId, DELETE

SOAP Endpoint	REST Endpoint
renameGroup	/groups/{groupId}, PUT

SOAP Endpoint	REST Endpoint
getGroupsInAccount	/groups, GET

SOAP Endpoint	REST Endpoint
getUsersInGroups	/groups/{groupId}/users, GET

SOAP Endpoint	REST Endpoint
moveUsersToGroup	/users/{userId}/groups, PUT

Specify the new groupId in the request.

SOAP Endpoint	REST Endpoint
getUserInfo	/users/{userId}, GET

Web Form Methods

SOAP Endpoint	REST Endpoint
createEmbeddedWidget	/widgets, POST

SOAP Endpoint	REST Endpoint
createPersonalEmbeddedWidget	/widgets/{widgetId/views, POST

Use PersonalizedSigningViewConfiguration for specifying personalization options

SOAP Endpoint	REST Endpoint
personalizeEmbeddedWidget	/widgets, POST

SOAP Endpoint	REST Endpoint
createUrlWidget	/widgets, POST

SOAP Endpoint	REST Endpoint
createPersonalUrlWidget	/widgets/{widgetId/views, POST

Use PersonalizedSigningViewConfiguration for specifying personalization options

SOAP Endpoint	REST Endpoint
personalizeUrlWidget	/widgets, POST

SOAP Endpoint	REST Endpoint
disableWidget	/widgets/{widgetId}/state, PUT

Use status value as INACTIVE.

SOAP Endpoint	REST Endpoint
enableWidget	/widgets/{widgetId}/state, PUT

Use status value as ACTIVE.

SOAP Endpoint	REST Endpoint
personalizeEmbeddedWidget	/widgets, POST

SOAP Endpoint	REST Endpoint
personalizeUrlWidget	/widgets, POST

Test Methods

SOAP Endpoint	REST Endpoint
testPing	/baseURIs, GET

SOAP Endpoint	REST Endpoint
testEchoFile	TBD

Deprecated SOAP Methods

Access Methods

issueAccessToken - OAuth has replaced access tokens.

Doc Methods

SOAP Endpoint	REST Endpoint
initiateInteractiveSendDocument	/agreements/{agrId}/views, POST

Status Methods

SOAP Endpoint	REST Endpoint
getDocumentUrlByVersion	/agreement/{agreementID}/combinedDocument/url, GET

SOAP Endpoint	REST Endpoint
getDocumentByVersion	/agreements/{agreementId}/combinedDocument, GET

SOAP Endpoint	REST Endpoint
getImagesByVersion	/agreements/{agrId}/documents/imageUrls, GET

SOAP Endpoint	REST Endpoint
getLatestDocument	/agreements/{agrId}/documents, GET

SOAP Endpoint	REST Endpoint
getLatestDocumentUrl	/agreements/{agrId}/documents/{docId}/url, GET /agreements/{agrId}/combinedDocument/url, GET

SOAP Endpoint	REST Endpoint
getLatestImages	/agreements/{agrId}/documents/imageUrls, GET /agreements/{agrId}/documents/{docId}/imageUrls, GET

User Methods

SOAP Endpoint	REST Endpoint
getDocumentsForUser	/agreements, GET

SOAP Endpoint	REST Endpoint
createAccount	None