API-Zugriff #

Eine API (Application Programming Interface) ist eine Möglichkeit für verschiedene Softwaresysteme, miteinander zu kommunizieren. Die Your AI Connector API ermöglicht es Ihnen (oder Ihrem Entwickler), automatisch Kontakte zu erstellen, Nachrichten zu senden, Listen zu verwalten und eingehende Nachrichten von benutzerdefinierten Kanälen zu empfangen — alles ohne das Dashboard zu verwenden.

Warum die API verwenden? Wenn Sie die App mit einem Tool verbinden möchten, das keine integrierte Schnittstelle besitzt, oder wenn Sie sich wiederholende Aufgaben in großem Maßstab automatisieren müssen, ist die API der richtige Weg.

Generieren Ihres API-Schlüssels #

1. Klicken Sie in der linken Seitenleiste auf Einstellungen (Zahnradsymbol).
2. Klicken Sie in der Einstellungs-Seitenleiste unter der Gruppe Integrationen auf API-Schlüssel.

3. Falls Sie noch keinen Schlüssel haben, klicken Sie auf API-Schlüssel generieren.
4. Falls Sie bereits einen haben, wird dieser maskiert unter Ihr Schlüssel angezeigt. Wenn Ihr Schlüssel dies unterstützt, klicken Sie auf Anzeigen, um ihn sichtbar zu machen, und dann auf Kopieren, um ihn zu kopieren – Sie erhalten eine Bestätigungsmeldung.
5. Bewahren Sie den Schlüssel an einem sicheren Ort auf – Sie benötigen ihn für jede API-Anfrage.

Teammitglieder: Der API-Schlüssel gehört dem Kontoinhaber. Wenn Sie als eingeladenes Teammitglied (einschließlich eines Administrators) angemeldet sind, zeigt der Bereich anstelle des Schlüssels einen Hinweis an. Melden Sie sich als Kontoinhaber an, um ihn anzuzeigen, zu kopieren oder neu zu generieren – dies gilt auch für bereichsbezogene Schlüssel.

Wo Sie ihn finden: API-Schlüssel ist ein eigener Bereich unter Einstellungen → Integrationen, getrennt von Webhooks. Wenn eine Anleitung oder ein Kollege Ihnen sagt, Sie sollen unter “Webhooks” nach dem Schlüssel suchen, schauen Sie stattdessen im Bereich daneben.

Bereichsbezogene Schlüssel: zusätzliche Schlüssel für eine bestimmte Aufgabe #

Ihr Hauptschlüssel kann alles, daher ist er nicht der richtige Schlüssel für einen Bericht, ein Kunden-Dashboard oder eine separate Sandbox- und Entwicklungsumgebung. Erstellen Sie dafür bereichsbezogene Schlüssel (Scoped keys) in der Karte Bereichsbezogene Schlüssel, im selben Bereich API-Schlüssel unterhalb von Ihr Schlüssel:

1. Klicken Sie auf Neuer Schlüssel.
2. Geben Sie ihm einen Namen, den Sie später wiedererkennen, zum Beispiel “Sandbox” oder “Acme Kunden-Dashboard”.
3. Markieren Sie unter Was er sehen kann nur die Bereiche, die er benötigt.
4. Belassen Sie es unter Was er tun kann bei Nur lesen, es sei denn, das Tool muss Änderungen vornehmen. Ein Schlüssel, der Änderungen vornehmen kann, kann Nachrichten senden und Ihre Konfiguration bearbeiten.
5. Legen Sie optional Anfragen pro Minute (ein eigenes Limit, damit Ihre anderen Integrationen nicht verlangsamt werden) und ein Ablaufdatum fest.
6. Klicken Sie auf Schlüssel erstellen und kopieren Sie ihn sofort. Bereichsbezogene Schlüssel werden nur einmal angezeigt; wenn Sie einen verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.

Sie können so viele erstellen, wie Sie benötigen. Jeder Schlüssel in der Liste zeigt an, wann er zuletzt verwendet wurde, und Schlüssel widerrufen stoppt seine Funktion sofort. Das Erstellen oder Widerrufen eines bereichsbezogenen Schlüssels hat keinerlei Auswirkungen auf Ihren Hauptschlüssel. Die vollständigen Optionen, einschließlich Schlüsseln, die auf bestimmte Unterkonten beschränkt sind, finden Sie auf der Seite API-Schlüssel in der API-Referenz.

Basis-URL #

Alle API-Anfragen verwenden die folgende Web-Basisadresse:

https://api.youraiconnector.com/v1/

Authentifizierung #

Jede Anfrage muss Ihren API-Schlüssel enthalten, damit die Plattform weiß, dass Sie es sind. Der einfachste Weg ist, ihn an das Ende der Webadresse anzuhängen:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Sie können den Schlüssel auch als Anfrage-Header anstelle der URL senden (empfohlen für die Produktion, damit der Schlüssel nicht in Server-Logs landet):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Alle Anfragen müssen eine sichere Verbindung (HTTPS) verwenden. Unsichere (HTTP) Anfragen werden abgelehnt.

Suchen Sie nach den vollständigen Entwicklerhandbüchern? Diese Seite ist eine kurze Einführung, die die häufigsten Vorgänge abdeckt. Für vollständige Schritt-für-Schritt-Anleitungen – zu jeder Ressource, mit cURL-, JavaScript- und Python-Beispielen – siehe Erste Schritte mit der API und die API-Referenz.

Häufige API-Operationen #

Einen Kontakt erstellen #

Anfrage:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Erforderliche Felder: Eine phoneNumber (mit Ländervorwahl) ist immer erforderlich, um einen Kontakt zu erstellen. Eine E-Mail-Adresse allein reicht nicht aus – eine Anfrage ohne gültige Telefonnummer wird abgelehnt. Die E-Mail-Adresse ist optional.

Antwort:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Speichern Sie data.contactId – Sie benötigen sie für den Aufruf “Einen Kontakt zu einer Liste hinzufügen”.

Kontakt zu einer Liste hinzufügen #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Die ID einer Liste finden Sie in der App unter Kontakte → Listen im Menü der jeweiligen Liste (Listen-ID kopieren).

Einen Kontakt aktualisieren #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Nur die Felder, die Sie einbeziehen, werden geändert. Dies ist auch die Methode, um benutzerdefinierte Feldwerte nach einem Import massenhaft zu laden – siehe Benutzerdefinierte Felder, Lead-Profil & Notizen. Alle Details finden Sie in der Kontakte-API.

Nachricht senden (Benutzerdefinierter Kanal) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Eingehende Nachrichten empfangen (Benutzerdefinierter Kanal) #

Akzeptieren Sie Nachrichten von externen Systemen als benutzerdefinierten Kanal. Auf diese Weise senden Integrationen wie GoHighLevel Nachrichten an Your AI Connector. Weitere Informationen finden Sie unter Benutzerdefinierte Kanäle.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Übersicht der verfügbaren Vorgänge #

Ratenbegrenzung #

Die API erzwingt Ratenbegrenzungen, um die Plattformstabilität zu gewährleisten. Das Überschreiten Ihres Limits führt zur Rückgabe von 429 Too Many Requests — halten Sie inne und versuchen Sie es nach der in den Antwort-Headern angegebenen Zeit erneut. Für Anwendungsfälle mit hohem Volumen (Massenimporte) verwenden Sie die integrierte Import-Funktion oder senden Sie eine E-Mail an hi@youraiconnector.com, um Unterstützung zu erhalten.

Best Practices #

• Bewahren Sie Ihren API-Schlüssel sicher auf — verwenden Sie einen Passwort-Manager oder eine serverseitige Konfiguration, niemals clientseitigen Code, den ein Browser-Besucher lesen könnte.
• Geben Sie immer die Landesvorwahl bei Telefonnummern an (+1 für die USA, +44 für Großbritannien, +31 für die Niederlande).
• Behandeln Sie Fehler ordnungsgemäß — prüfen Sie Statuscodes und lesen Sie alle zurückgegebenen Fehlermeldungen.
• Gehen Sie mit Duplikaten um — eine doppelte Telefonnummer gibt { "success": false, "error_code": 409 } anstelle eines neuen Kontakts zurück, wobei die ID des bestehenden Kontakts in contactId enthalten ist.
• Testen Sie mit einem kleinen Datensatz, bevor Sie Massenvorgänge ausführen.

Fehlerantworten #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Nächste Schritte #

• Webhooks – erhalten Sie Echtzeit-Benachrichtigungen aus der App (ein separater Bereich von Ihrem API-Schlüssel).
• KI-Assistenten verbinden (MCP) – verwenden Sie denselben API-Schlüssel, damit Claude Ihr Konto steuert.
• Facebook Lead-Formulare – verwenden Sie die API mit Automatisierungsplattformen, um Leads zu erfassen.
• GoHighLevel-Integration – ein Beispiel für eine vollständige Zwei-Wege-API-Integration.