Zum Hauptinhalt springen
Der Endpunkt „Lead erstellen“ ermöglicht es Ihnen, neue Leads aus jedem externen System — einem Webformular, einem CRM, einer Marketing-Automatisierungsplattform oder einem benutzerdefinierten Skript — programmgesteuert zu Ihrem AgencyHandy-Workspace hinzuzufügen. Über diesen Endpunkt erstellte Leads erscheinen sofort in Ihrer Lead-Pipeline, genau wie wenn sie manuell hinzugefügt worden wären.
Bevor Sie diesen Endpunkt verwenden, schließen Sie den Leitfaden Erste Schritte ab, um Ihren API-Schlüssel und Ihre Unternehmens-ID zu erhalten. Sie müssen außerdem Ihre Kunden-Rollen-ID abrufen, die beim Erstellen eines Leads erforderlich ist.

​
Voraussetzungen

  • ✅ API-Schlüssel generiert aus Workspace-Konfiguration → API-Schlüssel
  • ✅ Unternehmens-ID abgerufen aus GET {{URL}}/accounts/companies
  • ✅ Kunden-Rollen-ID abgerufen (siehe Schritt 1 unten)

​
Schritt 1: Kunden-Rollen-ID abrufen

Bevor Sie einen Lead erstellen, benötigen Sie die Rollen-ID für die client-Rolle in Ihrem Unternehmen.

​
Endpunkt

GET {{URL}}/roles?type=company
HeaderWert
x-api-keyIhr API-Schlüssel
companyidIhre Unternehmens-ID

​
Beispielanfrage

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

​
Beispielantwort

{
  "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"
    }
  ]
}
Suchen Sie den Eintrag, bei dem roles[0].role.name === "client" gilt, und extrahieren Sie die äußere _id — das ist roles[0]._id, nicht roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
Verwenden Sie roles[0]._id (die Unternehmensrollen-Zuordnungs-ID), nicht roles[0].role._id (die Rollendefinitions-ID). Die Verwendung der falschen ID führt dazu, dass die Lead-Erstellungsanfrage fehlschlägt.

​
Schritt 2: Neuen Lead erstellen

​
Endpunkt

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

​
Header

HeaderWert
x-api-keyIhr API-Schlüssel
companyidIhre Unternehmens-ID
Content-Typeapplication/json

​
Anfrage-Body

Der Anfrage-Body ist ein JSON-Array — Sie können einen oder mehrere Leads in einem einzigen Aufruf erstellen.
​
firstName
string
erforderlich
Der Vorname des Leads.
​
lastName
string
erforderlich
Der Nachname des Leads.
​
email
string
erforderlich
Die E-Mail-Adresse des Leads. Muss innerhalb Ihres Workspaces eindeutig sein.
​
role
string
erforderlich
Die in Schritt 1 abgerufene Kunden-Rollen-ID (d. h. roles[0]._id).
​
isConvertedClient
boolean
erforderlich
Muss beim Erstellen eines Leads auf false gesetzt werden. Nur auf true setzen, wenn ein Lead in einen vollständigen Kunden umgewandelt wird.
​
status
string
Der Pipeline-Status des Leads. Häufige Werte: New, Contacted, Qualified. Standardmäßig New, wenn nicht angegeben.
​
contactNo
string
Die Telefonnummer des Leads.
​
source
string
Wie Sie diesen Lead gewonnen haben. Beispielwerte: website, referral, social.
​
positionInBoard
number
Die Position (Reihenfolge) des Leads in der Pipeline-Board-Spalte. Standardmäßig 1.

​
Beispielanfrage

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

​
Erfolgsantwort

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Bestätigungszeichenfolge: "Lead created successfully".
​
createdMembers
array
Array der erstellten Lead-Objekte.
​
createdMembers[].\_id
string
Die eindeutige ID des neu erstellten Leads. Speichern Sie diese, wenn Sie den Lead in nachfolgenden API-Aufrufen referenzieren müssen.
​
createdMembers[].name
string
Der vollständige Name des Leads (Vorname + Nachname).
​
createdMembers[].status
string
Der gespeicherte Pipeline-Status des Leads.
​
createdMembers[].role
string
Der dem Mitglied zugewiesene Rollenname — wird "client" sein.
Sie können mehrere Lead-Objekte im Array übergeben, um mehrere Leads in einem einzigen API-Aufruf zu erstellen. Jedes Objekt muss alle Pflichtfelder mit einer eigenen eindeutigen E-Mail-Adresse enthalten.