curl --request POST \
--url https://{instance}/wapi/v1/cards \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"contactId": 601,
"pipelineId": 2,
"sourceId": 4
}
'{
"requestId": "req_20e6a1",
"card": {
"id": 982,
"title": "API — Maria Souza",
"value": 1500,
"status": "open",
"probability": 50,
"pipeline": {
"id": 2,
"name": "Vendas"
},
"stage": {
"id": 8,
"name": "Qualificação"
},
"contact": {
"id": 601,
"name": "Maria Souza",
"number": "5534992341048",
"email": null,
"tags": []
},
"user": {
"id": 12,
"name": "Ana Paula"
},
"source": {
"id": 4,
"name": "Indicação"
},
"lostReason": null,
"originTicketId": null,
"expectedCloseDate": null,
"closedAt": null,
"stageEnteredAt": "2026-09-23T09:40:00.000Z",
"createdAt": "2026-09-23T09:40:00.000Z",
"updatedAt": "2026-09-23T09:40:00.000Z"
}
}{
"error": "ERR_CONTACT_IDENTIFIER_REQUIRED",
"code": "ERR_CONTACT_IDENTIFIER_REQUIRED"
}{
"error": "Token não fornecido",
"code": "ERR_TOKEN_MISSING"
}{
"error": "Token sem permissão para esta ação",
"code": "ERR_SCOPE_MISSING"
}{
"error": "ERR_PIPELINE_NOT_FOUND",
"code": "ERR_PIPELINE_NOT_FOUND"
}{
"error": "ERR_STAGE_NOT_IN_PIPELINE",
"code": "ERR_STAGE_NOT_IN_PIPELINE"
}{
"error": "Limite de requisições excedido",
"code": "ERR_RATE_LIMITED"
}Criar card
Cria um card num pipeline. Informe exatamente um entre contactId (contato já existente) e phone (cria ou reaproveita o contato pelo número, igual ao upsert de POST /v1/contacts) — nenhum ou os dois juntos devolve 400 ERR_CONTACT_IDENTIFIER_REQUIRED. pipelineId é obrigatório: use o id devolvido por GET /v1/pipelines; inexistente ou de outra conta devolve 404 ERR_PIPELINE_NOT_FOUND. stageId é opcional, mas se omitido o card é criado SEM etapa (stage: null) e não aparece nas colunas do kanban — envie sempre stageId; se enviado precisa pertencer ao MESMO pipelineId, senão 422 ERR_STAGE_NOT_IN_PIPELINE. sourceId é opcional; inexistente ou de outra conta devolve 404 ERR_SOURCE_NOT_FOUND. Quando a etapa informada exige origem obrigatória e sourceId não foi enviado, devolve 400 ERR_SOURCE_REQUIRED_FOR_STAGE (sem stageId, essa checagem não roda). customFields aceita os campos personalizados do pipeline (ou globais da conta): a chave é o nome técnico do campo, o valor já no formato esperado pelo tipo (select/multiselect precisam bater com as opções cadastradas). Campo inexistente, de outro pipeline/conta ou com valor inválido é ignorado — NUNCA falha a criação — e listado em ignoredCustomFields na resposta, presente só quando algo foi ignorado. Quem estiver com o kanban aberto no painel vê o card novo aparecer em tempo real. Requer escopo cards:write.
curl --request POST \
--url https://{instance}/wapi/v1/cards \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"contactId": 601,
"pipelineId": 2,
"sourceId": 4
}
'{
"requestId": "req_20e6a1",
"card": {
"id": 982,
"title": "API — Maria Souza",
"value": 1500,
"status": "open",
"probability": 50,
"pipeline": {
"id": 2,
"name": "Vendas"
},
"stage": {
"id": 8,
"name": "Qualificação"
},
"contact": {
"id": 601,
"name": "Maria Souza",
"number": "5534992341048",
"email": null,
"tags": []
},
"user": {
"id": 12,
"name": "Ana Paula"
},
"source": {
"id": 4,
"name": "Indicação"
},
"lostReason": null,
"originTicketId": null,
"expectedCloseDate": null,
"closedAt": null,
"stageEnteredAt": "2026-09-23T09:40:00.000Z",
"createdAt": "2026-09-23T09:40:00.000Z",
"updatedAt": "2026-09-23T09:40:00.000Z"
}
}{
"error": "ERR_CONTACT_IDENTIFIER_REQUIRED",
"code": "ERR_CONTACT_IDENTIFIER_REQUIRED"
}{
"error": "Token não fornecido",
"code": "ERR_TOKEN_MISSING"
}{
"error": "Token sem permissão para esta ação",
"code": "ERR_SCOPE_MISSING"
}{
"error": "ERR_PIPELINE_NOT_FOUND",
"code": "ERR_PIPELINE_NOT_FOUND"
}{
"error": "ERR_STAGE_NOT_IN_PIPELINE",
"code": "ERR_STAGE_NOT_IN_PIPELINE"
}{
"error": "Limite de requisições excedido",
"code": "ERR_RATE_LIMITED"
}Autorizações
Token criado em API → Tokens no painel. Prefixo wtx_live_ (ou wtx_test_).
Corpo
Exatamente um entre contactId/phone deve vir preenchido.
Mesmo id devolvido em GET /v1/pipelines.
Contato existente da sua conta.
Cria ou reaproveita o contato por número (mesmo upsert de POST /v1/contacts).
"5534992341048"
Nome usado se o contato for criado agora via phone.
Precisa ser do MESMO pipeline. Omitido = card criado SEM etapa (stage: null), fora das colunas do kanban — envie sempre este campo.
Default: "API — ".
Data de calendário (YYYY-MM-DD). ISO completo é aceito na entrada e reduzido ao dia em UTC.
Campos personalizados do pipeline informado (ou globais da conta) — chave é o nome técnico do campo, valor é o literal já no formato do tipo (select/multiselect precisam bater com as opções cadastradas). Campo inexistente, de outro pipeline/conta ou com valor inválido é IGNORADO (nunca falha a criação) e reportado em ignoredCustomFields na resposta.
{
"referred_by": "Indicação",
"payment_method": "Cartão"
}