Start Playbook Run
POST/external/v1/playbooks/:id/runsStarts a playbook: creates a run and one task per step, with due dates chained from start_date and assignees as configured in each step. It is the same operation as Start playbook in the app, and the assignees are notified the same way.
Authentication
Requires playbooks:run permission. The playbook must be active and visible to the user who created the API key. The run is started by that user.
Safe retries
Send an Idempotency-Key header so a retry does not start the playbook twice. See Idempotency.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Playbook identifier (UUID) |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
contact_id | string | No* | Contact the run is about |
opportunity_id | string | No* | Opportunity the run is about. Its contact comes along, and its owner receives the owner steps |
conversation_id | string | No* | Conversation linked to the run. Also used to find who handles the contact when there is no opportunity owner |
title | string | No* | Run title (max 255). Required for an internal run (no contact, opportunity or conversation) |
start_date | string (ISO 8601) | No | When the run starts. Defaults to now; a date in the past makes the first steps overdue at once |
skip_weekends | boolean | No | Due dates that fall on Saturday or Sunday move to Monday, same time. The next steps count from the moved date |
timezone | string | No | IANA time zone that decides what "Saturday" is for skip_weekends, e.g. America/Sao_Paulo. Defaults to the time zone of the key's creator, then UTC |
* Send at least one of contact_id, opportunity_id, conversation_id or title. When more than one is sent, they must point to the same contact.
Who receives each task comes from the playbook configuration (see Get Playbook); it cannot be overridden per run.
Request
curl --request POST \
--url "https://app.getraze.com/external/v1/playbooks/9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62/runs" \
--header "Content-Type: application/json" \
--header "X-API-Key: YOUR_API_KEY" \
--header "Idempotency-Key: deal-won-e8a3b2c1" \
--data '{
"opportunity_id": "e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34",
"skip_weekends": true,
"timezone": "America/Sao_Paulo"
}'const axios = require('axios');
const playbookId = '9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62';
const response = await axios.post(
`https://app.getraze.com/external/v1/playbooks/${playbookId}/runs`,
{
opportunity_id: 'e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34',
skip_weekends: true,
timezone: 'America/Sao_Paulo'
},
{
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Idempotency-Key': 'deal-won-e8a3b2c1'
}
}
);
console.log(response.data);import requests
playbook_id = '9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62'
response = requests.post(
f'https://app.getraze.com/external/v1/playbooks/{playbook_id}/runs',
headers={
'X-API-Key': 'YOUR_API_KEY',
'Idempotency-Key': 'deal-won-e8a3b2c1'
},
json={
'opportunity_id': 'e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34',
'skip_weekends': True,
'timezone': 'America/Sao_Paulo'
}
)
print(response.json())Response
201 Created with the run, in the format of Get Playbook Run. Each step carries the task_id of the task it created.
{
"success": true,
"data": {
"id": "3ef8c1c3-c081-4187-a6aa-657fbf1a813b",
"playbook": { "id": "9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62", "name": "Onboarding" },
"status": "in_progress",
"context": {
"type": "contact",
"name": "John Doe",
"contact": { "id": "c2f9d1a4-5b7e-4c1a-9e0f-3a8b6d2c4e71", "name": "John Doe", "company": "Acme Inc" },
"opportunity": { "id": "e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34", "title": "Acme Inc - Plan Pro" },
"conversation_id": null
},
"progress": { "steps_done": 0, "steps_total": 3, "overdue_steps": 0 },
"steps": [
{ "position": 1, "task_id": "97f785b0-d1ce-4a2b-8142-89c2fb88d501", "title": "Welcome call", "status": "pending", "due_date": "2026-10-23T22:00:00.000Z", "assignees": [{ "id": "2d19889d-6ff9-4782-8165-32e56bb593c0", "name": "Maria Silva" }] },
{ "position": 2, "task_id": "a8e9f0b1-c2d3-4e5f-8a9b-0c1d2e3f4a5b", "title": "Send the onboarding kit", "status": "pending", "due_date": "2026-10-26T22:00:00.000Z", "assignees": [] }
]
}
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | No contact, opportunity, conversation or title; ids that are not in this account or point to different contacts; invalid start_date or timezone; the playbook is inactive or has no steps |
| 403 | INSUFFICIENT_PERMISSIONS | Key lacks playbooks:run |
| 404 | NOT_FOUND | Playbook not found, or not visible to the key's creator |