Möten #

Appointments API låter dig boka möten för dina kontakter baserat på dina evenemangstyper, samt hämta, lista, uppdatera, avboka eller ta bort dem. Det besvarar även frågan som kommer först i de flesta bokningsflöden — vilka tider som faktiskt är lediga — och täcker kalendersidan: listar de Google-kalendrar du har anslutit och importerar händelser som redan finns i dem. När en Google Kalender-anslutning är aktiv skapas motsvarande kalenderhändelse och hålls automatiskt synkroniserad i bakgrunden. Restauranger som använder Zenchef, Formitable, OpenTable eller TheFork för sina egna bokningssystem kan också verifieras och anslutas här, så att AI-agenten bokar riktiga bord istället för interna möten — och företag som hanterar sina scheman i Trafft kan ansluta på samma sätt.

Alla sökvägar på denna sida är relativa till bas-URL:en https://api.youraiconnector.com/v1. Varje anrop kräver din API-nyckel — se Autentisering för en fullständig lista över hur den kan skickas. Exemplen nedan använder headern X-API-Key, där ett cURL-exempel även visar frågeformuläret ?apiKey=.

Händelser vs. möten: En händelsetyp är en definition av en bokningsbar tid (typ av möte, längd, rum). Ett möte är en bokad instans av en händelsetyp för en specifik kontakt. Du bokar ett möte genom att referera till kontakten och händelsetypen.

Mötesobjektet #

Varje slutpunkt som returnerar ett möte använder samma struktur:

Om kalendersynkronisering: Direkt efter att du bokat eller ändrat ett möte kan google_calendar_event_id fortfarande vara null och calendar_synced kan vara false eftersom synkroniseringen körs i bakgrunden en stund senare. Hämta mötet igen en kort stund senare för att se de ifyllda kalenderfälten.

Hitta tillgängliga tider #

GET /appointments/available-slots

Returnerar de tider som faktiskt är lediga för en händelsetyp mellan två tidpunkter. Detta är normalt det första anropet i ett bokningsflöde: visa dessa tider, låt personen välja en, och skicka sedan den valda tiden till Boka ett möte.

Svaret tar redan hänsyn till händelsetypens egna öppettider och tidslängd, dess rum, möten du redan har bokat på den, samt allt som är blockerat i de anslutna Google-kalendrarna — så en tid som returneras här är en tid du kan boka.

Resultaten returneras grupperade per dag — och när händelsetypen använder rum, en grupp per rum per dag:

Varje post i available_slots har:

Tiderna är lokala för händelsetypen, inte UTC. date, start_time och end_time är klockslag i händelsetypens egen tidszon (dess åsidosättning, eller ditt kontos tidszon om ingen sådan finns). Boka ett möte förväntar sig ett ISO 8601 UTC-ögonblick, så konvertera tiden du valde innan du skickar den.

cURL

curl "https://api.youraiconnector.com/v1/appointments/available-slots?event_id=event_xyz789&start_time=2026-06-15T00:00:00.000Z&end_time=2026-06-19T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  event_id: "event_xyz789",
  start_time: "2026-06-15T00:00:00.000Z",
  end_time: "2026-06-19T00:00:00.000Z",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments/available-slots?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/available-slots",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T00:00:00.000Z",
        "end_time": "2026-06-19T00:00:00.000Z",
    },
)
print(res.json()["data"])

Svar (200 OK):

{
  "success": true,
  "data": [
    {
      "date": "15/06/2026",
      "day": "monday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "10:00", "end_time": "10:30", "available": true },
        { "start_time": "10:30", "end_time": "11:00", "available": true }
      ]
    },
    {
      "date": "16/06/2026",
      "day": "tuesday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "09:00", "end_time": "09:30", "available": true, "spots_left": 2 }
      ]
    }
  ]
}

En dag utan lediga tider visas helt enkelt inte. Om event_id, start_time eller end_time saknas returneras 400; en händelsetyp som inte finns på ditt konto returnerar 404.

Boka ett möte #

POST /appointments

Skapar en bokning för en av dina kontakter. Det finns två sätt att använda den:

