Skip to main content
O lead score soma os pontos dos critérios aplicados a um lead ou a uma oportunidade, sempre limitado entre 0 e 100. Pela API externa você lista, consulta, cria e atualiza os critérios da empresa em /integrations/external/lead-scores/criteria e aplica critérios já no cadastro de leads e oportunidades. A exclusão de critérios é feita apenas no CRM. O usuário que criou a chave é o ator das operações. Se ele estiver inativo, as rotas retornam 403.

Como um critério funciona

Quando o critério tem opções ativas, quem aplica precisa escolher uma delas, e a pontuação aplicada é a da opção. Sem opções ativas, vale o points do critério. Alterar um critério depois não recalcula leads e oportunidades que já o receberam: cada aplicação guarda a pontuação e os nomes da época.

Listar e consultar

A listagem aceita search (parte do nome), skip, take (de 1 a 100, padrão 10), category_id, without_category=true (somente critérios sem categoria), target_type e status. target_type=LEAD e target_type=DEAL também trazem os critérios BOTH; target_type=BOTH traz apenas os compartilhados. category_id e without_category=true não podem ser usados juntos. Os critérios vêm do mais recente para o mais antigo:
options traz as opções ativas e inativas, ordenadas por position. Critérios inativos aparecem na listagem, a menos que você filtre por status=1. Para consultar um critério, use GET /integrations/external/lead-scores/criteria/{id}; um critério inexistente, excluído no CRM ou de outra empresa retorna 404.

Criar um critério

A resposta 201 é o critério criado, já ativo e com os IDs das opções, no mesmo formato da consulta. target_type, name e points são obrigatórios; points continua obrigatório mesmo com opções e vale se o critério ficar sem opções ativas.
  • name e label aceitam até 120 caracteres; os espaços das extremidades são removidos, e um nome só com espaços retorna 400.
  • description aceita até 5.000 caracteres.
  • Um critério aceita até 50 opções, e os nomes das opções não podem se repetir no mesmo critério, sem diferenciar maiúsculas e minúsculas.
  • Nas opções, position assume a ordem da lista e status assume 1 quando omitidos.
  • Uma categoria inexistente ou inativa em category_id retorna 404.
  • A criação não usa idempotência: repetir a chamada cria outro critério.

Atualizar um critério

PUT /integrations/external/lead-scores/criteria/{id} altera somente os campos enviados:
Quando options é enviado, ele substitui a lista inteira: opções com id são atualizadas, opções sem id são criadas e as opções atuais que não vierem na lista são excluídas. Para manter as opções como estão, não envie options; para remover todas, envie uma lista vazia. Consulte o critério antes de alterar as opções para reenviar os id das que devem continuar. Um id que não pertence ao critério retorna 404. category_id: null remove a categoria, e description: null limpa a descrição. target_type, name, points, status e options não aceitam null. Para tirar um critério de uso, envie status: 0: ele deixa de poder ser aplicado e de contar no conhecimento do registro, mas as aplicações já feitas continuam. status: 1 o reativa. Não há exclusão pela API.

Aplicar critérios no cadastro

POST /integrations/external/leads e POST /integrations/external/deals aceitam score_applications, com até 50 critérios. Cada item tem criterion_id, criterion_option_id e note, a observação do critério aplicado:
  • A chave precisa de crm/lead-score.create, além da permissão de criar o registro. Sem ela, a criação inteira retorna 403. Uma lista vazia ou a ausência do campo não exige a permissão.
  • Cada critério precisa estar ativo e servir ao registro: leads aceitam critérios LEAD ou BOTH; oportunidades, DEAL ou BOTH. O mesmo critério não pode vir duas vezes.
  • criterion_option_id é obrigatório quando o critério tem opções ativas e precisa ser uma delas; quando o critério não tem opções ativas, a opção não pode ser enviada.
  • note é opcional e aceita até 5.000 caracteres.
  • Permissão e critérios são conferidos antes da idempotência e da deduplicação de pessoa: um critério inválido retorna erro sem consumir a chave de idempotência, alterar uma pessoa ou criar o registro. Repetir uma criação já concluída devolve o registro sem conferir os critérios de novo.
  • Os critérios são gravados logo depois do registro, com o histórico do score e uma atividade na linha do tempo, e atualizam score, score_criteria_count e score_updated_at. Se a empresa usa o lead score como métrica de qualificação, eles também atendem às etapas que exigem qualificação na entrada.
A API externa aplica critérios apenas na criação. Para mudar a pontuação de um registro existente, use o CRM. Os demais campos do cadastro estão no guia de leads e oportunidades.

Erros