Saltar al contenido principal
El endpoint Create Lead le permite añadir nuevos leads a su espacio de trabajo de AgencyHandy mediante programación desde cualquier sistema externo — un formulario web, un CRM, una plataforma de automatización de marketing o un script personalizado. Los leads creados a través de este endpoint aparecen en su pipeline de leads de inmediato, igual que si se hubieran añadido manualmente.
Antes de usar este endpoint, complete la guía Getting Started para obtener su clave de API y su Company ID. También necesita obtener su Client Role ID, que es obligatorio al crear un lead.

​
Requisitos previos

  • ✅ Clave de API generada desde Workspace Config → API Key
  • ✅ Company ID obtenido de GET {{URL}}/accounts/companies
  • ✅ Client Role ID obtenido (vea el Paso 1 a continuación)

​
Paso 1: Obtener el Client Role ID

Antes de crear un lead, necesita el Role ID del rol client en su empresa.

​
Endpoint

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

​
Encabezados

EncabezadoValor
x-api-keySu clave de API
companyidSu Company ID

​
Solicitud de ejemplo

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

​
Respuesta de ejemplo

{
  "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"
    }
  ]
}
Busque la entrada donde roles[0].role.name === "client" y extraiga el _id externo — es decir, roles[0]._id, no roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Use roles[0]._id (el ID de la asignación empresa-rol), no roles[0].role._id (el ID de la definición del rol). Usar el ID incorrecto hace que la solicitud de creación de lead falle.

​
Paso 2: Crear un nuevo lead

​
Endpoint

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

​
Encabezados

EncabezadoValor
x-api-keySu clave de API
companyidSu Company ID
Content-Typeapplication/json

​
Cuerpo de la solicitud

El cuerpo de la solicitud es un array JSON — puede crear uno o más leads en una sola llamada.
​
firstName
string
requerido
El nombre del lead.
​
lastName
string
requerido
El apellido del lead.
​
email
string
requerido
La dirección de correo electrónico del lead. Debe ser única dentro de su espacio de trabajo.
​
role
string
requerido
El Client Role ID obtenido en el Paso 1 (es decir, roles[0]._id).
​
isConvertedClient
boolean
requerido
Debe establecerse en false al crear un lead. Establézcalo en true solo al convertir un lead en un cliente completo.
​
status
string
El estado del lead en el pipeline. Valores comunes: New, Contacted, Qualified. Por defecto es New si se omite.
​
contactNo
string
El número de teléfono del lead.
​
source
string
Cómo adquirió este lead. Valores de ejemplo: website, referral, social.
​
positionInBoard
number
La posición (orden) del lead dentro de la columna del tablero del pipeline. Por defecto es 1.

​
Solicitud de ejemplo

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
    }
  ]'

​
Respuesta de éxito

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Cadena de confirmación: "Lead created successfully".
​
createdMembers
array
Array de objetos de lead creados.
​
createdMembers[].\_id
string
El ID único del lead recién creado. Guárdelo si necesita hacer referencia al lead en llamadas posteriores a la API.
​
createdMembers[].name
string
El nombre completo del lead (firstName + lastName).
​
createdMembers[].status
string
El estado del lead en el pipeline tal como se almacenó.
​
createdMembers[].role
string
El nombre del rol asignado al miembro — será "client".
Puede pasar varios objetos de lead en el array para crear varios leads en una sola llamada a la API. Cada objeto debe incluir todos los campos requeridos con su propia dirección de correo electrónico única.