Add Signatory to a Signature Request

This operation allows you to add a participant (signer, approver or cc) to a signature request that was created using type=0 (skeleton mode). Each person you add to the request can be configured with a custom role, signing order, color label, and OTP authentication method.

You can call this endpoint multiple times to build out your workflow with as many participants as needed, assigning them in sequential or parallel flows.

Request URL

POST /_apis/sign/api/v2/requests/requestId/signatories

Defines the request URL for adding a signatory to a request.

Required Headers

Headers required to authenticate the API call and send data in the correct format.

Header	Required	Description
Authorization	✅ Yes	Bearer token generated from the OAuth 2.0 flow. Used to authenticate the API caller.
Content-Type	✅ Yes	Must be application/json. Ensures the body is parsed correctly.

Request Body Schema

Use this JSON structure to define the signatory you’re adding to the signature request.

{
  "Email": "[email protected]",
  "Name": "Signer User",
  "Order": 1,
  "PrivateMessage": "Sample private message",
  "SignatoryType": 1,
  "Color": "#7c95f4",
  "OTP": {
    "IsRequired": true,
    "AccessCode": "",
    "Type": 2,
    "MobileNumber": ""
  }
}

Field-by-Field Explanation

Explanation of each field in the request body.

Field	Type	Required	Description
Email	string	✅ Yes	Signatory's email. Used for communication and signing access.
Name	string	✅ Yes	Full name of the signatory. Displayed in the UI and audit trail.
Order	integer	✅ Yes	Defines the sequence of signing. Lower order signs first. Use 1for parallel signing.
PrivateMessage	string	Optional	A message visible only to this signatory. Useful for instructions.
SignatoryType	integer	✅ Yes	Role in the workflow: 1 = Signer, 2 = Approver, 3 = CC (copy only)
Color	string	Optional	UI tag color (hex) to visually represent the user (no impact on final doc).

---

Role of the User in the Request

Defines the level of interaction each signatory will have with the document.

Value	Role	Description
1	Signer	Can view and apply their signature to the document.
2	Approver	Can review and approve but cannot sign.
3	CC	Receives a final signed copy but cannot take action.

OTP (One-Time Password) Settings

You can add an extra layer of identity verification using Email or SMS-based OTP. This is defined inside the OTP object.

Field	Type	Required	Description
IsRequired	boolean	✅ Yes	Set to true if OTP is required before signing.
AccessCode	string	Optional	A custom passcode (if required by your compliance policy). Usually left blank.
Type	integer	✅ Yes	OTP delivery methods: 1 = Email OTP 2 = SMS OTP 3 = AccessCode 4 = Email & SMS OTP
MobileNumber	string	Required if Type=2 & Type=4	This is required if SMS OTP is enabled.

If IsRequired is true and Type=2 or Type=4 is selected, the MobileNumber must be valid. If missing, the request will fail.

Successful Response

When a signatory is successfully added to a request, the API returns the following response:

{
  "requestId": "abc123-request-id",
  "signatoryId": "xyz789-signatory-id"
}

Field Descriptions

Field	Type	Description
requestId	string	The unique ID of the signature request the signatory was added to. This matches the request you created using POST /requests?type=0.
signatoryId	string	A unique identifier for the newly added signatory. You'll need this ID to assign stamp placeholders, position stamps on the document, and track the signatory’s progress.

Possible Errors and How to Handle Them

When adding a signatory to a request, the API may return standard error responses depending on the validity of the input or authentication state. Below are the most common error scenarios and how to interpret them:

Status Code	Error Message	Explanation
400	Bad Request	The request body is missing required fields or is improperly formatted.
401	Unauthorized	The access token is missing, expired, or invalid.
404	Request ID not found	The requestId does not exist or has been deleted.