Entregar um lead - Homfy Public API

Entrega UM lead à Homfy. A Homfy cria sozinha o Cliente (ou reaproveita o que já existe com o mesmo WhatsApp), a Oportunidade (na primeira etapa em andamento do quadro padrão) e, se vier visit_at, a Visita, e encaminha o atendimento: o corretor de agent_whatsapp recebe o lead por WhatsApp; sem corretor (ou com um que a Homfy não acha), o lead entra "Sem atendimento" e o gestor é avisado.

Reexecutável: reenviar o mesmo external_id devolve result: "skipped" (HTTP 200) com a situação atual da entrada, sem reprocessar nem atualizar nada — o corpo novo não é comparado com o antigo. Entrada nova devolve result: "accepted" (HTTP 202) em poucos segundos; o resto acontece em segundo plano.

Três avisos:

O external_id é também o partner_code da Oportunidade criada (consultável por POST /partner/v1/opportunity/find). Por isso não reuse um código que você já mandou em POST /partner/v1/opportunity: o lead falha com PARTNER_CODE_CONFLICT em error.

O processamento é assíncrono: o 202 só confirma o recebimento. O resultado (Cliente, Oportunidade, Visita, atendimento e avisos) se consulta por POST /partner/v1/lead-intake/find.

Cada lead pode disparar WhatsApp para o corretor (quando ele é encontrado) ou para o gestor (quando o lead fica "Sem atendimento"). Não use esta rota para teste em carga nem para importar histórico.

visit_at precisa de fuso (2026-10-10T10:00:00-03:00): sem ele a resposta é 400 e a frase de errorMessage começa com VISIT_AT_WITHOUT_TIMEZONE.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Example

{
    "external_id": "LEAD-2210",
    "visit_at": "2026-10-10T10:00:00-03:00",
    "acquisition_channel": "paid_social",
    "lead": {
        "name": "Ana Pereira",
        "whatsapp": "(48) 99999-1234",
        "email": "ana@exemplo.com"
    },
    "property_code": "AP-0042",
    "agent_whatsapp": "+55 (48) 98888-7777",
    "message": "Quer visitar no sábado.",
    "acquisition_source": "zap"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200

application/json

O external_id já tinha sido recebido (result: "skipped"): nada foi alterado nem reprocessado, e status é a situação atual daquela entrada. O corpo novo NÃO é comparado com o antigo.

Bodyapplication/json

Example

{
    "result": "accepted",
    "external_id": "LEAD-2210",
    "status": "RECEIVED"
}

🟢202

🟠400

🟠401

🟠403

🟠429

🔴500