Criar Tarefa
POST/external/v1/tasksCria uma tarefa. Vincule-a a uma oportunidade (opportunity_id) ou a um contato (contact_id); sem nenhum dos dois, ela é uma tarefa avulsa da equipe. A tarefa aparece no app na hora: na home de Tarefas, no quadro e no contato ou na oportunidade a que pertence.
Autenticação
Requer permissão tasks:write. O autor da tarefa é o usuário que criou a chave.
Retentativas seguras
Envie um header Idempotency-Key para repetir a requisição sem criar duplicatas. Veja Idempotência.
Corpo da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | Sim | O que precisa ser feito (máx. 500 caracteres) |
description | string | Não | Detalhes |
task_type | string | Não | call (padrão), meeting, email, follow_up, proposal, communication, internal_task, other |
priority | string | Não | low, medium (padrão), high, urgent |
status | string | Não | pending (padrão), in_progress, completed |
due_date | string (ISO 8601) | Não | Prazo. Envie com offset (2026-10-20T14:00:00-03:00) ou em UTC (Z); um valor sem offset é lido como UTC |
end_date | string (ISO 8601) | Não | Fim de uma tarefa de vários dias (depois de due_date) |
opportunity_id | string | Não | Oportunidade a que a tarefa pertence |
contact_id | string | Não | Contato a que a tarefa pertence. Junto com opportunity_id, precisa ser o contato da oportunidade |
assignee_ids | string[] | Não | Usuários ativos da conta responsáveis pela tarefa (veja Listar Usuários) |
label_ids | string[] | Não | Etiquetas de tarefa (veja Pipelines e Etiquetas de Tarefa) |
task_pipeline_id | string | Não | Pipeline de tarefas (quadro). O padrão é o pipeline padrão da conta |
reminder_minutes_before | integer | Não | 15, 60 ou 1440: lembrete enviado aos responsáveis antes de due_date |
size | string | Não | XS, S, M, L, XL |
estimate_hours | number | Não | Estimativa de esforço em horas |
recurrence | object | Não | Repete a tarefa quando ela é concluída (abaixo) |
Recorrência
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
unit | string | Sim | hour, day ou week |
interval | integer | Não | A cada N unidades (padrão 1) |
end_date | string (ISO 8601) | Não | Nenhuma ocorrência depois desta data |
count | integer | Não | Quantas ocorrências a mais |
Quando uma tarefa recorrente é concluída, a próxima ocorrência é criada com os mesmos campos, responsáveis, etiquetas e subtarefas, com prazo um intervalo depois.
Requisição
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": "Ligar para confirmar a proposta",
"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: 'Ligar para confirmar a proposta',
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': 'Ligar para confirmar a proposta',
'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())Resposta
201 Created com a tarefa, no formato de Buscar Tarefa. A resposta sempre traz a tarefa criada, mesmo quando o criador da chave não a veria na listagem (por exemplo, um vendedor criando uma tarefa só para outra pessoa).
{
"success": true,
"data": {
"id": "7b1e4c52-9a0d-4f1e-8c35-2d6f0a9b3e11",
"number": 483,
"title": "Ligar para confirmar a proposta",
"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": "Geral" },
"contact": { "id": "c2f9d1a4-5b7e-4c1a-9e0f-3a8b6d2c4e71", "name": "John Doe", "company": "Acme Inc" },
"opportunity": { "id": "e8a3b2c1-6d4f-4a9e-b1c7-5f2d8e0a9b34", "title": "Acme Inc - Plano 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"
}
}Erros
| Status | Código | Descrição |
|---|---|---|
| 400 | VALIDATION_ERROR | title ausente; valor fora da lista permitida; data inválida; end_date antes de due_date; oportunidade, contato, usuário, etiqueta ou pipeline de tarefas que não é desta conta; contact_id diferente do contato da oportunidade |
| 403 | INSUFFICIENT_PERMISSIONS | A chave não tem tasks:write |