Leads von Partner-Agenturen
Wie die Marketing-Agentur eines Partners Leads direkt als Interessenten des Partners einsendet und für jeden sofort einen persönlichen Terminlink bekommt: Opt-in auf der eigenen Landingpage, dann Termin buchen ohne erneute Eingabe.
Der Ablauf
Die Agentur arbeitet mit einem Partner-Schlüssel, der an genau einen Partner (Affiliate) gebunden ist. Sie liest einmal die Definition des Formulars, sendet je Lead die Werte ein und bekommt in derselben Antwort die Kennung des Interessenten und, mit einer Terminart, den persönlichen Terminlink des Partners. Wer den Link öffnet, findet seine Angaben schon eingetragen und wählt nur noch einen Termin. Der Termin liegt beim Partner und seinem Team.
1. Partner-Schlüssel ausstellen
Ausstellen kann der Partner im Partner-Portal unter „Schnittstelle für meine Agentur“ oder ein Admin der Organisation in der Affiliate-Verwaltung am Partner. Beide sehen dieselben Schlüssel und können sie widerrufen. Name, optional Ablaufdatum und erlaubte IP-Adressen; der Schlüssel (capi_…) wird nur einmal angezeigt. Rotieren stellt einen neuen aus, der alte gilt noch 24 Stunden. Der Schlüssel ruft genau drei Endpunkte: GET /forms/{id}, POST /forms/{id}/responses und POST /appointment-types/{id}/partner-links. Er gilt nur, solange der Partner aktiv ist und die Organisation ihre Schnittstelle eingeschaltet hat; den MCP-Zugang nimmt er nicht. Die Kennungen der Formulare und Terminarten, die er nutzen darf, zeigt die Anleitung im Portal.
2. Formular lesen
GET /forms/{id} nennt die Felder (key, required, options), die Einwilligungen mit Kennung (elementId), Wortlaut (labelHtml) und Pflicht sowie die Seiten. Den Wortlaut der Einwilligungen zeigt die Landingpage der Agentur so, wie er hier steht: Nur dann ist die Einwilligung, die sie einsendet, auch eine. Mit einem Partner-Schlüssel kommen nur die Formulare, die für das Partner-Portal freigegeben sind und Interessenten anlegen; jedes andere antwortet 404. responseCount zählt nur die Einsendungen des eigenen Partners, publicUrl ist leer. Ändert die Organisation das Formular, ändert sich die Definition mit; ein erneutes Lesen vor einer Kampagne lohnt sich.
curl "https://www.claritos.io/api/v1/forms/<FORMULAR>?locale=de" \
-H "Authorization: Bearer capi_…"{
"id": "<FORMULAR>",
"fields": [
{ "key": "std:firstName", "required": true },
{ "key": "std:email", "required": true },
{ "key": "cf:interesse", "required": false, "options": [ … ] }
],
"consents": [
{ "elementId": "<EINWILLIGUNG>", "required": true, "labelHtml": "<p>Ich bin einverstanden, …</p>" }
]
}3. Lead einsenden, Terminlink in derselben Antwort
POST /forms/{id}/responses mit values (die keys aus Schritt 2) und consents (Kennung der Einwilligung auf true). Mit appointmentTypeId, einer Terminart, die für den Partner freigegeben ist, kommt der persönliche Terminlink gleich mit; senderContactId wählt optional, in wessen Namen er geht, sonst die zuständige Person des Interessenten oder der Inhaber des Partners. affiliateId muss nicht mitgehen: Der Schlüssel setzt seinen Partner selbst. Ein Idempotency-Key je Lead verhindert, dass ein wiederholter Aufruf den Lead zweimal anlegt. Scheitert nur der Terminlink, bleibt der Lead gespeichert: bookingUrl ist dann leer und bookingError nennt den Grund (prospect-without-contact, appointment-type-not-released-to-partner, sender-not-in-team, prospect-not-found, booking-failed). Ist die Person schon Interessent eines anderen Partners, gelten dieselben Regeln wie beim öffentlichen Formular.
curl -X POST https://www.claritos.io/api/v1/forms/<FORMULAR>/responses \
-H "Authorization: Bearer capi_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: <je Lead eindeutig>" \
-d '{ "values": { "std:firstName": "Anna", "std:lastName": "Muster", "std:email": "anna@example.com" },
"consents": { "<EINWILLIGUNG>": true },
"appointmentTypeId": "<TERMINART>" }'{
"id": "<EINSENDUNG>",
"prospectId": "<INTERESSENT>",
"contactId": "<KONTAKT>",
"affiliateId": "<PARTNER>",
"bookingUrl": "https://www.claritos.io/t/…",
"bookingError": null
}4. Terminlink später holen
Mit der Kennung aus der Antwort (prospectId) holt POST /appointment-types/{id}/partner-links den Link jederzeit wieder, auch für eine andere freigegebene Terminart. Gibt es ihn schon, kommt derselbe Link zurück.
curl -X POST https://www.claritos.io/api/v1/appointment-types/<TERMINART>/partner-links \
-H "Authorization: Bearer capi_…" -H "Content-Type: application/json" \
-d '{ "prospectId": "<INTERESSENT>" }'Fehler
401: Schlüssel widerrufen oder Partner nicht mehr aktiv; key-expired nach dem Ablaufdatum, auch 24 Stunden nach dem Rotieren. 403: ip-not-allowed, api-disabled (Schnittstelle der Organisation aus), forbidden mit reason partner-key-endpoint (anderer Endpunkt). 404: Formular nicht für Partner freigegeben. 422 validation-failed: an body.values.<key> oder body.consents.<kennung> für fehlende Pflichtangaben, an body.affiliateId mit Code partner-affiliate, wenn ein anderer Partner mitgeschickt wird, an body.prospectId mit Code not_found für einen unbekannten Interessenten oder den eines anderen Partners (beides sieht gleich aus). 422 precondition-failed beim Terminlink: prospect-without-contact, appointment-type-not-released-to-partner.
Mit einem Org-Schlüssel
Dieselben Endpunkte gehen auch mit einem Schlüssel der Organisation. affiliateId wählt dann den Partner, dem der Interessent gehört; appointmentTypeId beim Einsenden braucht zusätzlich appointments:write, und POST /appointment-types/{id}/partner-links braucht eine Person mit dem Recht, die Terminplanung zu verwalten. Für eine Agentur ist der Partner-Schlüssel der richtige Weg: Er kann nichts anderes.