Registros por oportunidade, empresa ou pessoa

Uma lista de dados é uma tabela vinculada a uma oportunidade, empresa ou pessoa. Cada linha é um registro; cada coluna é um campo, identificado por uma chave de 32 caracteres. Um registro só aparece na interface quando está vinculado a uma entidade, e os endpoints desta seção criam o registro e o vínculo em uma única chamada.

Antes de começar

• Autentique todas as chamadas com o cabeçalho token: SEU_TOKEN. Veja Token de autenticação.
• URL base: https://api.pipe.run/v1.
• Tenha em mãos o ID numérico da oportunidade, empresa ou pessoa. Na interface, o ID da oportunidade é o número final da URL app.pipe.run/v2/pipeline/deal/{deal_id}. Para empresas e pessoas, use Listar empresas e Listar pessoas. O hash da oportunidade não é aceito nestes endpoints.

Passo 1: descubra a lista e as chaves dos campos

Liste as listas de dados da entidade desejada (deals, companies ou persons):

GET /v1/datalists?entity=deals

Depois consulte a lista escolhida em Ver detalhes da lista de dados. A resposta traz os campos com a key que você vai usar no payload, o tipo (datalist_field_type_id) e, para campos de opção, os IDs das opções:

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 1212,
    "name": "Faturamento mensal",
    "entity": "deals",
    "fields": [
      { "id": 1, "name": "Competência", "key": "6d10783c2a2bd628d6ac0944757c9cf8", "datalist_field_type_id": 4 },
      { "id": 2, "name": "Valor", "key": "a827b6e4df0535f21d6739624084a707", "datalist_field_type_id": 1 },
      { "id": 3, "name": "Situação", "key": "e1c5ff25f5d853ff0d94079e50e06d73", "datalist_field_type_id": 8,
        "options": [ { "id": 31, "name": "Pago" }, { "id": 32, "name": "Em aberto" } ] }
    ]
  }
}

Passo 2: grave o registro vinculado à entidade

O corpo tem o campo order (posição da linha, inteiro de 0 a 9999, obrigatório) e uma propriedade por campo, cuja chave é a key do campo e cujo valor é um objeto { "value": ... }:

{
  "order": 1,
  "6d10783c2a2bd628d6ac0944757c9cf8": { "value": "2026-08-31" },
  "a827b6e4df0535f21d6739624084a707": { "value": 125000 },
  "e1c5ff25f5d853ff0d94079e50e06d73": { "value": 31 }
}

Resposta 201 Created. Guarde o data.id: ele é o ID do registro, necessário para atualizar ou excluir.

{
  "success": true,
  "message": "Created",
  "data": {
    "id": 55012,
    "datalist_id": 1212,
    "order": 1,
    "6d10783c2a2bd628d6ac0944757c9cf8": { "value": "2026-08-31" },
    "a827b6e4df0535f21d6739624084a707": { "value": 125000 },
    "e1c5ff25f5d853ff0d94079e50e06d73": { "value": 31 }
  }
}

Para cada linha da sua planilha, faça uma chamada com um order diferente. Um registro pertence a uma única oportunidade, empresa ou pessoa.

Formato de value por tipo de campo

Valor fora do formato retorna 422 Unprocessable Entity com a mensagem do erro em data.

Passo 3: consulte, atualize ou exclua

Registros vinculados a uma entidade, sem paginação:

Atualizar e excluir usam o ID do registro. O corpo do PUT segue o mesmo formato do POST; envie apenas os campos que quer alterar.

Não há endpoint de exclusão em lote. Para substituir todos os registros de uma entidade, liste-os e exclua um a um, ou prefira atualizar os existentes com PUT.

Regras que costumam causar dúvida

🚧

Use sempre o endpoint da entidade para criar

POST /v1/datalists/{datalist_id}/records cria um registro sem vínculo, que não aparece em nenhuma oportunidade, empresa ou pessoa.

• A lista pertence a uma entidade. Uma lista com entity: deals só é aceita no endpoint de oportunidades; nos demais, retorna 404.
• Chave inexistente não gera erro. Se a key estiver errada, o registro é criado sem aquele valor. Confira o data da resposta antes de considerar a linha gravada.
• "value": null é ignorado. Não limpa o valor já gravado.
• Datas seguem AAAA-MM-DD. 31/08/2026 retorna 422.
• Opções são informadas pelo ID, obtido no Passo 1.

Exemplo completo com curl

# 1. Chaves dos campos
curl -sS -H "token: SEU_TOKEN" https://api.pipe.run/v1/datalists/1212

# 2. Grava uma linha na oportunidade 123456
curl -sS -X POST -H "token: SEU_TOKEN" -H "Content-Type: application/json" \
  https://api.pipe.run/v1/deals/123456/datalists/1212/records \
  -d '{"order":1,"6d10783c2a2bd628d6ac0944757c9cf8":{"value":"2026-08-31"},"a827b6e4df0535f21d6739624084a707":{"value":125000}}'

# 3. Confere o que ficou gravado na oportunidade
curl -sS -H "token: SEU_TOKEN" https://api.pipe.run/v1/deals/123456/datalists/1212/records