Passer au contenu principal
Le point de terminaison Create Lead vous permet d’ajouter par programmation de nouveaux leads à votre espace de travail AgencyHandy depuis n’importe quel système externe — un formulaire web, un CRM, une plateforme d’automatisation marketing ou un script personnalisé. Les leads créés via ce point de terminaison apparaissent immédiatement dans votre pipeline de leads, exactement comme s’ils avaient été ajoutés manuellement.
Avant d’utiliser ce point de terminaison, suivez le guide Getting Started pour obtenir votre clé API et votre Company ID. Vous devez également récupérer votre Client Role ID, requis lors de la création d’un lead.

​
Prérequis

  • ✅ Clé API générée depuis Workspace Config → API Key
  • ✅ Company ID récupéré depuis GET {{URL}}/accounts/companies
  • ✅ Client Role ID récupéré (voir l’étape 1 ci-dessous)

​
Étape 1 : obtenir le Client Role ID

Avant de créer un lead, vous avez besoin du Role ID du rôle client dans votre entreprise.

​
Point de terminaison

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

​
En-têtes

En-têteValeur
x-api-keyVotre clé API
companyidVotre Company ID

​
Exemple de requête

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

​
Exemple de réponse

{
  "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"
    }
  ]
}
Repérez l’entrée où roles[0].role.name === "client" et extrayez le _id externe — c’est-à-dire roles[0]._id, et non roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Utilisez roles[0]._id (l’ID de mappage rôle-entreprise), et non roles[0].role._id (l’ID de définition du rôle). Utiliser le mauvais ID fait échouer la requête de création du lead.

​
Étape 2 : créer un nouveau lead

​
Point de terminaison

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

​
En-têtes

En-têteValeur
x-api-keyVotre clé API
companyidVotre Company ID
Content-Typeapplication/json

​
Corps de la requête

Le corps de la requête est un tableau JSON — vous pouvez créer un ou plusieurs leads en un seul appel.
​
firstName
string
requis
Le prénom du lead.
​
lastName
string
requis
Le nom de famille du lead.
​
email
string
requis
L’adresse e-mail du lead. Doit être unique au sein de votre espace de travail.
​
role
string
requis
Le Client Role ID récupéré à l’étape 1 (c’est-à-dire roles[0]._id).
​
isConvertedClient
boolean
requis
Doit être défini sur false lors de la création d’un lead. Définissez-le sur true uniquement lors de la conversion d’un lead en client à part entière.
​
status
string
Le statut du lead dans le pipeline. Valeurs courantes : New, Contacted, Qualified. Par défaut New si omis.
​
contactNo
string
Le numéro de téléphone du lead.
​
source
string
Comment vous avez acquis ce lead. Exemples de valeurs : website, referral, social.
​
positionInBoard
number
La position (ordre) du lead dans la colonne du tableau du pipeline. Par défaut 1.

​
Exemple de requête

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

​
Réponse de succès

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Chaîne de confirmation : "Lead created successfully".
​
createdMembers
array
Tableau des objets lead créés.
​
createdMembers[].\_id
string
L’ID unique du lead nouvellement créé. Conservez-le si vous devez référencer le lead dans des appels API ultérieurs.
​
createdMembers[].name
string
Le nom complet du lead (firstName + lastName).
​
createdMembers[].status
string
Le statut du lead dans le pipeline tel qu’enregistré.
​
createdMembers[].role
string
Le nom du rôle attribué au membre — sera "client".
Vous pouvez transmettre plusieurs objets lead dans le tableau pour créer plusieurs leads en un seul appel API. Chaque objet doit inclure tous les champs requis avec sa propre adresse e-mail unique.