Team-API

Je team bestaat uit iedereen die naast jou in je account werkt — beheerders, medewerkers en kijkers met alleen-lezen toegang — plus de uitnodigingen die je hebt verstuurd en de afdelingen waarin je ze indeelt. De Team-API is de programmatische versie van Instellingen → Team: mensen toevoegen en verwijderen, instellen wat ieder van hen kan zien en doen, uitnodigingen versturen en opvolgen, en afdelingen beheren.

Alle onderstaande eindpunten zijn relatief ten opzichte van de basis-URL https://api.youraiconnector.com/v1. Zie Teambeheer voor de dashboardversie van alles op deze pagina.

Authenticatie: deze eindpunten vereisen een ingelogde persoon

Dit is het enige deel van de API dat niet met een API-sleutel kan worden gebruikt. Elk /team-eindpunt, behalve de afdelings-eindpunten, moet worden aangeroepen met een Firebase ID-token van een ingelogde sessie:

Authorization: Bearer <Firebase ID token>

Stuur een API-sleutel mee en het verzoek wordt afgewezen met een 401:

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

De reden hiervoor is dat deze eindpunten beslissen wat ze doen op basis van wie er is ingelogd: jouw rol, de limiet van wat je aan iemand anders mag toekennen, en of je momenteel in een ander account werkt. Een API-sleutel is een integratie, geen persoon, dus er is niemand op wie die regels van toepassing kunnen zijn.

In de praktijk betekent dit dat de Team-API bedoeld is voor een first-party app met een ingelogde Your AI Connector-gebruiker (zie Authenticatie → Firebase ID-token). Een server-to-server-integratie kan geen teamleden beheren — er is geen manier om een van deze tokens van buiten de app aan te maken.

De uitzondering: de vier afdelings-eindpunten zijn gewone API-eindpunten. Ze accepteren je API-sleutel precies zoals de rest van de API, evenals een ingelogde sessie.

Elk antwoord op deze pagina volgt de gebruikelijke envelop: success: true plus de velden van het eindpunt op het hoogste niveau, of success: false met error en error_code wanneer er iets misgaat.

Rollen en rechten

Elk teamlid heeft één rol, die de standaardtoegang bepaalt voor 12 onderdelen van de app. Je kunt vervolgens individuele onderdelen overschrijven.

Rol	Waarde	Samenvatting
Admin	`admin`	Alles behalve acties op factuurniveau van de eigenaar.
Editor	`editor`	Kan dingen maken en wijzigen. Wordt in de app weergegeven als Medewerker.
Viewer	`viewer`	Alleen-lezen.

Elk onderdeel is ingesteld op een van de vier niveaus: none (verborgen), view (alleen-lezen), edit (maken en wijzigen), full (inclusief verwijderen).

Onderdeel	Admin	Editor	Viewer
`campaigns`	full	edit	view
`contacts`	full	edit	view
`messages`	full	edit	view
`appointments`	full	edit	view
`settings`	edit	view	none
`billing`	edit	none	none
`team_management`	edit	none	none
`analytics`	full	view	view
`phone_numbers`	edit	none	none
`integrations`	edit	none	none
`faqs`	full	edit	view
`daily_summaries`	full	view	view

Om af te wijken van de standaardinstellingen van de rol, stuur je permission_overrides — een array van { "area": ..., "level": ... } objecten. Elke invoer vervangt de standaardinstelling van de rol voor dat specifieke gebied; alles wat je niet vermeldt, behoudt de standaardinstelling van de rol.

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

Wie kan deze endpoints aanroepen

De accounteigenaar kan altijd alles doen.
Een teamlid heeft team_management op view nodig om het rooster en de uitnodigingslijst te lezen, en op edit om toe te voegen, te wijzigen, op te schorten, te verwijderen, uit te nodigen, te annuleren of opnieuw te verzenden. Beheerders hebben standaard edit; editors en kijkers hebben none, dus standaard kunnen alleen beheerders het team beheren.
Niemand kan toegang verlenen die hoger is dan die van henzelf. Als je probeert iemand een niveau te geven dat je zelf niet hebt — of iemand te bewerken, op te schorten of te verwijderen wiens toegang al breder is dan die van jou — wordt het verzoek geweigerd met 403 en een bericht waarin het gebied wordt genoemd.