• På en av dina händelsetyper — skicka event_id, så fungerar bokningen precis som den alltid har gjort: tillgänglighet och kapacitet respekteras, sluttiden beräknas utifrån händelsetypens tidslucka, och bokningen synkroniseras till din Google Kalender när en sådan är ansluten.
• Som en extern bokning — utelämna event_id och skicka en title istället. Detta registrerar en bokning som gjorts någon annanstans (ditt eget CRM, ett kursschema, ett annat bokningsverktyg) så att den visas på sidan Bokningar tillsammans med de övriga.

En bokning för en händelsetyp med rum måste ske vid en tidpunkt som Hitta tillgängliga tider skulle erbjuda: inom rummets öppettider, utanför varseltiden, inom hur långt i förväg händelsetypen kan bokas, i tidsrutnätet, inte i det förflutna och inte blockerad i en ansluten kalender. Alla andra tider nekas med ett 400 och ingenting skapas. Detsamma gäller en room_name som inte matchar något av händelsetypens rum (meddelandet listar de giltiga namnen). Bufferttider som ställts in för händelsetypen (Buffert före och Buffert efter i redigeraren för händelsetyper, buffer_before och buffer_after i minuter) hålls fria kring varje bokning.

En bokning för en händelsetyp genomgår även en konfliktkontroll: om tidsluckan redan är full misslyckas begäran med ett 409 och ingenting skapas. En extern bokning har ingen händelsetyp kopplad till sig, så ingenting kontrolleras mot din tillgänglighet eller kapacitet och ingenting synkroniseras till en kalender.

Det är säkert att försöka igen. Om samma kontakt redan har en bekräftad bokning för samma händelsetyp vid samma starttid (i samma rum, när du anger ett), till exempel för att din första begäran tog för lång tid trots att den gick igenom, får du tillbaka den bokningen med ett 200 och "replayed": true istället för en andra bokning eller ett 409.

En external_reference fungerar som en idempotensnyckel. Den är unik för ditt konto: om en bokning redan har den referens du skickar, returneras den bokningen med en 200 och "replayed": true och inget nytt skapas, även om ett nytt försök anger en annan tid eller kontakt och oavsett bokningens status. Använd den för betalda bokningar (skicka ditt betalnings- eller order-ID) och skicka en ny referens för en genuint ny bokning.

Skicka event_id och title tillsammans, eller ingetdera, så returnerar begäran ett 400 — likaså om du skickar både end_time och duration_minutes.

cURL (använder frågeformuläret ?apiKey=)

curl -X POST "https://api.youraiconnector.com/v1/appointments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "start_time": "2026-06-15T10:00:00.000Z",
    "room_name": "Room A"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    event_id: "event_xyz789",
    start_time: "2026-06-15T10:00:00.000Z",
    room_name: "Room A",
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T10:00:00.000Z",
        "room_name": "Room A",
    },
)
print(res.json()["appointment_id"])

Svar (201 Created):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Registrera en bokning gjord någon annanstans #

Samma slutpunkt, utan en händelsetyp: ett title och ett start_time räcker, och duration_minutes anger hur länge den pågår.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "title": "Beginner guitar class",
    "start_time": "2026-06-15T10:00:00.000Z",
    "duration_minutes": 90,
    "external_reference": "class-slot-4812"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    title: "Beginner guitar class",
    start_time: "2026-06-15T10:00:00.000Z",
    duration_minutes: 90,
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "title": "Beginner guitar class",
        "start_time": "2026-06-15T10:00:00.000Z",
        "duration_minutes": 90,
    },
)
print(res.json()["appointment_id"])

Svar (201 Created):

