Create Task
POST/external/v1/tasksCreates a task. Link it to an opportunity (opportunity_id) or to a contact (contact_id); with neither, it is a standalone team task. The task appears in the app at once: in the Tasks home, on the board and on the contact or opportunity it belongs to.
Authentication
Requires tasks:write permission. The task is authored by the user who created the API key.
Safe retries
Send an Idempotency-Key header to retry without creating duplicates. See Idempotency.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
title | string | Yes | What has to be done (max 500 characters) |
description | string | No | Details |
task_type | string | No | call (default), meeting, email, follow_up, proposal, communication, internal_task, other |
priority | string | No | low, medium (default), high, urgent |
status | string | No | pending (default), in_progress, completed |
due_date | string (ISO 8601) | No | When it is due. Send it with an offset (2026-10-20T14:00:00-03:00) or in UTC (Z); a value without an offset is read as UTC |
end_date | string (ISO 8601) | No | End of a multi-day task (after due_date) |
opportunity_id | string | No | Opportunity the task belongs to |
contact_id | string | No | Contact the task belongs to. With opportunity_id, it must be the opportunity's contact |
assignee_ids | string[] | No | Active users of the account responsible for the task (see List Users) |
label_ids | string[] | No | Task labels (see Task pipelines and labels) |
task_pipeline_id | string | No | Task pipeline (board). Defaults to the account default pipeline |
reminder_minutes_before | integer | No | 15, 60 or 1440: reminder sent to the assignees before due_date |
size | string | No | XS, S, M, L, XL |
estimate_hours | number | No | Effort estimate in hours |
recurrence | object | No | Repeat the task when it is completed (below) |
Recurrence
| Field | Type | Required | Description |
|---|---|---|---|
unit | string | Yes | hour, day or week |
interval | integer | No | Every N units (default 1) |
end_date | string (ISO 8601) | No | No occurrence after this date |
count | integer | No | How many more occurrences |
When a recurring task is completed, the next occurrence is created with the same fields, assignees, labels and subtasks, due one interval later.
Request
curl --request POST \
--url "https://app.getraze.com/external/v1/tasks" \
--header "Content-Type: application/json" \
--header "X-API-Key: YOUR_API_KEY" \
--header "Idempotency-Key: crm-sync-48213" \
--data '{
"title": "Call to confirm the proposal",
"task_type": "call",
"priority": "high",
"due_date": "2026-10-20T14:00:00-03:00",
"opportunity_id": "e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34",
"assignee_ids": ["2d19889d-6ff9-4782-8165-32e56bb593c0"],
"reminder_minutes_before": 60
}'const axios = require('axios');
const response = await axios.post(
'https://app.getraze.com/external/v1/tasks',
{
title: 'Call to confirm the proposal',
task_type: 'call',
priority: 'high',
due_date: '2026-10-20T14:00:00-03:00',
opportunity_id: 'e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34',
assignee_ids: ['2d19889d-6ff9-4782-8165-32e56bb593c0'],
reminder_minutes_before: 60
},
{
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Idempotency-Key': 'crm-sync-48213'
}
}
);
console.log(response.data);import requests
response = requests.post(
'https://app.getraze.com/external/v1/tasks',
headers={
'X-API-Key': 'YOUR_API_KEY',
'Idempotency-Key': 'crm-sync-48213'
},
json={
'title': 'Call to confirm the proposal',
'task_type': 'call',
'priority': 'high',
'due_date': '2026-10-20T14:00:00-03:00',
'opportunity_id': 'e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34',
'assignee_ids': ['2d19889d-6ff9-4782-8165-32e56bb593c0'],
'reminder_minutes_before': 60
}
)
print(response.json())Response
201 Created with the task, in the format of Get Task. The response always carries the created task, even when the key's creator would not see it in the list (for example, a seller creating a task only for someone else).
{
"success": true,
"data": {
"id": "7b1e4c52-9a0d-4f1e-8c35-2d6f0a9b3e11",
"number": 483,
"title": "Call to confirm the proposal",
"task_type": "call",
"status": "pending",
"priority": "high",
"due_date": "2026-10-20T17:00:00.000Z",
"reminder_minutes_before": 60,
"task_pipeline": { "id": "4a0631b8-b1cb-48c6-af5e-9df2bca56645", "name": "General" },
"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" },
"assignees": [
{ "id": "2d19889d-6ff9-4782-8165-32e56bb593c0", "name": "Maria Silva", "email": "maria@acme.com" }
],
"labels": [],
"subtasks": [],
"created_at": "2026-10-19T13:38:13.000Z"
}
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing title; a value outside the allowed list; invalid date; end_date before due_date; an opportunity, contact, user, label or task pipeline that is not in this account; contact_id different from the opportunity's contact |
| 403 | INSUFFICIENT_PERMISSIONS | Key lacks tasks:write |