Het teamlid-object

GET /team/members retourneert er één per lid:

Veld	Type	Beschrijving
`member_uid`	string	De eigen gebruikers-ID van het lid. Dit is de `{memberUid}` in de onderstaande paden.
`account_owner_uid`	string	Het account waarvan ze lid zijn.
`member_email`	string	Hun e-mailadres.
`member_display_name`	string	De naam die voor hen in de app wordt weergegeven.
`role`	string	`admin`, `editor` of `viewer`.
`permission_overrides`	array	Hun uitzonderingen per gebied. `[]` wanneer ze puur op rol-standaarden staan.
`status`	string	`active` of `suspended`.
`auto_assign_enabled`	boolean \| null	Of nieuwe contacten automatisch aan hen kunnen worden toegewezen. `null` betekent nooit gewijzigd, wat zich gedraagt als `true`.
`created_by`	string	Wie hen heeft toegevoegd.
`created_at`	string \| null	ISO 8601-tijdstempel.
`updated_at`	string \| null	ISO 8601-tijdstempel.

Verwijderde leden worden niet geretourneerd — de lijst bevat alleen actieve en opgeschorte leden.

Zichtbaarheidslimieten zijn hier alleen-schrijven. contact_scope, contact_scope_axes en sub_account_access (zie Beperken wat een lid kan zien) kunnen worden ingesteld bij aanmaken, bijwerken en uitnodigen, maar dit endpoint retourneert ze niet.

Teamleden weergeven

GET /team/members

Retourneert het rooster plus de stoeltellingen van je abonnement, zodat je “3 van 5 stoelen” kunt tonen en weet wanneer uitnodigen op het punt staat te worden geweigerd.

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

Antwoord

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

seat_limit is null wanneer je abonnement geen stoellimiet heeft. seats_used telt alleen actieve leden — iemand opschorten of verwijderen maakt hun stoel onmiddellijk vrij.

Direct een teamlid toevoegen

POST /team/members

Zet iemand direct in je team, zonder uitnodiging.

Dit verstuurt geen e-mail. Niemand krijgt bericht dat ze zijn toegevoegd, en als ze nog geen Your AI Connector-login hadden, heeft het voor hen aangemaakte account geen wachtwoord, dus kunnen ze niet inloggen totdat ze het opnieuw instellen. Gebruik Stuur een uitnodiging tenzij je je eigen manier hebt om het de persoon te vertellen en hen te laten inloggen.

Aanvraagvelden

Veld	Vereist	Beschrijving
`email`	Ja	Het e-mailadres van het teamlid.
`display_name`	Ja	De naam die voor hen in de app wordt getoond.
`role`	Ja	`admin`, `editor` of `viewer`.
`permission_overrides`	Nee	Uitzonderingen per gebied op de standaardinstellingen van de rol.
`contact_scope`	Nee	`all` of `assigned` — zie Beperken wat een lid kan zien.
`contact_scope_unassigned`	Nee	Met `assigned`, laat hen ook contacten zien die nog door niemand worden beheerd.
`contact_scope_axes`	Nee	Beperk hen tot genoemde agenten, kanalen of afdelingen.
`sub_account_access`	Nee	Alleen voor bureaus — welke klant-subaccounts ze mogen openen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

Antwoord — 201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}

Status	Wanneer
`400`	`email`, `display_name` of `role` ontbreekt, de rol is niet een van de drie, of je hebt geprobeerd jezelf toe te voegen.
`403`	Je hebt geen toestemming om het team te beheren, of je hebt geprobeerd toegang te verlenen die verder gaat dan die van jezelf.
`409`	Die persoon is al een actief lid van je team.
`429`	De teamplaatsen van je abonnement zijn vol.

Iemand toevoegen die eerder geschorst of verwijderd was, herstelt hen in plaats van dat het mislukt.

Een teamlid bijwerken

PATCH /team/members/{memberUid}

Wijzigt de rol, rechten, zichtbaarheid, klanttoegang of deelname aan automatische contacttoewijzing van een lid. Stuur alleen de velden die je wilt wijzigen; alles wat je weglaat, behoudt zijn huidige waarde.

Aanvraagvelden