{
  "success": true,
  "appointment_id": "eFgH5678aBcD1234",
  "appointment": {
    "id": "eFgH5678aBcD1234",
    "contact_id": "contact_abc123",
    "event_id": null,
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T11:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "summary": "Beginner guitar class",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Externa bokningar är vanliga bokningar från och med då: de visas på sidan Bokningar och i Lista bokningar, de kan ombokas, avbokas eller raderas i appen eller via detta API, bokningsbekräftelsen skickas ut som vanligt, och automationsutlösaren Bokning bokad samt webhookar aktiveras för dem precis som för alla andra bokningar som görs via API:et. De enda skillnaderna är de som nämns ovan — ingen kontroll av tillgänglighet eller kapacitet, ingen kalendersynkronisering, och event_id förblir null.

Hämta ett möte #

GET /appointments/{appointmentId}

Returnerar ett enskilt möte via dess ID, inklusive dess synkroniseringsstatus för kalendern.

cURL

curl "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["appointment"])

Svar (200 OK):

{
  "success": true,
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": "abc123googleevent",
    "calendar_synced": true
  }
}

Lista möten #

GET /appointments

Listar möten för ditt konto, med det nyaste först, med markörbaserad paginering.

Några regler att komma ihåg:

• Utan filter får du varje möte på kontot, sida för sida.
• Per kontakt — ställ in contact_id för att se en kontakts bekräftade möten. Du kan begränsa detta till en enskild dag genom att även skicka med date.
• Per status — ställ in status (utan contact_id) för att endast lista Confirmed eller endast Canceled möten för hela kontot.
• Filtret date utan contact_id, eller status=Canceled tillsammans med contact_id, returnerar ett 400.

cURL

curl "https://api.youraiconnector.com/v1/appointments?contact_id=contact_abc123&date=2026-06-15" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  contact_id: "contact_abc123",
  date: "2026-06-15",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointments, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"contact_id": "contact_abc123", "date": "2026-06-15"},
)
data = res.json()
print(data["appointments"], data["next_cursor"])

Svar (200 OK):

{
  "success": true,
  "appointments": [
    {
      "id": "aBcD1234eFgH5678",
      "contact_id": "contact_abc123",
      "event_id": "event_xyz789",
      "status": "Confirmed",
      "start_time": "2026-06-15T10:00:00.000Z",
      "end_time": "2026-06-15T10:30:00.000Z",
      "calendar_synced": true
    }
  ],
  "next_cursor": null
}

För att bläddra igenom resultaten, skicka med next_cursor från ett svar som cursor i nästa begäran. Fortsätt tills next_cursor är null. Se Fel & Paginering för det gemensamma pagineringsmönstret.

Uppdatera ett möte #

PUT /appointments/{appointmentId}

Boka om ett möte eller ändra dess detaljer. Skicka endast de fält du vill ändra — minst ett krävs. Den kombinerade start- och sluttiden måste vara i kronologisk ordning (end_time måste vara efter start_time). Ändringar synkroniseras automatiskt till den länkade kalenderhändelsen.

Att flytta en bekräftad bokning för en händelsetyp (ett nytt start_time eller room_name) genomgår en konfliktkontroll precis som en ny bokning: en tidslucka som redan är full svarar med 409 och ingenting ändras, och ett room_name som inte matchar något av händelsetypens rum svarar med 400. Skicka endast start_time så behåller bokningen sin längd. Dina egna öppettider och varseltider tillämpas inte här, så du kan fortfarande flytta en bokning till vilken ledig tid som helst.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      start_time: "2026-06-16T10:00:00.000Z",
      end_time: "2026-06-16T10:30:00.000Z",
    }),
  }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "start_time": "2026-06-16T10:00:00.000Z",
        "end_time": "2026-06-16T10:30:00.000Z",
    },
)
print(res.json()["appointment"])

Svar (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z",
    "calendar_synced": true
  }
}

Avboka en tid #

POST /appointments/{appointmentId}/cancel

Avbokar en bekräftad tid, med möjlighet att ange en orsak. Tiden finns kvar på ditt konto med status Canceled, och den länkade kalenderhändelsen tas bort automatiskt i bakgrunden. Att avboka en redan avbokad tid returnerar en 400.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Client asked to reschedule next month"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cancellation_reason: "Client asked to reschedule next month",
    }),
  }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"cancellation_reason": "Client asked to reschedule next month"},
)
print(res.json()["success"])

Svar (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678"
}

