Embed 2.0 API¶

Tip

Your feedback is valuable and is vital in improving our product and documentation. Send suggestions to acrobatsignembed@adobe.com.

The Acrobat Sign Embed 2.0 frictionless model release exposes new APIs for streamlining account management as well as creating and validating new user tokens. Embed 2.0 provides the following benefits:

Seamless onboarding of new customers via the API
Partner ownership of all aspects of their end-customer relationship. End customers are not known to Adobe
Access to the Adobe Admin Console, Global Admin Console, and Developer Console
Support ticket access via the Admin Console
The ability to add, remove, and fully manage end-users independently from Adobe
Eliminates provisioning conflicts

Adobe provisions Embed 2.0 customers with access to both the Global and Admin Consoles so they can:

Use the consoles for managing all licensed Adobe products.
Create and assign roles for partner’s users (e.g. developers; not customers).
Set up Federated directory and define Identity Provider (IdP).
Claim domains (e.g. ‘oempartner.com’) for use with all customers (e.g. bob.smith_joesbikeshop@oempartner.com)

Note

Adobe creates and assigns a Sign ‘channel’ for exclusive partner use. All customer accounts will inherit from this channel’s settings. You will collaborate with the Acrobat Sign partner team to define set of ‘global’ settings for all of your customers.

As described in the onboarding guide, creating a technical account involves these high level steps in the Developer Console:

Create a token for creating a new customer organization within Acrobat Sign.
Use your token for creating new users. Repeat as necessary.
Use the the technical account token in the Adobe Developer Portal, and generate a cURL to create an endpoint such as:

[https://ims-na1-stg1.adobelogin.com/ims/token/v2?grant_type=client_credentials&
client_id=xxxxxxxxxxxx&
client_secret=xxxxxxxxxx&scope=sign_webhook_retention,openid,widget_write,workflow_read,agreement_send,agreement_sign,AdobeID,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,user_management_sdk,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write]
(https://ims-na1-stg1.adobelogin.com/ims/token/v2?grant_type=client_credentials&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxx&scope=sign_webhook_retention,openid,widget_write,workflow_read,agreement_send,agreement_sign,AdobeID,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,user_management_sdk,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write)

Note

The rest of this document provides details about new Embed 2.0 APIs.

Base Endpoint API¶

Get Base_uri

Acrobat Sign APIs come with location awareness, so it’s important to use the correct geographic access point when calling resource-based APIs to ensure success. We highly recommend that clients store the base endpoint URL for each environment. This way, you can retrieve the appropriate geographic access points (https://api.na1.adobesign.com, https://api.eu1.adobesign.com) for your resource-based API calls. Before making any API calls, make sure to include the valid access point returned as part of the base endpoint API in your request.

Base API Host¶
Environment	Base API Host
Sandbox Production	https://api.adobesignsandbox.com
Production	https://api.adobesign.com

Overview¶
Item	Value
HTTP Method	GET
Endpoint Operation	{Base Api Host}/api/rest/v6/baseUris
Description	Very first API call to fetch geographical aware access points before you can call further apis.
Authentication	Valid user/technical account token
Request Header	Auth API Headers
Response Object	BaseUri Response
HTTP Status Code	200
Error Code	BaseUri Error Codes

Response Object¶
Parameter Name	Type	Description
apiAccessPoint	String	The access point from where other APIs need to be accessed. In case other APIs are accessed from a different end point, it will be considered an invalid request.
webAccessPoint	String	Web access point acting as base host domain for all web based calls

BaseUri: Sample Response

{
    "apiAccessPoint": "https://api.na1.echosign.com/",
    "webAccessPoint": "https://secure.na1.echosign.com/"
}

BaseUri: Error Response

Error codes¶
HTTP Status Code	ErrorCode	Message
401	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
401	NO_AUTHORIZATION_HEADER	Authorization header not provided.

Authentication: Token APIs¶

Call these APIs via the AdobeSignAuthService for user token generation and validation:

POST Token: Exchange technical account token for a user token.
POST Validate Token: Validate Sign Embed User Token.

Common auth token API attributes¶

Common header attributes¶
Header Name	Values	Description
content-type	application/x-www-form-urlencoded	The resource media type.
x-request-id	String	A string value needed to track a given request

Create an Embed user token¶

Overview¶
Item	Value
HTTP Method	POST
Endpoint Operation	{apiAccessPoint}/api/gateway/adobesignauthservice/api/v1/token
Description	API to generate Sign Embed user Token.
Request Header	Auth API Headers
Request Object	Create token parameters
Response Object	Create token response
HTTP Status Code	200
Error Code	Generate Token - Error response

Request¶

Request Parameters¶
Parameter Name	Type	Description	Mandatory Fields by POST
client_id	String	IMS Client Id	Required
client_secret	String	IMS client secret	Required
grant_type	String	Auth Grant type	Required
subject_token	String	Unsigned JWT token of the user with email as payload. Refer below section for more details.	Required
subject_token_type	String	jwt: subject token type	Required
actor_token_type	String	access_token - actor Token type	Required
actor_token	String	Technical account token with mandatory scope: sign_oem_user_impersonate.	Required
scope	String	Scopes requested for the user access token. It must be a subset of the scopes that are available in the technical account token: openid, AdobeID, agreement_read, agreement_sign, agreement_write, agreement_send, agreement_retention, agreement_vault, sign_library_read, sign_library_write, sign_library_retention, widget_read, widget_write, workflow_read, workflow_write, sign_user_write, sign_user_read, sign_user_login, sign_webhook_read, sign_webhook_write, sign_webhook_retention The following scopes are not allowed for user access token: sign_account_read, sign_account_write, sign_oem_user_impersonate, ee.GROUP_SIGN_OEM, user_management_sdk	Required

Generating Subject Token

Subject identifies the principal for which the JWT token https://jwt.io/introduction belongs & access token is being minted by exchanging technical account token(actor token). Subject is scoped to be locally unique in context of authorization server identified by email. The jwt token belonging to this subject is termed subject_token which is an unsigned one and has “email” as claim.

Sample subject token (jwt)

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJlbWFpbCI6InN1YmplY3RfZW1haWxAc2lnbmVtYmVkcGFydG5lci5jb20ifQ.IOqyTkveGBDhfmanxttJnrcO-X8iYK1yyu7mU5Eb3dY

Payload:

{
  "email": "subject_email@signembedpartner.com"
}

For quick testing, copy this sample value and paste in jwt.io, Navigate to right hand payload section & update “email”. The jwt token at left side will be updated automatically. You can use this as subject token in token exchange api

How to generate programmatically?

You can use libraries https://jwt.io/libraries based on different languages to generate an unsigned subject token.

Sample Request parameters

client_id:<IMS_client_id>
client_secret:<client_secret>
grant_type:urn:ietf:params:oauth:grant-type:token-exchange
subject_token:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3R1c2VyZW1haWxAam9lc2Jpa2VzaG9wLmNvbSJ9.smfBPHgx68LXnwzKV_t2DurHyHT1aPlzFB8nxo_RiBY
subject_token_type:jwt
actor_token_type:access_token
actor_token:<technical_account_token>
scope:sign_webhook_retention,widget_write,workflow_read,agreement_send,agreement_sign,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write

Response¶

Response Parameters¶
Parameter Name	Type	Description
access_token	String	User Access Token value
token_type	String	Token type: `access_token`
expires_in	Long	Duration before expiry in seconds. The user token expires in 5 minutes.
scope	String	Scope available in the user access token.

Sample Response

{
    "access_token": <user_access_token>,
    "token_type": "access_token",
    "expires_in": 300,
    "scope": "sign_webhook_retention,openid,widget_write,workflow_read,agreement_send,agreement_sign,AdobeID,agreement_write,widget_read,sign_webhook_read,sign_user_write,agreement_read,agreement_retention,sign_user_read,sign_library_read,agreement_vault,sign_user_login,sign_webhook_write,sign_library_retention,sign_library_write,workflow_write"
}

Errors¶

Error codes for create an embed user token¶
HTTP Status Code	Error code	Message
400	BAD_REQUEST	The request provided is invalid.
400	INVALID_REQUEST	<required param name> is missing or invalid.
401	INVALID_AUTHENTICATING_TOKEN	actor_token is missing or invalid.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

Validate Embed User token¶

Overview¶
Item	Value
HTTP Method	POST
Endpoint Operation	{apiAccessPoint}/api/gateway/adobesignauthservice/api/v1/validate_token
Description	API to check the validity of the user token.
Request Header	Auth API Headers
Request Object	Validate token request
Response Object	Validate token Response
HTTP Status Code	200
Error Code	Error Response - Validate Token

Request¶

Request Parameters¶
Parameter Name	type	Description	Mandatory Fields by POST
client_id	String	IMS Client Id	Required
token	String	User access token	Required
type	String	Token type	Required

Sample Request

client_id:<IMS_client_id>
token:<user_access_token>
type:access_token

Response¶

Response Parameters¶
Parameter Name	Type	Description
valid	boolean	Returns if the token is valid or not.
expires_at	long	Token Expiry time in Epoc sec.

Sample Response

{
    "valid": true,
    "expires_at": 1673987741
}

Errors¶

Error codes for validate account¶
HTTP Status Code	Error code	Message
400	BAD_REQUEST	The request provided is invalid.
400	INVALID_REQUEST	<required param name> is missing or invalid.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

Common attributes¶

Account & User APIs: Common headers for Partner APIs¶
Header name	Value	Description
Authorization	Bearer <Technical Account Token>	Technical account token that is generated by the partner and tha Partner is onboarded before hand.
content-type	application/json	Media type of the resource.
x-request-id	String	A string value needed to track a given request.

Common headers for Auth token APIs¶
Header name	Value	Description
content-type	application/x-www-form-urlencoded	Media type of the resource.
x-request-id	String	A string value needed to track a given request.

Register APIs¶

Register APIs allow you to register your partner application with Acrobat Sign as part of the on-boarding process. Call this API directly with your technical account token for each technical account. You must also do this in the sandbox environment as well.

You can call the following API to register your partner application by directly using Technical account token:

Post Partners - Register the partner with Acrobat Sign

Create partner¶

Overview¶
Item	Value
HTTP Method	POST
Endpoint Operation	`{apiAccessPoint}/api/gateway/signembed/v1/partners`
Authentication/Authorization	Values: Valid Technical Account Token Mandatory scopes in token: `sign_user_write`, `sign_user_read`, `sign_account_write`, `sign_account_read`, `sign_oem_user_impersonate`
Description	API to register the Partner with Acrobat Sign. This would be called once as part of Partner onboarding.
Request Header	Partner APIs Common Headers
Request Object	RegisterPartnerRequest
Response Object	RegisterPartnerResponse
HTTP Status Code	201
Error Code Error Response	Error Response - Register Partner

Request¶

Register Partner request parameters¶
Parameter Name	Type	Default	Description	Requirement	Validations/Comments
name	String	NA	Identifiable partner name	Required
domains	List<String>	List of all the domains claimed/trusted by the partner org	List of domains claimed/trusted by the partner organization	Optional	domain regex validation Validated against the domains claimed/trusted by the partner org

Register partner sample request

{
"name":"Partner Name",
"domains": [
  "partnerdomain.com",
  "partnerdomain.us"
 ]
}

Response¶

Register partner response parameters¶
Parameter Name	Type	Default	Description
imsClientId	String		The client ID associated with the technical account
created	Date		Created date in ISO format
domains	List<String>		List of domains claimed/trusted by the partner
id	String		Id for the Partner.
modified	Date		Last modified date in ISO format
name	String		Identifiable partner name
orgGuid	String		Id of the IMS organization.
status	String	INACTIVE	Status of the Partner.
technicalAccountId	String		Technical account ID associated with the technical account.
updatedBy	String		Technical account ID associated with the technical account.

Register partner sample response

{
"id" :"1234",
"name":"Partner Name",
"orgGuid": "PartnerOrgGuid",
"imsClientId": "CliendIdOfTechnicalAccToken",
"technicalAccountId": "41AC2000634002540A49403A@techacct.adobe.com",
"status": "INACTIVE",
"updatedBy": "41AC2000634002540A49403A@techacct.adobe.com",
"created": "date",
"modified": "date",
"domains": [
  "partnerdomain.com",
  "partnerdomain.in"
]
}

Errors¶

Error codes for register partner response¶
HTTP Status Code	Error code	Message
400	INVALID_PARAMETER	The <param_name> value specified is invalid.
400	DOMAIN_NOT_ElIGIBLE	One or more domains are not allowed for the given partner.
400	INVALID_JSON	An invalid JSON was specified.
400	MISSING_REQUIRED_PARAM	Required parameter <param name> is missing.
401	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
403	MISSING_SCOPES	The token does not contain the required scopes.
404	ORG_DOMAINS_NOT_FOUND	Org does not have any owned or trusted federated domains.
409	TECHNICAL_ACCOUNT_ID_ALREADY_EXISTS	Partner already exists for this Technical Account Id.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

Account APIs¶

Call these APIs directly using a technical account token to create or update an account.

POST Account - To create a new account.

PUT Account - To update a new account.

GET Account - To fetch an account info.

GET All Accounts - To fetch all accounts in a channel.

Common account API header attributes¶

Common header attributes¶
Header Name	Values	Description
Authorization	Bearer <Technical Account Token>	Technical account token that is generated by the partner and the Partner is onboarded beforehand.
content-type	application/json	The resource media type.
x-request-id	String	A string value needed to track a given request

Create Account¶

Overview¶
Item	Value
HTTP Method	POST
Endpoint Operation	{apiAccessPoint}/api/gateway/signembed/v1/accounts
Authentication/ Authorization	Valid technical account token. Required scopes in token: `sign_account_write`.
Audience	Partner will call this API to create new accounts for their customers.
Request Header	Partner APIs Common Headers
Request Object	AccountProvisionRequest
Response Object	AccountProvisionResponse
HTTP Status Code	201
Error Code	Error Response: Create Account

Request¶

Account create-update request parameters¶
Parameter Name	Type	Default	Description	Needed in POST/PUT	Updatable by PUT
id	String	NA	Account ID of the Account	Required and Permitted only in PUT	Immutable
name	String	NA	Name of the account. The name must only include numbers and letters. No special characters or spaces are allowed.	Required	mutable
company	String	“”	Name of the company	Optional	mutable
consumables	List<Consumable>	[ ]	List of Consumables	Optional	mutable
countryCode	String	NA	Target Country for Account Provisioning. Ex US, FR, GB	Required	Immutable

Consumable¶
Parameter Name	Type	Default Value	Description	Needed in POST/PUT	Updatable by PUT
type	String	NA	Name of consumable supported in Embed Accounts. KBA_ANNUAL PHONE_AUTH_ANNUAL SEAT	Required	mutable
attributes	Object	N/A	Properties for each consumable type	Required	mutable

Sample Account Provisioning Request

{
    "name": "SignEmbedTestAccount",
    "company": "Sign Embed Test Account",
    "countryCode": "US",
    "consumables":[
        {
            "type": "SEATS",
            "attributes": {
                "cap": 1
            }
        },
        {
            "type": "PHONE_AUTH",
            "attributes": {
                "cap": 1
            }
        },
        {
            "type": "KBA",
            "attributes": {
                "cap": 1
            }
        }
    ]
}

Account creation response object¶

Parameter Name	REST Object	Description
accountId	String	Account ID

Sample account creation response

{
  "accountId" : "2aabnucbm3xsdfweldvwporqvjqzxdkjorbikaifuiwufwihs*"
}

Errors¶

Error codes for AccountCreateErrorResponse¶
HTTP Status Code	Error code	Message
400	MISSING_REQUIRED_PARAMS	Required parameter <param name> is missing.
400	INVALID_JSON	An invalid JSON was specified.
400	INVALID_PARAMETER	The <param_name> value specified is invalid.
401	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
403	MISSING_SCOPES	The token does not contain the required scopes.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
409	ACCOUNT_ALREADY_EXISTS	Account with this name already exists.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.
500	ACCOUNT_COULD_NOT_BE_CONFIGURED	Account with accountId {account id} could not be configured properly.

Update Account¶

Overview¶
Item	Value
HTTP Method	PUT
Endpoint Operation	{apiAccessPoint}/api/gateway/signembed/v1/accounts/<accountId>
Authentication/ Authorization	Valid technical account token. Required scopes: `sign_account_write`
Audience	Partner will call this API to update existing Embed account.
Request Header	Partner APIs Common Headers
Request Object	AccountUpdateRequest
Response Object	No Content
HTTP Status Code	204
Error Code	ErrorCodes - Update Account

Request¶

Account update request parameters

Sample Account Update Request

{
    "id":"accountid",
    "name": "SignEmbedTestAccountUpdated",
    "company": "Sign Embed Test Account Updated",
    "consumables":[
        {
            "type": "SEATS",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "PHONE_AUTH",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "KBA",
            "attributes": {
                "cap": 10
            }
        }
    ]
}

Errors¶

Error codes for AccountUpdateErrorResponse¶
HTTP Status Code	Error code	Message
400	MISSING_REQUIRED_PARAMS	Missing required parameters <required param name>.
400	INVALID_PARAMETER	The <param_name> value specified is invalid.
400	INVALID_INPUT	An invalid input is provided.
400	INVALID_JSON	An invalid JSON was specified.
401	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
403	MISSING_SCOPES	The token does not contain the required scopes.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation.
404	ACCOUNT_NOT_FOUND	Account does not exist.
409	ACCOUNT_ALREADY_EXISTS	An account with this name already exists.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

Get Account¶

Overview¶
Item	Value
HTTP Method	GET
Endpoint Operation	{apiAccessPoint}/api/gateway/signembed/v1/accounts/<accountId>
Authorization	Valid technical account token. Required Scopes in token: sign_account_read
Audience	Partner will call this API to fetch account details for their customers.
Request Header	Partner APIs Common Headers
Request Object
Response Object	GetAccountResponse
HTTP Status Code	200
Error Code	ErrorCodes - get Account

Response¶

Response Object GetAccountResponse¶
Parameter Name	Type	Description
id	String	account ID
name	String	Name of the account
company	String	Name of the company
consumables	List<Consumable>	LList of Consumables with values. For example, KBA, PHONE_AUTH, and SEATS.
countryCode	String	Target Country for Account Provisioning. Ex US, FR, GB
created	Date	Account created date in ISO format.

Sample account creation GetAccountResponse

{
    "id":"accountId"
    "name": "SignEmbedTestAccountUpdated",
    "company": "Sign Embed Test Account Updated",
    "consumables":[
        {
            "type": "SEATS",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "PHONE_AUTH",
            "attributes": {
                "cap": 10
            }
        },
        {
            "type": "KBA",
            "attributes": {
                "cap": 10
            }
        }
    ],
    "created": "2023-01-17T12:27:08Z"
}

Errors¶

Error codes for AccountGetErrorResponse¶
HTTP Status Code	Error code	Message
400	INVALID_INPUT	An invalid input is provided.
401	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
403	MISSING_SCOPES	The token does not contain the required scopes.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation.
404	ACCOUNT_NOT_FOUND	Account does not exist.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

Get All Accounts¶

Overview¶
Item	Value
HTTP Method	GET
Endpoint Operation	/v1/accounts?isLegacy={true/false}&pagesSize={}&pageNumber={}
Authorization	Valid Technical Account Token. Mandatory Scope in token - sign_account_read
Audience	Partner will call this API to fetch paginated list of accounts for all their customers.
Request Header	Partner APIs Common Headers
Request Object	GetAccountsResponse
HTTP Status Code	200
Error Code	ErrorCodes - get Account

Query Params¶
Parameter Name	Type	Description	Needed	Data Range
pageNumber	Integer	pageNumber to navigate through pages	Optional	default:0 If pageNumber less than 0, throw INVALID_PARAMETER exception
pageSize	Integer	pageSize to limit the number of records that will be fetched.	Optional	default:20 max:100 If pageSize less than 1, throw INVALID_PARAMETER exception If pageSize given is more than 100, throw PAGE_SIZE_LIMIT_EXCEEDED exception
isLegacy	boolean	Return legacy accounts that are on old Sign Embed Models.	Optional	default:false If isLegacy value provided is not a boolean, throw INVALID_PARAMETER exception

Response¶

Response Object GetAccountResponse¶
Parameter Name	Type	Description
accountList	List<Account>	List of Account details.

Account¶
Parameter Name	Type	Description
accountId	String	Secure Account id to identify an Account
name	String	Name of the account
created	Date	Account created date in ISO format.

Sample GetAccountsResponse

{
"accountList": [
  {
    "accountId": "secureAccountId1234",
    "name": "Joes Bike Shop",
    "created": "2023-01-17T12:27:08Z"
  },
  {
    "accountId": "secureAccountId2345",
    "name": "Acme Corp",
    "created": "2023-01-17T12:27:08Z"
  }
]
}

Error¶

Error Response for Get Accounts¶
HTTP Status Code	Error code	Message
400	INVALID_PARAMETER	The pageSize specified must be greater than or equal to 1.
400	PAGE_SIZE_LIMIT_EXCEEDED	Page size has exceeded the maximum length of 100.
401	INVALID_TOKEN	The token provided is invalid or expired.
401	MISSING_SCOPES	The token does not contain the required scopes.
401	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

User APIs¶

Call these APIs directly using a technical account token to create or update an account and users.

POST User - To add a user to an account.

PUT User - To update a user.

GET User - To fetch user info.

Common user API header attributes¶

Common user header attributes are identical to the Account APIs.

POST user¶

Overview¶
Item	Value
HTTP Method	POST
Endpoint Operation	{apiAccessPoint}/api/gateway/signembed/v1/users
Authentication/ Authorization	Valid Technical Account Token or Sign Embed user Admin token. RMandatory Scopes required in token: `sign_user_write`.
Audience	Partner will call this API to add a new user to their customer’s account.
Request Header	Partner APIs Common Headers
Request Object	Create User Request
Response Object	Create User Response
HTTP Status Code	201
Error Code	ErrorCodes - Create User

Request¶

Create-update user request parameters¶
Parameter Name	Type	Default Value	Description	Mandatory Fields by POST/PUT	Update Allowed via PUT
id	String		Id to uniquely identify a user.	Required and permitted only in a PUT call	Immutable
email	String		Email of the user.	Required	Mutable
emailAlias	String		Email alias with customer domain displayed in the audit report.	Optional	Mutable
firstName	String		First Name of the User.	Required	Mutable
lastName	String		Last Name of the User.	Required	Mutable
accountId	String		Account ID where the user needs to be added.	Required. Optional if User token is used for Authentication.	Immutable
status	String	ACTIVE	Status of the user.	Optional. Not supported in POST. Defaults to ACTIVE.	Mutable
initials	String	“”	Initials of the user name.	Optional	Mutable
phone	String	“”	Phone number of the user.	Optional	Mutable
title	String	“”	Job Title of the user.	Optional	Mutable
company	String	“”	Name of the company.	Optional	Mutable
roles	List<String>		User roles Values: ACCOUNT_ADMIN, PRIVACY_ADMI	Optional	Mutable

Sample user creation request body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe_joesbikeshop@partnerdomain.com",
  "emailAlias":"johndoe@joesbikeshop.com",
  "accountId": "CBJCHBCAABAAyQTAasUNZ-lxF0gKyvZUaB6rQ3UfrKr1",
  "status": "ACTIVE",
  "initials": "JD",
  "phone": "12345678111",
  "title": "SDE",
  "company": "Joes Bike Shop",
  "roles": [
    "ACCOUNT_ADMIN",
    "PRIVACY_ADMIN"
  ]
}

Response¶

Create User Response

Parameter Name	Type	Description
userId	String	User ID

Error¶

Error codes for UserCreateErrorResponse¶
HTTP Status Code	Error code	Message
400	MISSING_REQUIRED_PARAMS	Required parameter <param name> is missing.
400	INVALID_PARAMETER	The <param_name> value specified is invalid.
401	INVALID_ACCESS_TOKEN	Token provided is invalid or has expired.
403	MISSING_SCOPES	The token does not contain the required scopes.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	MAXIMUM_USERS_FOR_ACCOUNT_LIMIT_EXCEEDED	Maximum active user limit reached for the account.
403	PERMISSION_DENIED	The API caller does not have permission to execute this operation.
404	ACCOUNT_NOT_FOUND	Account does not exist.
409	USER_ALREADY_EXISTS	User with this email already exists.
500	USER_COULD_NOT_BE_CREATED	User could not be created.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

PUT User¶

Overview¶
Item	Value
HTTP Method	PUT
Endpoint Operation	{apiAccessPoint}/api/gateway/signembed/v1/users/<userId>
Authentication/ Authorization	Valid Technical Account Token or Admin User Token. Mandator scopes in token: `sign_user_write`.
Audience	Partner will call this API to update the user attributes in the customer’s Account.
Request Header	Partner APIs Common Headers
Request Object	UpdateUserRequest
Response Object	No Content
HTTP Status Code	204
Error Code	ErrorCode - Update User

Request¶

Sample update user request body

{
  "id":"userId",
  "firstName": "John",
  "lastName": "Doe",
  "email": "johndoe_joesbikeshop@partnerdomain.com",
  "emailAlias":"johndoe@joesbikeshop.com",
  "accountId": "CBJCHBCAABAAyQTAasUNZ-lxF0gKyvZUaB6rQ3UfrKr1",
  "status": "ACTIVE",
  "initials": "JD",
  "phone": "12345678111",
  "title": "SDE",
  "company": "Joes Bike Shop",
  "roles": [
    "ACCOUNT_ADMIN",
    "PRIVACY_ADMIN"
  ]
}

Errors¶

Error codes for UserUpdateErrorResponse¶
HTTP Status Code	Error code	Message
400	MISSING_REQUIRED_PARAMS	Required parameter <param name> is missing.
400	INVALID_PARAMETER	The <param_name> value specified is invalid.
400	INVALID_JSON	An invalid JSON was specified.
400	INVALID_INPUT	An invalid input is provided.
401	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
403	MISSING_SCOPES	The token does not contain the required scopes.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation.
404	ACCOUNT_NOT_FOUND	Account does not exist.
404	USER_NOT_FOUND	User does not exist.
409	USER_ALREADY_EXISTS	User with this email already exists.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.
500	USER_COULD_NOT_BE_UPDATED	User could not be updated.

GET User¶

Overview¶
Item	Value
HTTP Method	GET
Endpoint Operation	/api/gateway/signembed/v1/users/<userId>
Authorization	Valid Technical Account Token or Admin User Token. Mandatory scopes in token: `sign_user_read`.
Audience	Partner will call this API to fetch details of a user.
Request Header	Partner APIs Common Headers
Request Object
Response Object	Get User Response
HTTP Status Code	200
Error Code	ErrorCodes - Get User

Response¶

Get user response attributes¶
Parameter Name	Type	Description
id	String	Id to uniquely identify a user.
email	String	Email of the user.
emailAlias	String	Email alias with customer domain displayed in the audit report.
firstName	String	First Name of User.
lastName	String	Last Name of the User.
accountId	String	Account ID of the user’s account.
status	String	Status of the user.
initials	String	Initials of the user name.
phone	String	Phone number of the user.
title	String	Job Title of the user.
company	String	Name of the company.
roles	List<String>	ACCOUNT_ADMIN, PRIVACY_ADMIN: User roles values.
created	Date	User creation date in ISO format.

Sample get user response

{
    "id":"userId",
    "email": "johndoe_joesbikeshop@partnerdomain.com",
    "emailAlias":"johndoe@joesbikeshop.com",
    "firstName": "John",
    "lastName": "Doe",
    "accountId": "CBJCHBCAABAAuchiIJRXpJ-IyaFxK6QvRPrLEahWSuRW",
    "status": "ACTIVE",
    "initials": "JD",
    "company": "Joes Bike Shop",
    "roles": [
        "ACCOUNT_ADMIN",
        "PRIVACY_ADMIN"
    ],
    "created":"2023-01-17T12:27:08Z"
}

Errors¶

Error codes for UserGetErrorResponse¶
HTTP Status Code	Error code	Message
400	INVALID_PARAMETER	The <param_name> value specified is invalid.
400	INVALID_ACCESS_TOKEN	Access token provided is invalid or has expired.
403	MISSING_SCOPES	TThe token does not contain the required scopes.
403	AUTHENTICATION_FAILED	Partner is not onboarded successfully.
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation.
404	USER_NOT_FOUND	User does not exist.
500	INTERNAL_SERVER_ERROR	Some miscellaneous error has occurred.

Consumables APIs¶

Adobe Acrobat Sign supports a variety of authentication methods to ensure the security and integrity of electronic signatures. These methods range from simple, single-factor authentication to more complex, multi-factor authentication options - ensuring that organizations can manage and budget their use according to their security needs and compliance requirements, while also providing flexibility to choose the appropriate level of authentication for different types of transactions.

Phone Authentication: A six-digit code is sent to the recipient’s phone via SMS or voice call, which must be entered to view the agreement. For details, check Phone authentication.
Knowledge-Based Authentication (KBA): This high-level authentication method is used mainly in financial institutions. It involves answering personal questions derived from public databases and is only available for recipients in the US. For details, check Knowledge-based authentication.
Government ID Authentication: This method requires the recipient to provide an image of a government-issued ID and a selfie for verification. For details, check Government ID.

Note

Add-ons and transactions are referred to as “consumables” because they are resources that are used up or consumed as they are utilized. Each time a transaction is initiated, such as sending an electronic document for signature, it is considered consumed and is deducted from the user’s available transaction quota. Similarly, authentication services like Knowledge-Based Authentication or Phone Authentication are also treated as consumables, as they are used up on a per-recipient basis when employed in the signing process. This means that each time a recipient uses one of these methods, it counts against the total number of transactions available to the sender, which must be replenished as needed.

Consumables summary on integration¶

	Value
HTTP Method	GET
Endpoint Operation	/v1/partners/me/consumableSummary
Authentication/ Authorization	Valid technical account token with ee.sign_group_oem
Audience	Partner will call this API to fetch count of consumables consumed within a given date range
Request Header	Partner APIs Common Headers
Query Params	FilterQueryParams
Response Object	ConsumableSummaryResponse
HTTP Status Code	200
Error Code	CommonErrorResponse

FilterRequestParams

Parameter Name	Type	Description	Required	Value Range
startDate	DateTime	DateTime in ISO-8601 format with UTC timezone	Yes	startDate should not be earlier than 2025-01-01T00:00:00Z
endDate	DateTime	DateTime in ISO-8601 format with UTC timezone	Yes	endDate should be greater than startDate but not more than 31 days from startDate. Ex: 2025-01-15T00:00:00Z

ConsumableSummaryResponse

Type	Description	Default Value
List<ConsumableSummary>	List of ConsumableSummary	[]

ConsumableSummary

Parameter Name	Type	Description	Sample Value
type	String	Type of consumables	Ex: TXN, PHONE_AUTH
count	Long	Count of consumable consumed within given range	Ex: 100

ConsumableSummaryResponse

{
  "consumableSummary": [
    {
     "type": "KBA",
     "count": 1
    },
    {
     "type": "PHONE_AUTH",
     "count": 2
    }
  ]
}

Get consumables summary on account level¶

	Value
HTTP Method	GET
Endpoint Operation	/v1/accounts/{account_id}/consumableSummary
Authentication/ Authorization	Valid Technical Account Token Mandatory Scopes in token - sign_account_read, agreement_read
Audience	Partner will call this API to fetch details of consumables (agreements, add-ons) consumed within a given date range for a given account
Request Header	Partner APIs Common Headers
Query Params	AccountFilterQueryParams
Response Object	ConsumableSummaryDetailsResponse
HTTP Status Code	200
Error Code	CommonErrorResponse

ConsumableSummaryResponse

{
  "consumableSummary": [
      {
        "type": "KBA",
        "count": 1
      },
      {
        "type": "PHONE_AUTH",
        "count": 2
      }
  ]
}

Get consumables summary details on account level¶

	Value
HTTP Method	GET
Endpoint Operation	/v1/accounts/{account_id}/consumableSummaryDetails
Authentication/ Authorization	Valid Technical Account Token Mandatory Scopes in token - sign_account_read, agreement_read
Audience	Partner will call this API to fetch details of consumables (agreements, add-ons) consumed within a given date range for a given account
Request Header	Partner APIs Common Headers
Query Params	AccountFilterQueryParams
Response Object	ConsumableSummaryDetailsResponse
HTTP Status Code	200
Error Code	CommonErrorResponse

AccountFilterQueryParams

Parameter Name	Type	Description	Required	Value Range
startDate	DateTime	DateTime in ISO-8601 format with UTC timezone	Yes	startDate should not be earlier than 2025-01-01T00:00:00Z
endDate	DateTime	DateTime in ISO-8601 format with UTC timezone	Yes	endDate should be greater than startDate but not more than 31 days from startDate. Ex: 2025-01-15T00:00:00Z
pageSize	Integer	Count of records to be returned per specific call	No
cursor	String	Reference to get next set of records with given pageSize. This is used to navigate through the pages. If not provided, returns the first page.	No

ConsumableSummaryDetailsResponse

Type	Description	Default Value
List<ConsumableSummaryDetails>	List of ConsumableSummaryDetails	[ ]

ConsumableSummaryDetails

Parameter Name	Type	Description	Sample Value
agreementId	String	Secure agreement identifier	Ex: CBJCHBCAABAA-N0tAR3aLID-u4R5RO
createdDate	DateTime	Agreement created time recorded in the system in UTC format
addonDetails	List<AddonDetails>	List of secondary consumables like add-ons with their count

AddonDetails

Parameter Name

Type

Description

Sample Value

type

String

Name of consumable

Ex: PHONE_AUTH, KBA

count

Long

Count of consumable consumed with an agreement

Ex: 100

ConsumptionResponseReportResponseItemDetail

{
  "page": {
    "nextCursor": "xyzjbjdbjb"
  },
  "agreements": [
    {
      "id": "CBJCHBCAABAA-N0tAR3aLID-u4R5RO",
      "createdDate": 2025-01-10T00:00:15Z,
      "addonDetails": [
        {
          "type": "KBA",
          "count": 1
        },
        {
          "type": "PHONE_AUTH",
          "count": 2
        }
      ]
    }
  ]
}

CommonErrorResponse¶

HTTP Code	Error Code	Message
400	BAD_REQUEST	The request provided is invalid
403	PERMISSION_DENIED	The API caller does not have the permission to execute this operation
429	TOO_MANY_REQUESTS	The request rate limit has reached
500	MISC_SERVER_ERROR	Some miscellaneous error has occurred.

Partner APIs Common Headers¶

Header Name	Values	Description
Authorization	Bearer <Technical Account Token>	Technical account token that is generated by the partner
content-type	application/json	Media type of the resource
x-request-id	String	A unique string value needed to track a given request