Descubra os funis e as colunas de um projeto e cadastre as pessoas do CRM dele antes de criar oportunidades.

Funis e contatos

Para criar uma oportunidade num projeto, você precisa do funil (pipeline_id), da coluna (phase) e, quase sempre, da pessoa (lead_id). Estas rotas entregam os três. O projeto interno do time também é um projeto: é o que vem com is_internal: true em GET /projects; use o id dele para consultar os funis e os contatos do CRM principal.

Projeto inexistente, de outro time ou com id malformado retorna 404 NOT_FOUND.

GET /projects/:id/pipelines

Lista os funis do projeto com as colunas e os motivos de perda. O funil padrão vem primeiro; as colunas saem na ordem do quadro. Não há paginação.

curl "https://app.usecolmeia.com/api/v1/projects/11111111-1111-4111-8111-111111111111/pipelines" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

{
  "success": true,
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "name": "Vendas",
      "slug": "vendas",
      "is_default": true,
      "columns": [
        { "slug": "novo", "title": "Novo", "position": 0, "outcome": "open", "is_terminal": false },
        { "slug": "proposta", "title": "Proposta", "position": 1, "outcome": "open", "is_terminal": false },
        { "slug": "ganho", "title": "Ganho", "position": 2, "outcome": "won", "is_terminal": true },
        { "slug": "perdido", "title": "Perdido", "position": 3, "outcome": "lost", "is_terminal": true }
      ],
      "loss_reasons": [
        { "id": "88888888-8888-4888-8888-888888888888", "name": "Preço" }
      ]
    }
  ]
}

columns[].slug é o valor de phase em POST /deals e PUT /deals/:id.
outcome é open (coluna aberta), won (ganho) ou lost (perda). A oportunidade só nasce em coluna open; para levar a won, a atualização precisa de win_note.
loss_reasons são os motivos aceitos em loss_reason_id. Um funil sem lista própria usa a do funil padrão.

GET /projects/:id/leads

Lista as pessoas do CRM do projeto, das mais recentes para as mais antigas. Cada item tem o mesmo formato do objeto lead de uma oportunidade.

Parâmetros de consulta

Parâmetro	Tipo	Padrão	Descrição
`page`	number	`1`	Página a retornar.
`limit`	number	`20`	Itens por página, entre `1` e `100`.
`search`	string	—	Busca parcial no nome, no e-mail ou no telefone.
`is_active`	boolean	—	`true` só ativos, `false` só inativos; sem o parâmetro, os dois. Outro valor retorna `422 VALIDATION_ERROR`.
`company_id`	uuid	—	Só as pessoas dessa empresa. Valor que não é UUID retorna `422 VALIDATION_ERROR`.

curl "https://app.usecolmeia.com/api/v1/projects/11111111-1111-4111-8111-111111111111/leads?search=maria" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

{
  "success": true,
  "data": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "public_id": "le_exemplo",
      "project_id": "11111111-1111-4111-8111-111111111111",
      "full_name": "Maria Silva",
      "name": "Maria Silva",
      "email": "maria@empresa-exemplo.test",
      "phone": "+5511999999999",
      "tags": ["indicacao"],
      "notes": null,
      "customer_source": "api",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null,
      "attribution": null,
      "metadata": {},
      "custom_fields": { "cargo": "CEO" },
      "is_active": true,
      "contact_identity_id": "55555555-5555-4555-8555-555555555555",
      "company_id": "77777777-7777-4777-8777-777777777777",
      "company": { "id": "77777777-7777-4777-8777-777777777777", "name": "Acme Serviços Digitais" },
      "company_name": "Acme Serviços Digitais",
      "identity": {
        "id": "55555555-5555-4555-8555-555555555555",
        "display_name": "Maria Silva",
        "primary_phone": "+5511999999999",
        "primary_email": "maria@empresa-exemplo.test",
        "custom_fields": { "porte": "grande" },
        "created_at": "2026-08-01T10:30:00.000Z",
        "updated_at": "2026-08-01T10:30:00.000Z"
      },
      "created_by": null,
      "created_at": "2026-08-01T10:30:00.000Z",
      "updated_at": "2026-08-01T10:30:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
}

custom_fields traz só os campos que se aplicam ao projeto. identity é a identidade compartilhada da pessoa, com os campos de Contato (CRM).

POST /projects/:id/leads

Cadastra uma pessoa no CRM do projeto. Só o contato: nenhuma oportunidade é criada. Para abrir uma, envie o id devolvido em lead_id no POST /deals.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`full_name`	string	Sim	Nome da pessoa.
`email`	string	Não	E-mail.
`phone`	string	Não	Telefone. Números brasileiros são gravados no formato `+55…`.
`company_id`	uuid	Não	Empresa ativa do mesmo projeto.
`tags`	array	Não	Lista de textos.
`notes`	string	Não	Observações.
`customer_source`	string	Não	Origem do contato.

Outros campos são ignorados. Campos personalizados do contato ainda não são gravados por esta rota.

curl -X POST "https://app.usecolmeia.com/api/v1/projects/11111111-1111-4111-8111-111111111111/leads" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Maria Silva",
    "email": "maria@empresa-exemplo.test",
    "phone": "(11) 99999-9999",
    "company_id": "77777777-7777-4777-8777-777777777777",
    "customer_source": "api"
  }'

A resposta 201 traz a pessoa criada, no mesmo formato da listagem, dentro de { "success": true, "data": { ... } }.

Duplicatas

A criação não reaproveita cadastros em silêncio. Se o telefone ou o e-mail já pertence a uma pessoa do projeto, a API retorna 422 com o código DUPLICATE_ENTRY e o cadastro existente; use esse id em vez de criar outro. Nome igual, com telefone e e-mail diferentes, não é duplicata.

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTRY",
    "message": "Este telefone já é de «Maria Silva». Use esse contato ou corrija o telefone.",
    "details": {
      "existing_contact_id": "44444444-4444-4444-8444-444444444444",
      "matched_by": "phone",
      "archived": false
    }
  }
}

archived: true indica que o cadastro existente está inativo.

Erros

Situação	Status	Código	Detalhe
Corpo que não é JSON	`400`	`VALIDATION_ERROR`	—
`full_name` vazio, e-mail inválido, `tags` que não é lista de textos ou campo de texto com outro tipo	`400`	`VALIDATION_ERROR`	`details.field`
`company_id` que não é UUID ou não é empresa ativa do projeto	`422`	`VALIDATION_ERROR`	`details.field: "company_id"`
Telefone ou e-mail já cadastrado no projeto	`422`	`DUPLICATE_ENTRY`	`details.existing_contact_id`
Projeto arquivado	`409`	`PROJECT_ARCHIVED`	—

O corpo é validado antes do projeto: um corpo inválido enviado a um projeto inexistente responde 400, não 404.

Funis e contatos

On this page