Skicka bokningsbekräftelsen igen #

POST /appointments/{appointmentId}/resend-confirmation

Skickar bokningsbekräftelsen till kontakten igen, till exempel om de säger att den aldrig kom fram eller hamnade i skräpposten. Två delar, båda skickas om du inte stänger av en av dem: bekräftelsemailet (samma mail som kontakten fick vid bokningstillfället) och, när mötet finns i din Google Kalender, Google Kalender-inbjudan. Båda skickas till kontaktens e-postadress.

Varje del returnerar sitt eget resultat: sent, not_requested, no_contact_email, turned_off_for_event_type (händelsetypens inställning Skicka mötesmail till kontakt är avstängd), not_on_google_calendar, imported (möten som importerats från din kalender får inget bekräftelsemail) eller failed.

• 200 när minst en del skickades. recipient är adressen den skickades till.
• 409 för ett avbokat möte, ett möte som redan har ägt rum, eller en bokning gjord via Zenchef, Formitable, OpenTable, TheFork eller Trafft (det systemet skickar sin egen bekräftelse). code är appointment_canceled, appointment_in_past eller managed_by_provider.
• 422 när ingenting kunde skickas, med orsaken i error.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ calendar_invite: false }),
  }
);
const data = await res.json();
console.log(data.email, data.recipient);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={},
)
print(res.json())

Svar (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "email": "sent",
  "calendar_invite": "sent",
  "recipient": "jane@example.com"
}

Ta bort en bokning #

DELETE /appointments/{appointmentId}

Tar permanent bort en bokning och dess referenser. Om du bara vill avboka tiden men behålla posten, använd avboka istället.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Svar (200 OK):

{
  "success": true
}

Lista dina anslutna Google-kalendrar #

GET /appointments/google-calendars

Returnerar de Google-kalendrar som är tillgängliga på detta konto, direkt från Google — användbart för att visa kontoinnehavaren en väljare för vilken kalender som ska importeras från nedan, eller bara för att bekräfta att anslutningen är aktiv.

Detta fungerar endast när kontot har anslutit Google Kalender (Inställningar → Integrationer) med minst läsbehörighet. Om det inte har gjorts, eller om den beviljade åtkomsten inte längre inkluderar läsbehörighet för kalendern, får du ett 400 som ber dig att (åter)ansluta den.

cURL

curl "https://api.youraiconnector.com/v1/appointments/google-calendars" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/google-calendars", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/google-calendars",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["data"])

Svar (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "primary",
      "summary": "jane@example.com",
      "timeZone": "America/New_York",
      "accessRole": "owner",
      "primary": true
    },
    {
      "id": "abcdefg1234567890@group.calendar.google.com",
      "summary": "Bookings",
      "timeZone": "America/New_York",
      "accessRole": "writer"
    }
  ]
}

Varje post har Googles egen CalendarListEntry-form, så fältnamnen följer Googles camelCase, inte detta API:s vanliga snake_case — det är Googles data som skickas vidare som den är, inte vår. En saknad eller återkallad anslutning returnerar 400 med ett felmeddelande som förklarar att Google Kalender behöver (åter)anslutas.

Importera händelser från en Google-kalender #

POST /appointments/import-calendar-events

Hämtar händelser som redan finns i en kampanjs eller AI-agents anslutna Google-kalender(ar) och gör om dem till möten — användbart första gången du ansluter en kalender som redan har bokningar. Detta kan ta en stund (varje händelse går igenom extrahering för att ta reda på vem den är till för), så det körs aldrig direkt: begäran köar ett bakgrundsjobb och ger dig tillbaka ett job_id att polla.

Skicka exakt en av campaign_id / agent_id, aldrig båda och aldrig ingen — båda kombinationerna returnerar ett 400. Den du skickar måste tillhöra ditt konto, annars får du ett 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/import-calendar-events?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "identifier": "EMAIL"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/import-calendar-events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    identifier: "EMAIL",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/import-calendar-events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"agent_id": "agent_abc123", "identifier": "EMAIL"},
)
print(res.json()["job_id"])

Svar (202 Accepted):

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "queued",
  "campaign_id": null,
  "agent_id": "agent_abc123"
}

campaign_id och agent_id ekar tillbaka den du skickade; den andra är alltid null.

Polla importjobbet #

GET /appointments/import-calendar-events/{jobId}

curl "https://api.youraiconnector.com/v1/appointments/import-calendar-events/jK9mQ2xR7pL4wN1t" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK):

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "completed",
  "message": "Imported 12 events as appointments.",
  "error": null
}

GET på ett jobId som inte finns (eller tillhör ett annat konto) returnerar 404.

Externa bokningsintegrationer (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef och Formitable är restaurangbokningssystem som din AI-agent kan boka riktiga bord genom; Trafft är en schemaläggningsplattform för företag som arbetar med tidsbokning, vilken ansluts en gång per konto snarare än per restaurang. De två restaurangplattformarna har vardera en publik, oautentiserad bokningswidget (https://api.youraiconnector.com/v1/zenchef-widget/... och https://api.youraiconnector.com/v1/formitable-widget/...) som renderas i chatten för gästen — dessa widget-vägar är vanliga HTML-sidor avsedda att öppnas i en webbläsare, inte JSON API-slutpunkter, så de dokumenteras inte här. Vad som följer är slutpunkterna för kontohantering: att verifiera att ett restaurang-ID tillhör kontoinnehavaren, samt att lägga till, uppdatera eller ta bort det.

Zenchef #

Att ansluta en Zenchef-restaurang är en tvåstegsverifiering, så kontoinnehavaren bevisar att de faktiskt driver restaurangen innan den kopplas till boten: kontrollera först att ID:t finns (utan att avslöja namnet), låt dem sedan skriva in restaurangens namn själva och verifiera att det matchar.

Steg 1 — Kontrollera att ett restaurang-ID finns

POST /appointments/zenchef-restaurants/check

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/check?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345" }'

Svar (200 OK):

{
  "success": true,
  "data": { "exists": true, "requiresNameVerification": true }
}

exists: false betyder att ingen Zenchef-restaurang har det ID:t — inget mer att göra. Hastighetsbegränsat till 10 kontroller per 5 minuter per konto; att överskrida detta returnerar 429.

Steg 2 — Verifiera restaurangens namn

POST /appointments/zenchef-restaurants/verify-name

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/verify-name?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "user_input_name": "The Blue Door Bistro" }'

Svar (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "id": "12345",
      "name": "The Blue Door Bistro",
      "address": "1 Rue de Rivoli, Paris",
      "status": "active"
    }
  }
}

verified: false betyder att namnet inte matchade — restaurantDetails utelämnas, be kontoinnehavaren att försöka igen. Hastighetsbegränsat till 3 försök per 5 minuter (strängare än existenskontrollen, eftersom detta är det faktiska bevissteget). Ett restaurant_id som inte längre kan matchas på Zenchef returnerar 404.

Steg 3 — Spara restaurangen

POST /appointments/zenchef-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "restaurant_name": "The Blue Door Bistro" }'

Svar (201 Created):

{ "success": true, "data": { "restaurantId": "12345" } }

Uppdatera en sparad Zenchef-restaurang

PUT /appointments/zenchef-restaurants/{restaurantId}

curl -X PUT "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Svar (200 OK): samma format som spar-svaret ovan.

Ta bort en Zenchef-restaurang

DELETE /appointments/zenchef-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK): { "success": true, "data": { "restaurantId": "12345" } }

En restaurantId som för närvarande inte finns på kontot returnerar 404 vid uppdatering eller borttagning.

Formitable #

Formitable behöver inte den tvåstegsnamnverifiering som Zenchef kräver — dess restaurang-ID:n är redan begränsade per företag, så ett verifieringsanrop räcker. Den har också en detaljsökning som används för att cachelagra restaurangens webbplats-URL under konfigurationen.

Verifiera ett restaurang-ID

POST /appointments/formitable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "the-blue-door", "language": "en" }'

Svar (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "the-blue-door",
      "productCount": 4,
      "sampleProductTitle": "Dinner for two",
      "language": "en"
    }
  }
}

Ett restaurant_id som Formitable inte känner igen returnerar 404. Hastighetsbegränsat till 10 försök per 5 minuter per konto.

Hämta restaurangdetaljer

GET /appointments/formitable-restaurants/{restaurantId}/details?language=en

Hämtar restaurangens offentliga profil från Formitable, inklusive dess webbplats — används för att cachelagra webbplatsens URL när restaurangen konfigureras. language är en valfri frågeparameter som som standard är "en".

curl "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door/details?language=en" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK):

{
  "success": true,
  "data": {
    "uid": "the-blue-door",
    "name": "The Blue Door Bistro",
    "website": "https://thebluedoorbistro.com",
    "email": "info@thebluedoorbistro.com",
    "telephone": "+31201234567",
    "streetAddress": "Prinsengracht 1",
    "zipcode": "1015 AB",
    "city": "Amsterdam",
    "country": "Netherlands",
    "countryCode": "NL",
    "currency": "EUR"
  }
}

Spara restaurangen

POST /appointments/formitable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "the-blue-door",
    "restaurant_name": "The Blue Door Bistro",
    "language": "en",
    "website_url": "https://thebluedoorbistro.com"
  }'

Svar (201 Created): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Uppdatera en sparad Formitable-restaurang

PUT /appointments/formitable-restaurants/{restaurantId}

curl -X PUT "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Svar (200 OK): samma format som spar-svaret ovan.

Ta bort en Formitable-restaurang

DELETE /appointments/formitable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK): { "success": true, "data": { "restaurantId": "the-blue-door" } }

En restaurantId som för närvarande inte finns på kontot returnerar 404 vid uppdatering eller borttagning.

OpenTable #

OpenTable-restauranger nås via plattformens OpenTable-partneruppgifter, och OpenTable låter endast dessa uppgifter se restauranger som har anslutit plattformens listning via OpenTables Integrations Marketplace. Så, precis som med Formitable, räcker ett verifieringsanrop: ett nåbart restaurang-ID (det numeriska “RID”) bevisar både att restaurangen existerar och att den har anslutit integrationen. Tills OpenTable-partnerlistningen är aktiverad på plattformen svarar verifieringsanropet 503.

Verifiera en OpenTable-restaurang

POST /appointments/opentable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007" }'

Svar (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "1038007",
      "diningAreaCount": 2,
      "diningAreaNames": ["Main Room", "Garden"],
      "tableTypes": ["default", "outdoor", "bar"]
    }
  }
}

verified: false betyder att ingen OpenTable-restaurang har det ID:t. Ett 403 betyder att restaurangen existerar men ännu inte har anslutit plattformens integration inuti OpenTable. Hastighetsbegränsat till 10 försök per 5 minuter per konto.

Lägg till en OpenTable-restaurang

POST /appointments/opentable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Svar (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

Uppdatera en sparad OpenTable-restaurang

PUT /appointments/opentable-restaurants/{restaurantId}

Skicka något av restaurant_name, is_active (pausa med false) eller website_url (tom sträng rensar det); utelämnade fält lämnas oförändrade.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Svar (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

Ta bort en OpenTable-restaurang

DELETE /appointments/opentable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

En restaurantId som för närvarande inte finns på kontot returnerar 404 vid uppdatering.

TheFork #

TheFork-restauranger nås via plattformens TheFork-partneruppgifter, och TheFork låter endast dessa uppgifter se restauranger som har plattformens partner aktiverad på sitt TheFork-konto. Så, precis som med Formitable och OpenTable, räcker ett verifieringsanrop: ett nåbart restaurang-ID bevisar både att restaurangen existerar och att partnern är aktiverad för den. ID:t är det UUID som TheFork ger restaurangen i TheFork Manager, skickat som en sträng. Tills TheFork har godkänt plattformen som partner och utfärdat uppgifterna, svarar verifieringsanropet 503 — se TheFork för vad det innebär idag.

Verifiera en TheFork-restaurang

POST /appointments/thefork-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" }'

Svar (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "partySizes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
}

partySizes är de sällskapsstorlekar som restaurangen tar emot online under de kommande 30 dagarna. Ett 404 eller 403 innebär att TheFork inte gav oss en restaurang med det ID:t — antingen är ID:t felaktigt, eller så är plattformens partner ännu inte aktiverad på den restaurangen; ett 400 innebär att ID:t inte är ett UUID. Hastighetsbegränsat till 10 försök per 5 minuter per konto.

Lägg till en TheFork-restaurang

POST /appointments/thefork-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Svar (201 Created): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Uppdatera en sparad TheFork-restaurang

PUT /appointments/thefork-restaurants/{restaurantId}

Skicka något av restaurant_name, is_active (pausa med false) eller website_url (tom sträng rensar det); utelämnade fält lämnas oförändrade.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Svar (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Ta bort en TheFork-restaurang

DELETE /appointments/thefork-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

En restaurantId som för närvarande inte finns på kontot returnerar 404 vid uppdatering eller borttagning.

Trafft #

Trafft ansluts en gång för hela kontot, inte per plats: en företagsadress plus API-uppgifter från Traffts administratörspanel (Features & Integrations → API & Connectors, en del av Traffts Business-plan). Anslutningsanropet kontrollerar dessa uppgifter mot Trafft innan något lagras, så en felaktig adress, felaktiga uppgifter eller en plan utan API-åtkomst misslyckas här istället för under en kundkonversation. Klienthemligheten (client secret) lagras krypterad och returneras aldrig av någon slutpunkt.

Alla tre skrivanrop (POST, PUT, DELETE) kräver behörigheten edit för integrationer; statusen GET kräver view för integrationer.

Anslut Trafft

POST /appointments/trafft/connect

curl -X POST "https://api.youraiconnector.com/v1/appointments/trafft/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "client_secret": "YOUR_TRAFFT_CLIENT_SECRET",
    "company_name": "Acme Salon"
  }'

Svar (200 OK):

{
  "success": true,
  "data": {
    "subdomain": "acme",
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

Antalen kommer tillbaka från Trafft under kontrollen — de är det snabbaste sättet att bekräfta att uppgifterna pekar på det konto du avsåg.

Hämta anslutningsstatus

GET /appointments/trafft

curl "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK):

{
  "success": true,
  "data": {
    "connected": true,
    "subdomain": "acme",
    "hostname": "acme.admin.trafft.com",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "company_name": "Acme Salon",
    "is_active": true,
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

connected: false betyder att ingenting har ställts in ännu. Klienthemligheten inkluderas aldrig i detta svar.

Uppdatera anslutningen

PUT /appointments/trafft

curl -X PUT "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Svar (200 OK): samma anslutningsobjekt som GET ovan.

Koppla från Trafft

DELETE /appointments/trafft

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Svar (200 OK): { "success": true }

Frånkoppling tar endast bort de lagrade inloggningsuppgifterna. Bokningar som redan finns i Trafft förblir orörda.

Felstruktur för alla Zenchef/Formitable/OpenTable/TheFork-slutpunkter: till skillnad från resten av den här sidan visas fel här med sin status två gånger — en gång som HTTP-status och en gång som error_code i brödtexten — till exempel { "success": false, "error": "Restaurant not found", "error_code": 404 }. Hantera det på samma sätt som alla andra fel: kontrollera success, läs error för meddelandet.

Fel i Appointments API #

Slutpunkter för möten returnerar standardfelmeddelandet:

{
  "success": false,
  "error": "Appointment not found"
}

De delade koderna som alla slutpunkter kan returnera — 401, 403 (din plan inkluderar inte API-åtkomst), 429 (hastighetsbegränsning) och 500 — listas med vägledning för återförsök i Fel & Paginering.

Nästa steg #

• Kontakter — skapa och sök efter de kontakter du bokar för.
• Meddelanden och konversationer — skicka en bekräftelse eller påminnelse till en kontakt.
• Webhooks — få aviseringar när bokningar ändras.