# 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.             |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sign.enadocapp.com/evia-sign-api/v2/creating-a-signature-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.