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.

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 #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Best Practices #

• Speichern Sie Ihren API-Schlüssel sicher – in einem Passwort-Manager oder einer serverseitigen Konfiguration, niemals in clientseitigem Code, den ein Website-Besucher lesen könnte.
• Geben Sie immer die Ländervorwahl 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.
• Behandeln Sie Duplikate – eine doppelte Telefonnummer gibt { "success": false, "error_code": 409 } anstelle eines neuen Kontakts zurück. Suchen Sie zuerst nach dem Kontakt, wenn Sie mit ihm arbeiten müssen.
• 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.