# 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

<mark style="color:green;">`POST`</mark> `/_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.

```json
{
  "Email": "eviasign@gmail.com",
  "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 `1`for parallel signing.                                                |
| `PrivateMessage` | `string`  | Optional | A message visible only to this signatory. Useful for instructions.                                                                    |
| `SignatoryType`  | `integer` | ✅ Yes    | <p>Role in the workflow: </p><p><code>1 = Signer</code>, </p><p><code>2 = Approver</code>, </p><p><code>3 = CC (copy only)</code></p> |
| `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                         | <p>OTP delivery methods:<br><code>1</code> = Email OTP<br><code>2</code> = SMS OTP </p><p><code>3</code> =  AccessCode</p><p><code>4</code> =  Email & SMS OTP</p> |
| `MobileNumber` | `string`  | Required if `Type=2 & Type=4` | This is required if SMS OTP is enabled.                                                                                                                            |

{% hint style="info" %}
If `IsRequired` is `true` and `Type=2 or Type=4` is selected, the **MobileNumber** must be valid. If missing, the request will fail.
{% endhint %}

### Successful Response

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

```json
{
  "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.                     |