Initiate Signature

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:

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. 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/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
  }'

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

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

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

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.

{
  "detail": "Invalid API key"
}

404 Not Found

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

{
  "detail": "Task not found"
}

409 Conflict

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

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

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

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

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

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

​401 Unauthorized

​404 Not Found

​409 Conflict

​422 Validation Error

​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

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

500 Internal Server Error

Notes

Use Cases