Veld	Beschrijving
`role`	`admin`, `editor` of `viewer`.
`permission_overrides`	Vervangt hun volledige lijst met overschrijvingen. Stuur `[]` om hen terug te zetten naar de pure standaardinstellingen van de rol.
`status`	Alleen `active` wordt geaccepteerd om een geschorst lid terug te halen. Gebruik het schorsings-eindpunt om iemand te schorsen.
`auto_assign_enabled`	`true` of `false`.
`contact_scope`	`all` of `assigned`.
`contact_scope_unassigned`	`true` of `false`.
`contact_scope_axes`	Zie Beperken wat een lid kan zien.
`sub_account_access`	Alleen voor bureaus.

Dit is het enige eindpunt waar null “wissen” betekent. Het sturen van "contact_scope": null, "contact_scope_axes": null of "sub_account_access": null verwijdert die beperking volledig en zorgt ervoor dat het lid weer alles kan zien. Bij aanmaken en uitnodigen betekent null simpelweg “niet opgegeven”.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

Antwoord

{
  "success": true,
  "message": "Team member updated successfully."
}

Status	Wanneer
`400`	Een ongeldige `status` of `auto_assign_enabled` waarde, of je hebt geprobeerd een lid te reactiveren dat was verwijderd (verwijderde leden moeten opnieuw worden uitgenodigd).
`403`	Je hebt geen toestemming, of de wijziging zou toegang bewerken of creëren die breder is dan die van jezelf.
`404`	Geen dergelijk teamlid.

Een teamlid schorsen

POST /team/members/{memberUid}/suspend

Schorst iemand: ze behouden hun plek in het team maar verliezen toegang. Gebruik dit in plaats van verwijderen wanneer de pauze tijdelijk is — haal ze terug met PATCH /team/members/{memberUid} en {"status": "active"}.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Antwoord

{
  "success": true,
  "message": "Team member suspended successfully."
}

Een geschorst lid maakt hun plek vrij, zodat je iemand anders in hun plaats kunt uitnodigen. Hun toegang eindigt wanneer hun huidige sessietoken de volgende keer ververst, wat tot een uur kan duren — verwijder ze in plaats daarvan als je wilt dat het onmiddellijk gebeurt.

Status	Wanneer
`400`	Je hebt geprobeerd de accounteigenaar te schorsen, of een lid dat al geschorst of verwijderd is.
`403`	Hun toegang is breder dan die van jou.
`404`	Geen dergelijk teamlid.

Een teamlid verwijderen

DELETE /team/members/{memberUid}

Verwijdert iemand uit je team en maakt hun licentie vrij. Ze worden uitgelogd en verliezen de toegang tot je account; hun eigen inloggegevens blijven ongewijzigd.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Antwoord

{
  "success": true,
  "message": "Team member removed successfully."
}

Verwijdering is permanent vanuit jouw kant: een verwijderd lid kan niet worden geactiveerd via het update-eindpunt — nodig ze opnieuw uit als je van gedachten verandert. Hun e-mailadres wordt ook verwijderd van de notificatielijst van je account.

Status	Wanneer
`400`	Je hebt geprobeerd de accounteigenaar te verwijderen.
`403`	Hun toegang is uitgebreider dan die van jou.
`404`	Dit teamlid bestaat niet.

Beperken wat een lid kan zien

Drie optionele velden, geaccepteerd bij toevoegen, bijwerken en uitnodigen, bepalen hoeveel van het account een persoon kan zien. Ze stapelen: een lid dat op meer dan één punt beperkt is, wordt door al deze beperkingen ingeperkt.

contact_scope — all (de standaard: elk contact en elk gesprek) of assigned (alleen de gesprekken die aan hen zijn toegewezen). Gebruik bij assigned ook "contact_scope_unassigned": true om ze ook contacten te laten zien die nog aan niemand zijn toegewezen.

contact_scope_axes — beperkt hen tot specifieke agents, kanalen of afdelingen:

