Initiate Signature

Endpoint

POST /v2/tasks/{task_id}/initiate_sign

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: tasks:write

The envelope is created as the access token’s user, and any replacement signing document is uploaded as them.

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

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.

Request Example

curl -X POST "https://platform.chamelio.ai/v2/tasks/12345/initiate_sign" \
  -H "Authorization: Bearer your_access_token" \
  -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
  }'

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/initiate_sign"
headers = {
    "Authorization": "Bearer your_access_token",
    "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())

const taskId = 12345;

const response = await fetch(
  `https://platform.chamelio.ai/v2/tasks/${taskId}/initiate_sign`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      '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);

Response

Success Response

Status Code: 200 OK

{
  "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

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: tasks:write"
}

Or when the user may not act on this task:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the task does not exist.

{
  "detail": "Not found"
}

409 Conflict

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

{
  "detail": "The task is not in a state that allows this operation"
}

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

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

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when signature initiation fails due to a server error.

{
  "detail": "Failed to initiate signature"
}

Notes

Call Get Signature Details first to read the step status and existing recipients, and to obtain the step_run_id.

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.

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.

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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

Recipient Object Fields

File Object Fields

Request Example

Response

Success Response

Response Fields

Envelope URL Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Required Fields

​Optional Fields

​Recipient Object Fields

​File Object Fields

​Request Example

​Response

​Success Response

​Response Fields

​Envelope URL Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

Recipient Object Fields

File Object Fields

Request Example

Response

Success Response

Response Fields

Envelope URL Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases