Skip to main content

​
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

ParameterTypeRequiredDescription
task_idintegerYesUnique identifier for the task

​
Request Body

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

​
Required Fields

FieldTypeDescription
step_run_idstringID of the signature step run

​
Optional Fields

FieldTypeDescription
auto_sendbooleanCreate the envelope and send it when true. Defaults to true
custom_recipientsbooleanUpsert the provided recipients before creating the envelope. Defaults to false
recipientsarrayRecipients to upsert. See Recipient Object. Required when custom_recipients is true
replace_signing_documentbooleanReplace the signing document before creating the envelope. Defaults to false
signing_documentobjectNew signing document. See File Object. Required when replace_signing_document is true
create_envelope_urlbooleanReturn the coordinator envelope URL (edit or view) in the response. Defaults to false

​
Recipient Object Fields

FieldTypeDescription
recipient_typestringRecipient role: signer or viewer. Defaults to signer
emailstringRecipient email address (required for each recipient)
namestringRecipient name (required for each recipient)

​
File Object Fields

FieldTypeDescription
filenamestringFilename, e.g. contract.pdf
base64_contentstringBase64-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

FieldTypeDescription
task_idintegerID of the task
envelope_idstring or nullProvider envelope identifier, if an envelope was created
envelope_urlobject or nullCoordinator envelope URL (only present when create_envelope_url=true and available)
messagestringSuccess confirmation message

​
Envelope URL Object Fields

FieldTypeDescription
url_typestringType of URL: edit or view
urlstringCoordinator 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