Veld	Type	Beschrijving
`agents`	string[]	Agent-ID’s. Ze zien alleen chats die naar een van deze agents zijn gerouteerd. Max. 200.
`channels`	string[]	Kanaalnamen — `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `instagram_private`, `messenger`, `facebook`, `chat_widget`, `telegram`, `line`, `viber`, `tiktok`, `imessage`, `email`, `linkedin`, `skool`, `custom`, `custom_channel`. Max. 200.
`departments`	string[]	Afdelings-ID’s (zie Afdelingen). Ze zien alleen leads die onder deze afdelingen vallen. Max. 200.
`include_unrouted`	boolean	Indien ingesteld op `agents`, worden ook chats getoond die door geen enkele agent worden afgehandeld. Standaard uitgeschakeld. Wordt genegeerd wanneer `agents` leeg is.
`include_undepartmented`	boolean	Indien ingesteld op `departments`, worden ook chats getoond die in geen enkele afdeling vallen. Standaard uitgeschakeld. Wordt genegeerd wanneer `departments` leeg is.

Agent- en afdelings-ID’s worden niet gecontroleerd wanneer je ze opslaat — een ID die niet bestaat, komt simpelweg nergens mee overeen, wat resulteert in een lege inbox in plaats van een foutmelding. Kanaalnamen worden wel gecontroleerd: een onbekende naam wordt afgewezen met 400.

Geen van deze drie kan worden ingesteld voor de accounteigenaar — dat verzoek wordt geweigerd met 400.

Uitnodigingen weergeven

GET /team/invites

De uitnodigingen die je hebt verzonden, met de nieuwste eerst, zodat je kunt zien wie nog niet heeft geaccepteerd.

Queryparameters

Parameter	Vereist	Beschrijving
`status`	Nee	Retourneer alleen uitnodigingen in deze status — `pending`, `accepted`, `declined`, `cancelled` of `expired`.

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Antwoord

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

Het uitnodigingstoken wordt nooit geretourneerd — het bestaat alleen in de verzonden e-mail.

Een uitnodiging verzenden

POST /team/invites

Stuurt iemand een e-mail met een uitnodiging om lid te worden van je team. Dit is de gebruikelijke manier om een teamlid toe te voegen: ze klikken op de link, loggen in als zichzelf en accepteren. Als ze nog geen Your AI Connector-account hebben, wordt er een voor hen aangemaakt en leidt de e-mail hen door het instellen van een wachtwoord.

Aanvraagvelden

Veld	Vereist	Beschrijving
`email`	Ja	Waar de uitnodiging naartoe moet worden gestuurd.
`role`	Ja	`admin`, `editor` of `viewer`.
`permission_overrides`	Nee	Uitzonderingen per gebied, toegepast op het moment dat ze accepteren.
`contact_scope`	Nee	Toegepast wanneer ze accepteren.
`contact_scope_unassigned`	Nee	Toegepast wanneer ze accepteren.
`contact_scope_axes`	Nee	Toegepast wanneer ze accepteren.
`sub_account_access`	Nee	Alleen voor bureaus. Toegepast wanneer ze accepteren.

Door de rechten vooraf in te stellen, hoef je het lid achteraf niet te bewerken — alles wordt naar hun lidmaatschap gekopieerd zodra ze accepteren.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

Antwoord — 201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

Dingen om rekening mee te houden

Uitnodigingen verlopen na 7 dagen. Een verlopen uitnodiging kan opnieuw worden verzonden, wat een nieuwe periode van 7 dagen start.
Openstaande uitnodigingen bezetten een plek. In tegenstelling tot het direct toevoegen van een lid, telt de controle hier actieve leden plus openstaande uitnodigingen. Een account waarvoor alle plekken bezet zijn, wordt dus geweigerd voordat de e-mail wordt verzonden.
20 uitnodigingen per dag, geteld per account voor zowel verzenden als opnieuw verzenden.

Status	Wanneer
`400`	`email` ontbreekt of de rol is ongeldig.
`403`	Je hebt geen toestemming om het team te beheren, of je hebt geprobeerd toegang te verlenen die hoger is dan die van jezelf.
`409`	Er bestaat al een openstaande uitnodiging voor dat e-mailadres, of die persoon zit al in je team.
`429`	De teamplekken van je abonnement zijn vol, of je hebt de limiet van 20 uitnodigingen per dag bereikt. Het `error`-bericht geeft aan welke van de twee het geval is.

Een uitnodiging annuleren

DELETE /team/invites/{inviteId}

Trekt een uitnodiging in voordat deze wordt geaccepteerd. De link in de e-mail werkt daarna niet meer.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Antwoord

{
  "success": true,
  "message": "Team invite cancelled."
}

Zowel pending- als expired-uitnodigingen kunnen worden geannuleerd. Een uitnodiging die al is geaccepteerd, geweigerd of geannuleerd, retourneert 400; een uitnodiging die niet van jou is, retourneert 403; een onbekende ID retourneert 404.

Een uitnodiging opnieuw verzenden

POST /team/invites/{inviteId}/resend

Verzendt de uitnodigingsmail opnieuw — voor wanneer deze is gemist of in de spam terecht is gekomen. Werkt voor pending- en expired-uitnodigingen en zet de vervaldatum terug naar 7 dagen vanaf nu.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Antwoord

{
  "success": true,
  "message": "Team invite resent successfully."
}

De nieuwe e-mail bevat een nieuwe link, en de oude link blijft ook werken, zodat iemand die de eerste e-mail later vindt, niet vastloopt. Opnieuw verzenden telt mee voor dezelfde limiet van 20 per dag als verzenden, en het opnieuw activeren van een verlopen uitnodiging controleert opnieuw je beschikbare plaatsen — een vol abonnement wordt geweigerd met 429.

Een uitnodiging accepteren

POST /team/invites/accept

Accepteert een uitnodiging met het token uit de uitnodigingsmail, waardoor de ingelogde persoon wordt toegevoegd aan het team van dat account.

Dit is een handeling van je eigen identiteit. Log in als jezelf — het wordt bewust geweigerd met 403 terwijl je in het account van iemand anders werkt.

Aanvraagvelden

Veld	Verplicht	Beschrijving
`invite_token`	Ja	Het token uit de link in de uitnodigingsmail.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Antwoord

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}

Status	Wanneer
`400`	`invite_token` ontbreekt, of de uitnodiging is voor je eigen account.
`403`	De sessie werkt binnen een ander account, of de uitnodiging is verzonden naar een ander e-mailadres dan waarmee je bent ingelogd.
`404`	De uitnodiging bestaat niet of is al gebruikt.
`429`	De plaatsen van het account zijn volgeraakt tussen het moment van uitnodigen en jouw acceptatie.
`504`	De uitnodiging is verlopen. Vraag de afzender om deze opnieuw te verzenden.

Een uitnodiging weigeren

POST /team/invites/decline

Weigert een uitnodiging met het token uit de e-mail. Net als bij accepteren is dit een handeling van je eigen identiteit en wordt dit geweigerd terwijl je in een ander account werkt.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Antwoord

{
  "success": true,
  "message": "Team invite declined."
}

Afdelingen

Een afdeling is een benoemde groep binnen je team — Sales, Klantenservice, HR. Het geeft een lead een eigenaar-team, kan zelfstandig nieuwe gesprekken claimen en kan worden gebruikt om te beperken wat een lid kan zien.

Deze vier endpoints vereisen een API-sleutel. In tegenstelling tot de rest van deze pagina, authenticeren ze op dezelfde manier als elk ander endpoint in de API (zie Authenticatie). Een ingelogde sessie werkt ook: voor lezen is contacts op view nodig, en voor aanmaken, wijzigen of verwijderen is team_management op edit nodig.

Het afdelingsobject

Veld	Type	Beschrijving
`id`	string	Het ID van de afdeling. Gebruik dit in `contact_scope_axes.departments` en in de onderstaande paden.
`name`	string	Hoe het team heet. Maximaal 60 tekens, uniek binnen het account.
`color`	string \| null	Accentkleur als `#rrggbb`, of `null`.
`member_uids`	string[]	De teamleden in deze afdeling. Kan de accounteigenaar bevatten.
`auto_assign_enabled`	boolean	Of een lead die onder deze afdeling valt ook wordt toegewezen aan iemand in die afdeling. `false` betekent dat de afdeling vanuit een gedeelde wachtrij werkt.
`routing_agents`	string[]	Nieuwe gesprekken die door deze AI-agents worden afgehandeld, worden automatisch onder deze afdeling geplaatst. Leeg betekent geen agent-regel.
`routing_channels`	string[]	Nieuwe gesprekken op deze kanalen worden hier automatisch geplaatst. Leeg betekent geen kanaalregel.
`created_by`	string \| null	Wie het heeft aangemaakt.

