> For the complete documentation index, see [llms.txt](https://docs.sign.enadocapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sign.enadocapp.com/evia-sign-api/v2/creating-a-signature-request.md).

# Creating a Signature Request

AuditDetails object ✅ Yes Captures metadata about who initiated the request

Connections array Optional Reserved for internal routing or grouping logicAuditDetails object ✅ Yes Captures metadata about who initiated the request

Connections array Optional Reserved for internal routing or grouping logicAfter successfully uploading a document, the next step is to initiate a signature request using the `documentToken` returned by the upload step. 

## Signature Request URL

<mark style="color:yellow;">`POST`</mark> `/_apis/sign/api/v2/requests?type=0`

This request URL is used to initialize a **Type 0 (Skeleton)** signature request in Evia Sign. It creates a signing workflow that can be configured further by adding signatories and stamps before being sent.

### What This Does

This API call **creates a new signature request** using **type=0**, also known as the **Skeleton workflow**.

* It sets up the signing request with a document, title, and audit metadata.
* **No signers or stamps are added yet** — those will be configured in follow-up API calls.
* This is ideal for automated flows where signer data is dynamic or added later.

| Type | Name                        | Description                                                            |
| ---- | --------------------------- | ---------------------------------------------------------------------- |
| `0`  | Skeleton (Automation / RPA) | Step-by-step creation using separate calls for signatories and stamps. |

### Required Headers

These headers must be included to authenticate and properly format the request.

| Header          | Required | Description                                 |
| --------------- | -------- | ------------------------------------------- |
| `Authorization` | ✅ Yes    | Bearer token (OAuth 2.0) for authentication |
| `Content-Type`  | ✅ Yes    | Must be `application/json`                  |

### Required Fields

Type 0 (Skeleton – Automation/RPA)

For workflows where you want full control over the process — add signers, stamps, and placements **after** creating the request.

You initialize the signing process with just the document and metadata. Callback settings are optional but recommended to stay notified about status changes

| Field                        | Required | Type       | Description                                                                  |
| ---------------------------- | -------- | ---------- | ---------------------------------------------------------------------------- |
| `Title`                      | ✅ Yes    | `string`   | The name of the signature request. Appears in the signer UI and email.       |
| `Message`                    | ✅ Yes    | `string`   | A short message shown to the signers (e.g., instructions or context).        |
| `Documents`                  | ✅ Yes    | `string[]` | List of uploaded `documentTokens`. At least one is required.                 |
| `CallbackUrl`                | Optional | `string`   | Publicly accessible URL to receive webhook notifications for events.         |
| `CallbackTypes`              | Optional | `int[]`    | List of event codes that determine which webhook events should be triggered. |
| `CompletedDocumentsAttached` | Optional | `boolean`  | If `true`, signed PDFs will be attached in the final webhook callback.       |
| `AuditDetails`               | ✅ Yes    | `object`   | Captures metadata about who initiated the request                            |
| `Connections`                | Optional | `array`    | Metadata used for audit trails and tracking. See below.                      |

Define which events you want Evia Sign to notify your system about by setting the `CallbackTypes`

| Code | Event Triggered                                                   |
| ---- | ----------------------------------------------------------------- |
| `0`  | **All Events** — shorthand to receive notifications for all below |
| `1`  | Request received                                                  |
| `2`  | Signatory completed their signature                               |
| `3`  | Entire signing process completed                                  |

### AuditDetails Breakdown

This block improves auditability by storing who created the request and from what environment.

| Subfield          | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `AuthorType`      | Usually `1` = Admin or system user.                                     |
| `AuthorIPAddress` | IP address of the user or system initiating the request.                |
| `Device`          | Human-readable string describing the environment (device, OS, browser). |

### Example Payload

```json
{
  "Title": "Contract Agreement",
  "Message": "Please review and sign.",
  "Documents": [
    "abc123-token"
  ],
  "CallbackUrl": "https://yourdomain.com/webhooks/evia-sign",
  "CallbackTypes": [1],
  "CompletedDocumentsAttached": true,
  "AuditDetails": {
    "AuthorType": 1,
    "AuthorIPAddress": "",
    "Device": "Device Type: desktop - OS: Windows - Browser: Chrome (v131.0)"
  },
  "Connections": []
}
```

### Successful Response

When a signature request is successfully created,Evia Sign returns the following response:

```json
{
  "requestId": "abc123-request-id"
}
```

### Field Explanation

| Field       | Type     | Description                                                                                                                                                                                       |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId` | `string` | A unique identifier for the newly created signature request. This ID is required for all subsequent operations such as adding signers, assigning stamps, tracking status, or sending the request. |

### Possible Errors and How to Handle Them

| Status Code | Error Message            | Explanation                                                                                             |
| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| `400`       | Bad Request              | The request body is invalid or missing required fields such as `Title`, `Documents`, or `AuditDetails`. |
| `401`       | Unauthorized             | The access token is missing, expired, or incorrect. Ensure a valid Bearer token is included.            |
| `404`       | Document Token Not Found | The `documentToken` provided in the `Documents` array does not exist or is no longer valid.             |