> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Signature

> Create and send a signature envelope for a task's signature step

## Endpoint

```
POST /tasks/{task_id}/initiate_sign
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Path Parameters

| Parameter | Type    | Required | Description                    |
| --------- | ------- | -------- | ------------------------------ |
| `task_id` | integer | Yes      | Unique identifier for the task |

## Request Body

The request body must be a JSON object with the following fields:

### Required Fields

| Field         | Type   | Description                  |
| ------------- | ------ | ---------------------------- |
| `step_run_id` | string | ID of the signature step run |

### Optional Fields

| Field                      | Type    | Description                                                                                                         |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `auto_send`                | boolean | Create the envelope and send it when `true`. Defaults to `true`                                                     |
| `custom_recipients`        | boolean | Upsert the provided `recipients` before creating the envelope. Defaults to `false`                                  |
| `recipients`               | array   | Recipients to upsert. See [Recipient Object](#recipient-object-fields). Required when `custom_recipients` is `true` |
| `replace_signing_document` | boolean | Replace the signing document before creating the envelope. Defaults to `false`                                      |
| `signing_document`         | object  | New signing document. See [File Object](#file-object-fields). Required when `replace_signing_document` is `true`    |
| `create_envelope_url`      | boolean | Return the coordinator envelope URL (edit or view) in the response. Defaults to `false`                             |

### Recipient Object Fields

| Field            | Type   | Description                                                |
| ---------------- | ------ | ---------------------------------------------------------- |
| `recipient_type` | string | Recipient role: `signer` or `viewer`. Defaults to `signer` |
| `email`          | string | Recipient email address (required for each recipient)      |
| `name`           | string | Recipient name (required for each recipient)               |

### File Object Fields

| Field            | Type   | Description                   |
| ---------------- | ------ | ----------------------------- |
| `filename`       | string | Filename, e.g. `contract.pdf` |
| `base64_content` | string | Base64-encoded file content   |

<Warning>
  Conditional rules enforced by the API:

  * `recipients` may only be provided when `custom_recipients` is `true`, and each recipient must include both `email` and `name`.
  * `signing_document` is required when `replace_signing_document` is `true`, and may only be provided when `replace_signing_document` is `true`.

  Violating these returns a `422 Validation Error`.
</Warning>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.chamelio.ai/tasks/12345/initiate_sign" \
    -H "X-API-Key: ca_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "step_run_id": "sr_abc123",
      "auto_send": true,
      "custom_recipients": true,
      "recipients": [
        {
          "recipient_type": "signer",
          "email": "john.doe@example.com",
          "name": "John Doe"
        }
      ],
      "create_envelope_url": true
    }'
  ```

  ```python Python theme={null}
  import requests

  task_id = 12345

  url = f"https://platform.chamelio.ai/tasks/{task_id}/initiate_sign"
  headers = {
      "X-API-Key": "ca_your_api_key_here",
      "Content-Type": "application/json"
  }

  payload = {
      "step_run_id": "sr_abc123",
      "auto_send": True,
      "custom_recipients": True,
      "recipients": [
          {
              "recipient_type": "signer",
              "email": "john.doe@example.com",
              "name": "John Doe"
          }
      ],
      "create_envelope_url": True
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const taskId = 12345;

  const response = await fetch(
    `https://platform.chamelio.ai/tasks/${taskId}/initiate_sign`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'ca_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        step_run_id: 'sr_abc123',
        auto_send: true,
        custom_recipients: true,
        recipients: [
          {
            recipient_type: 'signer',
            email: 'john.doe@example.com',
            name: 'John Doe'
          }
        ],
        create_envelope_url: true
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "task_id": 12345,
  "envelope_id": "env_789xyz",
  "envelope_url": {
    "url_type": "view",
    "url": "https://app.docusign.com/..."
  },
  "message": "Signature process initiated successfully"
}
```

### Response Fields

| Field          | Type           | Description                                                                           |
| -------------- | -------------- | ------------------------------------------------------------------------------------- |
| `task_id`      | integer        | ID of the task                                                                        |
| `envelope_id`  | string or null | Provider envelope identifier, if an envelope was created                              |
| `envelope_url` | object or null | Coordinator envelope URL (only present when `create_envelope_url=true` and available) |
| `message`      | string         | Success confirmation message                                                          |

### Envelope URL Object Fields

| Field      | Type   | Description                   |
| ---------- | ------ | ----------------------------- |
| `url_type` | string | Type of URL: `edit` or `view` |
| `url`      | string | Coordinator envelope URL      |

## Error Responses

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

Returned when the task doesn't exist or you don't have access to it.

```json theme={null}
{
  "detail": "Task not found"
}
```

### 409 Conflict

Returned when the task is not at a signature step or signature has already been initiated.

```json theme={null}
{
  "detail": "Task is not at a signature step"
}
```

### 422 Validation Error

Returned when the request body is invalid (for example, `recipients` provided without `custom_recipients=true`, or `signing_document` missing when `replace_signing_document=true`).

```json theme={null}
{
  "detail": [
    {
      "loc": ["body"],
      "msg": "recipients are required when custom_recipients is true",
      "type": "value_error"
    }
  ]
}
```

### 500 Internal Server Error

Returned when signature initiation fails due to a server error.

```json theme={null}
{
  "detail": "Failed to initiate signature"
}
```

## Notes

<Tip>
  Call [Get Signature Details](/api-reference/endpoint/tasks/signature-details) first to read the step status and existing recipients, and to obtain the `step_run_id`.
</Tip>

<Info>
  By default (`custom_recipients=false`), the envelope uses the recipients already configured on the signature step. Set `custom_recipients=true` and supply `recipients` to upsert recipients before sending. Set `create_envelope_url=true` to receive a coordinator URL for editing or viewing the envelope.
</Info>

<Warning>
  Set `replace_signing_document=true` and include `signing_document` only when you need to swap the document before sending. Otherwise the document already on the step is used.
</Warning>

## Use Cases

This endpoint is useful for:

* **Contract execution** - Create and send a signature envelope after review and approval
* **Custom signing workflows** - Upsert recipients or replace the signing document at send time
* **Coordinator handoff** - Return an envelope URL so a coordinator can edit or view the envelope
* **Multi-party agreements** - Configure signers and viewers for a structured signing process