Wanneer zowel routing_agents als routing_channels zijn ingesteld, moet een gesprek aan beide voldoen om hier te worden geplaatst — zo geef je een team “de support-agent, maar alleen op WhatsApp”.

Een account kan maximaal 50 afdelingen hebben.

Afdelingen weergeven

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

Een afdeling aanmaken

POST /team/departments

Aanvraagvelden

Veld	Verplicht	Beschrijving
`name`	Ja	Maximaal 60 tekens. Mag niet overeenkomen met een bestaande afdeling.
`color`	Nee	`#rrggbb` hex, of `null`.
`member_uids`	Nee	Wie erin zit. Elke UID moet de accounteigenaar of een actief teamlid zijn.
`auto_assign_enabled`	Nee	Standaard ingesteld op `true`.
`routing_agents`	Nee	Agent-ID’s waarvan nieuwe chats hier terechtkomen.
`routing_channels`	Nee	Kanaalnamen waarvan nieuwe chats hier terechtkomen — zelfde vocabulaire als `contact_scope_axes.channels`.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

Antwoord — 201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Status	Wanneer
`400`	`name` ontbreekt of is te lang, `color` is niet `#rrggbb`, een kanaalnaam wordt niet herkend, een vermelde UID is geen actief lid van dit team, of je hebt al 50 afdelingen.
`409`	Er bestaat al een afdeling met die naam.

