Zum Hauptinhalt springen
Der Endpunkt „Kunden erstellen“ ermöglicht es Ihnen, Kunden direkt aus einem externen System zu Ihrem AgencyHandy-Workspace hinzuzufügen. Im Gegensatz zu Leads sind Kunden vollständig eingebundene Kontakte, die Bestellungen, Rechnungen und Projekten zugewiesen werden können. Verwenden Sie diesen Endpunkt, um neue Kunden aus einem CRM, einem Onboarding-Formular oder einer anderen Datenquelle zu synchronisieren.
Bevor Sie diesen Endpunkt verwenden, schließen Sie den Leitfaden Erste Schritte ab, um Ihren API-Schlüssel und Ihre Unternehmens-ID zu erhalten. Im Gegensatz zum Endpunkt „Lead erstellen“ erfordert das Erstellen eines Kunden keinen separaten Schritt zum Abrufen der Rollen-ID.

​
Voraussetzungen

  • ✅ API-Schlüssel generiert aus Workspace-Konfiguration → API-Schlüssel
  • ✅ Unternehmens-ID abgerufen aus GET {{URL}}/accounts/companies

​
Endpunkt

POST {{URL}}/members/bulk-client
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 Kunden in einer einzigen Anfrage erstellen.
​
firstName
string
erforderlich
Der Vorname des Kunden.
​
lastName
string
erforderlich
Der Nachname des Kunden.
​
email
string
erforderlich
Die E-Mail-Adresse des Kunden. Muss innerhalb Ihres Workspaces eindeutig sein.
​
isConvertedClient
boolean
erforderlich
Auf false setzen für einen völlig neuen Kunden. Auf true setzen, wenn ein bestehender Lead in einen Kunden umgewandelt wird.
​
status
string
Der Status des Kunden. Häufige Werte: New, Active. Standardmäßig New, wenn nicht angegeben.
​
contactNo
string
Die Telefonnummer des Kunden.
​
source
string
Wie Sie diesen Kunden gewonnen haben. Beispielwerte: website, referral, social.
​
positionInBoard
number
Die Position des Kunden in der Board-Spalte. Standardmäßig 1.

​
Beispielanfrage

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-client" \
  --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",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
Erfolgsantwort

{
  "message": "Client created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
Bestätigungszeichenfolge bei Erfolg.
​
createdMembers
array
Array der erstellten Kunden-Objekte.
​
createdMembers[].\_id
string
Eindeutige ID des neu erstellten Kunden. Verwenden Sie diese ID, wenn Sie den Kunden über die API Bestellungen oder Rechnungen zuweisen.
​
createdMembers[].name
string
Der vollständige Name des Kunden (Vorname + Nachname).
​
createdMembers[].status
string
Der gespeicherte Status des Kunden.
​
createdMembers[].role
string
Die dem Mitglied zugewiesene Rolle — wird "client" sein.
Der companyId-Header für diesen Endpunkt verwendet ein großes I in Id — companyId — im Gegensatz zu einigen anderen Endpunkten, die companyid (alles Kleinbuchstaben) verwenden. Verwenden Sie die exakte Groß-/Kleinschreibung wie oben angegeben, um Authentifizierungsfehler zu vermeiden.
Übergeben Sie mehrere Kunden-Objekte im Array, um Kunden in einem einzigen API-Aufruf massenweise zu erstellen. Jedes Objekt muss eine eindeutige email-Adresse haben. Doppelte E-Mail-Adressen führen für diesen Eintrag zu einem Validierungsfehler.