API-toegang #

Een API (Application Programming Interface) is een manier voor verschillende softwaresystemen om met elkaar te communiceren. De Your AI Connector API stelt u (of uw ontwikkelaar) in staat om automatisch contacten aan te maken, berichten te versturen, lijsten te beheren en inkomende berichten van aangepaste kanalen te ontvangen — allemaal zonder het dashboard te gebruiken.

Waarom de API gebruiken? Als je de app wilt koppelen aan een tool die geen ingebouwde integratie heeft, of als je repetitieve taken op grote schaal wilt automatiseren, dan is de API de juiste weg.

Uw API-sleutel genereren #

1. Klik in de linkerzijbalk op Instellingen (tandwielpictogram).
2. Klik in de zijbalk van Instellingen, onder de groep Integraties, op API-sleutel.

3. Als je nog geen sleutel hebt, klik dan op API-sleutel genereren.
4. Als je er al een hebt, wordt deze gemaskeerd weergegeven onder Jouw sleutel. Als je sleutel dit ondersteunt, klik dan op Tonen om deze zichtbaar te maken en vervolgens op Kopiëren om deze te kopiëren — je ziet een bevestigingsmelding.
5. Bewaar de sleutel op een veilige plek — je hebt deze nodig voor elk API-verzoek.

Teamleden: de API-sleutel behoort toe aan de accounteigenaar. Als je bent aangemeld als een uitgenodigd teamlid (inclusief een beheerder), toont de sectie een opmerking in plaats van de sleutel. Meld je aan als de accounteigenaar om deze te bekijken, kopiëren of opnieuw te genereren — dit geldt ook voor scoped sleutels.

Waar vind je het: API-sleutel is een eigen sectie onder Instellingen → Integraties, los van Webhooks. Als een handleiding of een collega je vertelt om onder “Webhooks” naar de sleutel te zoeken, kijk dan in plaats daarvan in de sectie ernaast.

Bereikgebonden sleutels: extra sleutels voor één taak #

Uw hoofdsleutel kan alles, dus dit is niet de sleutel die u moet verstrekken voor een rapport, een klantendashboard of een afzonderlijke sandbox- en ontwikkelomgeving. Maak hiervoor bereikgebonden sleutels aan in de kaart Bereikgebonden sleutels, in dezelfde sectie API-sleutel onder Uw sleutel:

1. Klik op Nieuwe sleutel.
2. Geef deze een Naam die u later herkent, bijvoorbeeld “Sandbox” of “Acme klantendashboard”.
3. Vink onder Wat deze kan zien alleen de gebieden aan die nodig zijn.
4. Laat onder Wat deze kan doen de optie Alleen-lezen geselecteerd, tenzij de tool wijzigingen moet kunnen aanbrengen. Een sleutel die wijzigingen kan aanbrengen, kan berichten versturen en uw configuratie bewerken.
5. Stel optioneel Verzoeken per minuut in (een eigen limiet, zodat deze nooit uw andere integraties vertraagt) en een Vervaldatum.
6. Klik op Sleutel aanmaken en kopieer deze direct. Bereikgebonden sleutels worden slechts één keer getoond; als u er een verliest, trekt u deze in en maakt u een nieuwe aan.

U kunt er zoveel aanmaken als u nodig heeft. Elke sleutel in de lijst toont wanneer deze voor het laatst is gebruikt, en met Sleutel intrekken stopt de werking ervan onmiddellijk. Het aanmaken of intrekken van een bereikgebonden sleutel heeft nooit invloed op uw hoofdsleutel. De volledige opties, inclusief sleutels die beperkt zijn tot specifieke subaccounts, vindt u op de pagina API-sleutels in de API-referentie.

Basis-URL #

Alle API-verzoeken gebruiken het volgende basiswebadres:

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

Authenticatie #

Elk verzoek moet je API-sleutel bevatten zodat het platform weet dat jij het bent. De eenvoudigste manier is om deze toe te voegen aan het einde van het webadres:

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

U kunt de sleutel ook als verzoekheader verzenden in plaats van in de URL (aanbevolen voor productie, zodat de sleutel niet in serverlogboeken terechtkomt):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Alle verzoeken moeten een beveiligde verbinding (HTTPS) gebruiken. Onbeveiligde (HTTP) verzoeken worden afgewezen.

Op zoek naar de volledige ontwikkelaarsgidsen? Deze pagina is een korte introductie die de meest voorkomende bewerkingen behandelt. Voor volledige, stapsgewijze handleidingen — elke resource, met cURL-, JavaScript- en Python-voorbeelden — zie Aan de slag met de API en de API-referentie.

Veelvoorkomende API-bewerkingen #

Een contact aanmaken #

Verzoek:

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"
}

Verplichte velden: een phoneNumber (met landcode) is altijd vereist om een contact aan te maken. Een e-mailadres alleen is niet voldoende — een verzoek zonder geldig telefoonnummer wordt afgewezen. Het e-mailadres is optioneel.

Antwoord:

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

Sla data.contactId op — je hebt dit nodig voor de “Een contact toevoegen aan een lijst”-aanroep.

Een contact toevoegen aan een lijst #

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

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

Zoek de ID van een lijst in de app onder Contacten → Lijsten, via het menu van de rij van een lijst (Lijst-ID kopiëren).

Een contact bijwerken #

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

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

Alleen de velden die je opneemt, worden gewijzigd. Dit is ook de manier om aangepaste veldwaarden in bulk te laden na een import — zie Aangepaste velden, Leadprofiel & Notities. Volledige details in de Contacts API.

Een bericht versturen (Aangepast kanaal) #

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"
  }
}

Inkomende berichten ontvangen (Aangepast kanaal) #

Accepteer berichten van externe systemen als een aangepast kanaal. Dit is hoe integraties zoals GoHighLevel berichten naar Your AI Connector sturen. Zie Aangepaste kanalen voor alle details.

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"
}

Overzicht van beschikbare bewerkingen #

Snelheidsbeperkingen (Rate Limiting) #

De API dwingt snelheidslimieten af om de stabiliteit van het platform te waarborgen. Het overschrijden van uw limiet resulteert in 429 Too Many Requests — wacht even en probeer het opnieuw na de tijd die wordt aangegeven in de antwoordheaders. Gebruik voor gebruikssituaties met een hoog volume (bulk-imports) de ingebouwde importfunctie of stuur een e-mail naar hi@youraiconnector.com voor begeleiding.

Best practices #

• Bewaar uw API-sleutel veilig — gebruik een wachtwoordbeheerder of server-side configuratie, nooit client-side code die een bezoeker van de browser zou kunnen lezen.
• Voeg altijd de landcode toe aan telefoonnummers (+1 voor de VS, +44 voor het VK, +31 voor Nederland).
• Ga zorgvuldig om met fouten — controleer statuscodes en lees eventuele foutmeldingen die worden geretourneerd.
• Ga om met dubbele gegevens — een dubbel telefoonnummer retourneert { "success": false, "error_code": 409 } in plaats van een nieuwe contactpersoon, met het ID van de bestaande contactpersoon in contactId.
• Test met een kleine dataset voordat u bulkbewerkingen uitvoert.

Foutmeldingen #

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

Volgende stappen #

• Webhooks — ontvang realtime meldingen van de app (een apart gedeelte van uw API-sleutel).
• AI-assistenten verbinden (MCP) — gebruik dezelfde API-sleutel om Claude uw account te laten aansturen.
• Facebook Lead-formulieren — gebruik de API met automatiseringsplatforms om leads vast te leggen.
• GoHighLevel-integratie — een volledig tweerichtings-API-integratievoorbeeld.