Saltar para o conteúdo principal
O endpoint Criar Lead permite-lhe adicionar programaticamente novos leads ao seu workspace AgencyHandy a partir de qualquer sistema externo — um formulário web, um CRM, uma plataforma de automação de marketing ou um script personalizado. Os leads criados através deste endpoint aparecem imediatamente no seu pipeline de leads, tal como se tivessem sido adicionados manualmente.
Antes de utilizar este endpoint, complete o guia de Primeiros Passos para obter a sua chave de API e ID de Empresa. Também precisa de obter o seu ID de Função de Cliente, que é necessário ao criar um lead.

​
Pré-requisitos

  • ✅ Chave de API gerada em Configuração do Workspace → Chave de API
  • ✅ ID de Empresa obtido a partir de GET {{URL}}/accounts/companies
  • ✅ ID de Função de Cliente obtido (ver Passo 1 abaixo)

​
Passo 1: Obter o ID de Função de Cliente

Antes de criar um lead, precisa do ID de Função para a função client na sua empresa.

​
Endpoint

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

​
Cabeçalhos

CabeçalhoValor
x-api-keyA sua chave de API
companyidO seu ID de Empresa

​
Exemplo de pedido

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 exterior — ou seja, roles[0]._id, não roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Utilize roles[0]._id (o ID de mapeamento empresa-função), não roles[0].role._id (o ID de definição de função). Utilizar o ID errado faz com que o pedido de criação do lead falhe.

​
Passo 2: Criar um novo lead

​
Endpoint

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

​
Cabeçalhos

CabeçalhoValor
x-api-keyA sua chave de API
companyidO seu ID de Empresa
Content-Typeapplication/json

​
Corpo do pedido

O corpo do pedido é um array JSON — pode criar um ou mais leads numa única chamada.
​
firstName
string
obrigatório
O primeiro nome do lead.
​
lastName
string
obrigatório
O apelido do lead.
​
email
string
obrigatório
O endereço de e-mail do lead. Deve ser único no seu workspace.
​
role
string
obrigatório
O ID de Função de Cliente obtido 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 num cliente completo.
​
status
string
O estado do lead no pipeline. Valores comuns: New, Contacted, Qualified. Predefinição para New se omitido.
​
contactNo
string
O número de telefone do lead.
​
source
string
Como adquiriu este lead. Valores de exemplo: website, referral, social.
​
positionInBoard
number
A posição (ordem) do lead na coluna do quadro do pipeline. Predefinição para 1.

​
Exemplo de pedido

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
Texto 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. Guarde-o se precisar de referenciar o lead em chamadas de API subsequentes.
​
createdMembers[].name
string
O nome completo do lead (firstName + lastName).
​
createdMembers[].status
string
O estado do lead no pipeline tal como armazenado.
​
createdMembers[].role
string
O nome da função atribuída ao membro — será "client".
Pode passar múltiplos objetos de lead no array para criar vários leads numa única chamada à API. Cada objeto deve incluir todos os campos obrigatórios com o seu próprio endereço de e-mail único.