Pular para o conteúdo principal
O endpoint Criar Lead permite que você adicione novos leads programaticamente ao seu workspace do AgencyHandy a partir de qualquer sistema externo — um formulário web, um CRM, uma plataforma de automação de marketing ou um script personalizado. Leads criados via este endpoint aparecem em seu pipeline de leads imediatamente, como se tivessem sido adicionados manualmente.
Antes de usar este endpoint, conclua o guia de Primeiros Passos para obter sua chave de API e ID de Empresa. Você também precisa buscar o ID do Perfil de Cliente, que é obrigatório ao criar um lead.

​
Pré-requisitos

  • ✅ Chave de API gerada em Configuração do Workspace → Chave de API
  • ✅ ID de Empresa recuperado de GET {{URL}}/accounts/companies
  • ✅ ID do Perfil de Cliente recuperado (veja o Passo 1 abaixo)

​
Passo 1: Obter o ID do Perfil de Cliente

Antes de criar um lead, você precisa do ID do perfil para o perfil client na sua empresa.

​
Endpoint

GET {{URL}}/roles?type=company

​
Headers

HeaderValor
x-api-keySua chave de API
companyidSeu ID de Empresa

​
Exemplo de requisição

cURL
curl --request GET "https://api.agencyhandy.com/roles?type=company" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>"

​
Exemplo de resposta

{
  "roles": [
    {
      "_id": "6525994184e9ddd798534535",
      "role": {
        "_id": "6525994184e9ddd79853451e",
        "responsibility": "",
        "name": "client"
      },
      "company": "6525994184e9ddd79853450e",
      "createdAt": "2023-10-10T18:34:41.567Z",
      "updatedAt": "2024-10-01T07:28:48.340Z",
      "__v": 0,
      "type": "company"
    }
  ]
}
Encontre a entrada onde roles[0].role.name === "client" e extraia o _id externo — que é roles[0]._id, não roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Use roles[0]._id (o ID do mapeamento empresa-perfil), não roles[0].role._id (o ID da definição do perfil). Usar o ID errado faz com que a requisição de criação de lead falhe.

​
Passo 2: Criar um novo lead

​
Endpoint

POST {{URL}}/members/bulk-lead

​
Headers

HeaderValor
x-api-keySua chave de API
companyidSeu ID de Empresa
Content-Typeapplication/json

​
Corpo da requisição

O corpo da requisição é um array JSON — você pode criar um ou mais leads em uma única chamada.
​
firstName
string
obrigatório
O primeiro nome do lead.
​
lastName
string
obrigatório
O sobrenome do lead.
​
email
string
obrigatório
O endereço de e-mail do lead. Deve ser único dentro do seu workspace.
​
role
string
obrigatório
O ID do Perfil de Cliente recuperado no Passo 1 (ou seja, roles[0]._id).
​
isConvertedClient
boolean
obrigatório
Deve ser definido como false ao criar um lead. Defina como true apenas ao converter um lead em um cliente completo.
​
status
string
O status do lead no pipeline. Valores comuns: New, Contacted, Qualified. Padrão: New se omitido.
​
contactNo
string
O número de telefone do lead.
​
source
string
Como você adquiriu este lead. Exemplos de valores: website, referral, social.
​
positionInBoard
number
A posição (ordem) do lead dentro da coluna do quadro do pipeline. Padrão: 1.

​
Exemplo de requisição

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "role": "6525994184e9ddd798534535",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
Resposta de sucesso

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
String de confirmação: "Lead created successfully".
​
createdMembers
array
Array de objetos de lead criados.
​
createdMembers[].\_id
string
O ID único do lead recém-criado. Armazene-o se precisar referenciar o lead em chamadas de API subsequentes.
​
createdMembers[].name
string
O nome completo do lead (firstName + lastName).
​
createdMembers[].status
string
O status do lead no pipeline conforme armazenado.
​
createdMembers[].role
string
O nome do perfil atribuído ao membro — será "client".
Você pode passar múltiplos objetos de lead no array para criar vários leads em uma única chamada de API. Cada objeto deve incluir todos os campos obrigatórios com seu próprio endereço de e-mail único.