PATCH

/v1/leads/{id}

Atualizar lead (dados, responsável, próxima ação)

score/qualified/ready só são aceitos de agentes (a qualificação é determinística — PRD §1.4). Etapa muda por POST /leads/{id}/stage.

Permissão:leads:write

Autenticação

Envie o token de acesso do usuário no cabeçalho Authorization e, se ele tiver mais de uma clínica, o X-Clinic-Id. Integrações servidor a servidor usam o token de serviço com X-Clinic-Id e X-Agent-Key. Como autenticar

1Authorization: Bearer <TOKEN>2X-Clinic-Id: <clinic_id>

Parâmetros

Parâmetros de caminho

Parâmetros de caminho
Parâmetro	Tipo	Obrigatório	Descrição
`id`	string	Sim	Id do recurso. · Entre 1 e 64 caracteres · Padrão (regex): `^[A-Za-z0-9._-]+$`

idstringObrigatório
Id do recurso. · Entre 1 e 64 caracteres · Padrão (regex): ^[A-Za-z0-9._-]+$

Cabeçalhos

Cabeçalhos
Parâmetro	Tipo	Obrigatório	Descrição
`X-Clinic-Id`	string	Não	Clínica ativa. Obrigatório só para quem tem acesso a mais de uma clínica (ou token de serviço). Validado contra o vínculo do usuário. · Padrão (regex): `^[A-Za-z0-9._-]{1,64}$`

X-Clinic-IdstringOpcional
Clínica ativa. Obrigatório só para quem tem acesso a mais de uma clínica (ou token de serviço). Validado contra o vínculo do usuário. · Padrão (regex): ^[A-Za-z0-9._-]{1,64}$

Corpo da requisição

application/json · obrigatório

Campos do corpo da requisição
Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Entre 2 e 128 caracteres
`phone`	string	Não	Entre 8 e 32 caracteres
`email`	string (e-mail) \| null	Não	Até 160 caracteres
`age`	integer \| null	Não	Entre 0 e 130
`sex`	string \| null	Não	Até 16 caracteres
`city`	string \| null	Não	Até 80 caracteres
`source`	string	Não	Valores: `META_ADS`, `GOOGLE`, `INSTAGRAM`, `FECHADA`, `INFLUENCER`, `INDICACAO`
`channel`	string	Não	Valores: `WhatsApp`, `Instagram`, `Site`, `E-mail`, `Telefone`
`serviceKey`	string \| null	Não	Até 64 caracteres
`professionalKey`	string \| null	Não	Até 64 caracteres
`owner`	object \| null	Não	—
`type` owner.type	string	Sim	Valores: `human`, `agent`
`id` owner.id	string	Sim	membership id (humano) ou agent_key (agente). · Até 64 caracteres
`nextAction`	object \| null	Não	—
`label` nextAction.label	string	Sim	Até 128 caracteres
`at` nextAction.at	string (data-hora) \| null	Sim	—
`actionable` nextAction.actionable	boolean	Não	—
`score`	integer	Não	Somente agentes (qualificação determinística MOVA-TECH-001). · Entre 0 e 100
`qualified`	boolean	Não	Somente agentes.
`ready`	boolean	Não	Somente agentes.
`touch`	boolean	Não	true = atualiza lastInteractionAt para agora.
`estimatedValue`	number \| null	Não	Valor estimado em R$ (no banco: centavos). null limpa. · Entre 0 e 10000000
`labelIds`	string[]	Não	Ids do catálogo GET /leads/labels (até 5). Lista vazia limpa. Substitui a lista inteira. · Até 5 itens · Cada item: entre 1 e 64 caracteres, padrão (regex): `^[A-Za-z0-9._-]+$`
`expectedCloseDate`	string \| null	Não	Data prevista de fechamento (YYYY-MM-DD). null limpa. · Formato `AAAA-MM-DD`