Een afdeling bijwerken

PATCH /team/departments/{departmentId}

Wijzigt een afdeling. Alleen de velden die je verstuurt, worden gewijzigd.

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

Antwoord

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Het verzenden van geen herkende velden retourneert 400; een onbekende afdeling retourneert 404; een naam die botst met een andere afdeling retourneert 409.

Een afdeling verwijderen

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

Antwoord

{
  "success": true,
  "deleted": "dep_abc123"
}

Het verwijderen van een afdeling waartoe iemand beperkt is, wordt geweigerd. Het 400-antwoord noemt de leden wier zichtbaarheid is beperkt tot die afdeling, zodat u hun bereik eerst opnieuw kunt instellen. Dat is een bewuste keuze: ze stilletjes niet langer beperken zou hen toegang geven tot uw volledige klantenbestand zonder dat er iets zichtbaar is dat dit is gebeurd.

Contacten die onder een verwijderde afdeling zijn opgeslagen, worden niet herschreven — ze tonen simpelweg geen afdeling meer, en de volgende keer dat u ze opslaat, blijft het staan.

Controleer uw eigen rechten

GET /team/permissions

Geeft terug wat de ingelogde persoon mag doen in het account waarin deze momenteel werkt. Gebruik dit om knoppen te verbergen die een lid niet kan gebruiken, in plaats van hen de beperking te laten ontdekken via een foutmelding.

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Antwoord — de accounteigenaar

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

Antwoord — een teamlid dat in een account werkt

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

role is owner wanneer de ingelogde persoon de accounteigenaar is; anders is het hun teamrol. member is alleen aanwezig in de teammodus en bevat contact_scope, contact_scope_unassigned en contact_scope_axes wanneer hun lidmaatschap deze bevat.

Sessietokens

Vijf eindpunten maken een eenmalig inlogtoken aan voor het wisselen tussen accounts. Ze antwoorden allemaal op dezelfde manier:

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

Het token wordt ingewisseld voor een sessie met de Firebase client SDK. Het is geen API-sleutel en kan niet als zodanig worden verzonden, wat de reden is dat deze eindpunten alleen nuttig zijn binnen een first-party app.

Eindpunt	Wat het doet	Body
`POST /team/tokens/team-member`	Laat een teamlid beginnen met werken in een account waar ze bij horen.	`account_owner_uid` (vereist)
`POST /team/tokens/return-from-team`	Brengt hen terug naar hun eigen account.	—
`POST /team/tokens/assist`	Laat Your AI Connector-medewerkers het account van een klant openen voor hulp. Alleen voor medewerkers.	`customerUid`
`POST /team/tokens/return-to-admin`	Beëindigt een assistentiesessie en brengt medewerkers terug naar hun eigen account.	—
`POST /team/tokens/agency-assist`	Laat een bureau een van zijn klant-subaccounts openen — of, aangeroepen zonder account, terugkeren naar het bureau-account.	`subAccountUid` (optioneel)

