Skip to content

Start Playbook Run ​

POST /external/v1/playbooks/:id/runs

Starts 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 ​

ParameterTypeRequiredDescription
idstringYesPlaybook identifier (UUID)

Request Body ​

FieldTypeRequiredDescription
contact_idstringNo*Contact the run is about
opportunity_idstringNo*Opportunity the run is about. Its contact comes along, and its owner receives the owner steps
conversation_idstringNo*Conversation linked to the run. Also used to find who handles the contact when there is no opportunity owner
titlestringNo*Run title (max 255). Required for an internal run (no contact, opportunity or conversation)
start_datestring (ISO 8601)NoWhen the run starts. Defaults to now; a date in the past makes the first steps overdue at once
skip_weekendsbooleanNoDue dates that fall on Saturday or Sunday move to Monday, same time. The next steps count from the moved date
timezonestringNoIANA 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 ​

bash
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"
  }'
javascript
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);
python
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.

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

StatusCodeDescription
400VALIDATION_ERRORNo 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
403INSUFFICIENT_PERMISSIONSKey lacks playbooks:run
404NOT_FOUNDPlaybook not found, or not visible to the key's creator

GetRaze - AI-Powered Lead Generation