namestringOpcional
Entre 2 e 128 caracteres
phonestringOpcional
Entre 8 e 32 caracteres
emailstring (e-mail) | nullOpcional
Até 160 caracteres
ageinteger | nullOpcional
Entre 0 e 130
sexstring | nullOpcional
Até 16 caracteres
citystring | nullOpcional
Até 80 caracteres
sourcestringOpcional
Valores: META_ADS, GOOGLE, INSTAGRAM, FECHADA, INFLUENCER, INDICACAO
channelstringOpcional
Valores: WhatsApp, Instagram, Site, E-mail, Telefone
serviceKeystring | nullOpcional
Até 64 caracteres
professionalKeystring | nullOpcional
Até 64 caracteres
ownerobject | nullOpcional
typestringObrigatório
owner.type
Valores: human, agent
idstringObrigatório
owner.id
membership id (humano) ou agent_key (agente). · Até 64 caracteres
nextActionobject | nullOpcional
labelstringObrigatório
nextAction.label
Até 128 caracteres
atstring (data-hora) | nullObrigatório
nextAction.at
actionablebooleanOpcional
nextAction.actionable
scoreintegerOpcional
Somente agentes (qualificação determinística MOVA-TECH-001). · Entre 0 e 100
qualifiedbooleanOpcional
Somente agentes.
readybooleanOpcional
Somente agentes.
touchbooleanOpcional
true = atualiza lastInteractionAt para agora.
estimatedValuenumber | nullOpcional
Valor estimado em R$ (no banco: centavos). null limpa. · Entre 0 e 10000000
labelIdsstring[]Opcional
Ids do catálogo GET /leads/labels (até 5). Lista vazia limpa. Substitui a lista inteira. · Até 5 itens · Cada item: entre 1 e 64 caracteres, padrão (regex): ^[A-Za-z0-9._-]+$
expectedCloseDatestring | nullOpcional
Data prevista de fechamento (YYYY-MM-DD). null limpa. · Formato AAAA-MM-DD

Exemplo de requisição

Gerado do contrato. Troque os marcadores entre < > pelos seus valores.

1const res = await fetch("https://myclinc.leadpoint.com.br/v1/leads/<id>", {2  method: "PATCH",3  headers: {4    Authorization: "Bearer <TOKEN>",5    "X-Clinic-Id": "<clinic_id>",6    "Content-Type": "application/json",7  },8  body: JSON.stringify({9    "name": "<name>",10    "phone": "<phone>",11    "email": "contato@exemplo.com",12    "age": 1,13    "sex": "<sex>",14    "city": "<city>",15    "source": "META_ADS",16    "channel": "WhatsApp"17  }),18})1920if (!res.ok) {21  const { error } = await res.json()22  throw new Error(`${error.code}: ${error.message} (${error.requestId})`)23}24const { data } = await res.json()

Resposta

200OK — Sucesso.

JSON

1{2  "data": {3    "id": "<id>",4    "name": "<name>",5    "age": 1,6    "sex": "<sex>",7    "phone": "<phone>",8    "email": "<email>",9    "city": "<city>",10    "source": "META_ADS",11    "sourceLabel": "<sourceLabel>",12    "channel": "WhatsApp",13    "service": {14      "key": "<key>",15      "name": "<name>"16    },17    "stage": "NEW",18    "stageLabel": "<stageLabel>",19    "score": 1,20    "qualified": true,21    "ready": true,22    "appointment": "agendado",23    "appointmentAt": "2026-09-18T14:00:00.000Z",24    "appointmentId": "<appointmentId>",25    "professional": {26      "key": "<key>",27      "name": "<name>"28    },29    "lastInteractionAt": "2026-09-18T14:00:00.000Z",30    "lastInteractionMin": 1,31    "nextAction": {32      "label": "<label>",33      "at": "2026-09-18T14:00:00.000Z",34      "actionable": true35    },36    "owner": {37      "type": "human",38      "id": "<id>",39      "name": "<name>"40    }41  }42}

Exemplo gerado do esquema da resposta; valores entre < > são ilustrativos.

Códigos de erro

Corpo no formato padrão { error: { code, message, requestId } }. Veja todos os códigos.

400

Bad Request — Requisição malformada (JSON inválido, cursor inválido ou clínica ativa não informada).

401

Unauthorized — Token ausente, inválido ou expirado.

403

Forbidden — Autenticado, mas sem permissão (perfil ou clínica).

404

Not Found — Recurso não encontrado na clínica ativa.

422

Unprocessable Entity — Dados semanticamente inválidos (erros por campo em details).

429

Too Many Requests — Limite de requisições excedido (veja Retry-After).

500

Internal Server Error — Erro interno (sem detalhes expostos).

503

Service Unavailable — Banco de dados indisponível ou não configurado.

Limites

Limite padrão: 120 requisições a cada 60 segundos por token. Sobre limites

Testar no Swagger