Elk weigert met 403 wanneer de sessie er niet toe gerechtigd is: geen lid van dat account, geen personeelslid, dat subaccount bevindt zich niet in uw bureau of is niet aan u verleend, of de sessie bevindt zich momenteel niet in de modus waarin het eindpunt eindigt.

Een platformrol toewijzen

POST /team/users/{targetUid}/role

Stelt de platformrol van een gebruiker in — User, Dev, Support of Agency. Dit is geen teamlidmaatschap: het is het type Your AI Connector-account dat iemand heeft.

Dit eindpunt is beperkt tot Your AI Connector-personeel, en de laatst overgebleven Dev kan niet worden gedegradeerd. Vermeld voor de volledigheid; het maakt geen deel uit van het beheren van uw eigen team.

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}

Status	Wanneer
`400`	`role` ontbreekt of is niet een van de vier, of dit zou de laatste `Dev` verwijderen.
`403`	U bent geen personeelslid, of de sessie werkt binnen een ander account.
`404`	Gebruiker bestaat niet.

Team API-fouten

Teameindpunten retourneren de standaard fouten-envelop, altijd met error_code naast de HTTP-status:

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}

Status	Wanneer dit gebeurt op een teameindpunt
`400`	Een verplicht veld ontbreekt of is ongeldig, of de actie is niet toegestaan in deze status (het opnieuw activeren van een verwijderd lid, het opschorten van de eigenaar, het verwijderen van een afdeling waartoe iemand beperkt is).
`401`	U heeft een API-sleutel verzonden naar een eindpunt dat een aangemelde persoon vereist — zie Authenticatie.
`403`	U heeft geen `team_management`-toestemming, de wijziging overschrijdt uw eigen toegang, of de actie wordt geweigerd terwijl u binnen een ander account werkt.
`404`	Geen dergelijk lid, uitnodiging, afdeling of gebruiker.
`409`	Al een teamlid, er bestaat al een uitnodiging in afwachting, of er bestaat al een afdeling met die naam.
`429`	Teamplaatsen zijn vol, de limiet van 20 uitnodigingen per dag is bereikt, of u heeft de API-snelheidslimiet bereikt.
`504`	De uitnodiging die u probeerde te accepteren is verlopen.

De gedeelde codes die elk eindpunt kan retourneren — 429 (snelheidslimiet) en 500 — staan vermeld met richtlijnen voor opnieuw proberen in Fouten & Paginering.

Gerelateerd

Teambeheer — dezelfde functies in het dashboard, met schermafbeeldingen.
Authenticatie — hoe u een Firebase ID-token verzendt in plaats van een API-sleutel.
Contacten-API — de contacten waarop de zichtbaarheidsbeperkingen van een lid van toepassing zijn.

Team-API #

Authenticatie: deze eindpunten vereisen een ingelogde persoon #

Rollen en rechten #

Het teamlid-object #

Teamleden weergeven #

Direct een teamlid toevoegen #

Een teamlid bijwerken #

Een teamlid schorsen #

Een teamlid verwijderen #

Beperken wat een lid kan zien #

Uitnodigingen weergeven #

Een uitnodiging verzenden #

Een uitnodiging annuleren #

Een uitnodiging opnieuw verzenden #

Een uitnodiging accepteren #

Een uitnodiging weigeren #

Afdelingen #

Afdelingen weergeven #

Een afdeling aanmaken #

Een afdeling bijwerken #

Een afdeling verwijderen #

Controleer uw eigen rechten #

Sessietokens #

Een platformrol toewijzen #

Team API-fouten #

Gerelateerd #

Team-API

Authenticatie: deze eindpunten vereisen een ingelogde persoon

Rollen en rechten

Het teamlid-object

Teamleden weergeven

Direct een teamlid toevoegen

Een teamlid bijwerken

Een teamlid schorsen

Een teamlid verwijderen

Beperken wat een lid kan zien

Uitnodigingen weergeven

Een uitnodiging verzenden

Een uitnodiging annuleren

Een uitnodiging opnieuw verzenden

Een uitnodiging accepteren

Een uitnodiging weigeren

Afdelingen

Afdelingen weergeven

Een afdeling aanmaken

Een afdeling bijwerken

Een afdeling verwijderen

Controleer uw eigen rechten

Sessietokens

Een platformrol toewijzen

Team API-fouten

Gerelateerd