Skip to content

Create Task ​

POST /external/v1/tasks

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

FieldTypeRequiredDescription
titlestringYesWhat has to be done (max 500 characters)
descriptionstringNoDetails
task_typestringNocall (default), meeting, email, follow_up, proposal, communication, internal_task, other
prioritystringNolow, medium (default), high, urgent
statusstringNopending (default), in_progress, completed
due_datestring (ISO 8601)NoWhen 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_datestring (ISO 8601)NoEnd of a multi-day task (after due_date)
opportunity_idstringNoOpportunity the task belongs to
contact_idstringNoContact the task belongs to. With opportunity_id, it must be the opportunity's contact
assignee_idsstring[]NoActive users of the account responsible for the task (see List Users)
label_idsstring[]NoTask labels (see Task pipelines and labels)
task_pipeline_idstringNoTask pipeline (board). Defaults to the account default pipeline
reminder_minutes_beforeintegerNo15, 60 or 1440: reminder sent to the assignees before due_date
sizestringNoXS, S, M, L, XL
estimate_hoursnumberNoEffort estimate in hours
recurrenceobjectNoRepeat the task when it is completed (below)

Recurrence ​

FieldTypeRequiredDescription
unitstringYeshour, day or week
intervalintegerNoEvery N units (default 1)
end_datestring (ISO 8601)NoNo occurrence after this date
countintegerNoHow 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 ​

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

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

StatusCodeDescription
400VALIDATION_ERRORMissing 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
403INSUFFICIENT_PERMISSIONSKey lacks tasks:write

GetRaze - AI-Powered Lead Generation