Skip to content

Criar Tarefa ​

POST /external/v1/tasks

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

CampoTipoObrigatórioDescrição
titlestringSimO que precisa ser feito (máx. 500 caracteres)
descriptionstringNãoDetalhes
task_typestringNãocall (padrão), meeting, email, follow_up, proposal, communication, internal_task, other
prioritystringNãolow, medium (padrão), high, urgent
statusstringNãopending (padrão), in_progress, completed
due_datestring (ISO 8601)NãoPrazo. Envie com offset (2026-10-20T14:00:00-03:00) ou em UTC (Z); um valor sem offset é lido como UTC
end_datestring (ISO 8601)NãoFim de uma tarefa de vários dias (depois de due_date)
opportunity_idstringNãoOportunidade a que a tarefa pertence
contact_idstringNãoContato a que a tarefa pertence. Junto com opportunity_id, precisa ser o contato da oportunidade
assignee_idsstring[]NãoUsuários ativos da conta responsáveis pela tarefa (veja Listar Usuários)
label_idsstring[]NãoEtiquetas de tarefa (veja Pipelines e Etiquetas de Tarefa)
task_pipeline_idstringNãoPipeline de tarefas (quadro). O padrão é o pipeline padrão da conta
reminder_minutes_beforeintegerNão15, 60 ou 1440: lembrete enviado aos responsáveis antes de due_date
sizestringNãoXS, S, M, L, XL
estimate_hoursnumberNãoEstimativa de esforço em horas
recurrenceobjectNãoRepete a tarefa quando ela é concluída (abaixo)

Recorrência ​

CampoTipoObrigatórioDescrição
unitstringSimhour, day ou week
intervalintegerNãoA cada N unidades (padrão 1)
end_datestring (ISO 8601)NãoNenhuma ocorrência depois desta data
countintegerNãoQuantas 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 ​

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

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

StatusCódigoDescrição
400VALIDATION_ERRORtitle 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
403INSUFFICIENT_PERMISSIONSA chave não tem tasks:write

GetRaze - AI-Powered Lead Generation