Aftaler #

Appointments API’en lader dig booke aftaler for dine kontakter på dine begivenhedstyper, og derefter hente, liste, opdatere, annullere eller slette dem. Den besvarer også det spørgsmål, der kommer først i de fleste booking-flows — hvilke tidspunkter er faktisk ledige — og dækker kalendersiden: visning af de Google-kalendere, du har forbundet, og import af begivenheder, der allerede findes i dem. Når en Google Kalender-forbindelse er aktiv, oprettes den matchende kalenderbegivenhed og holdes automatisk synkroniseret i baggrunden. Restauranter, der bruger Zenchef, Formitable, OpenTable eller TheFork til deres egne reservationssystemer, kan også verificeres og forbindes her, så AI-agenten booker rigtige borde i stedet for interne aftaler — og virksomheder, der kører deres tidsplan i Trafft, kan forbinde på samme måde.

Alle stier på denne side er relative til basis-URL’en https://api.youraiconnector.com/v1. Hver anmodning kræver din API-nøgle — se Godkendelse for den fulde liste over måder at sende den på. Eksemplerne nedenfor bruger X-API-Key-headeren, hvor et cURL-eksempel også viser ?apiKey=-forespørgselsformen.

Begivenheder vs. aftaler: En begivenhedstype er en definition af en bookbar plads (typen af møde, dets varighed, dets lokaler). En aftale er én booket forekomst af en begivenhedstype for en specifik kontakt. Du booker en aftale ved at referere til kontakten og begivenhedstypen.

Aftaleobjektet #

Hvert slutpunkt, der returnerer en aftale, bruger samme form:

Om kalendersynkronisering: Lige efter du booker eller ændrer en aftale, kan google_calendar_event_id stadig være null og calendar_synced kan være false, fordi synkroniseringen kører i baggrunden et øjeblik senere. Hent aftalen igen kort efter for at se de udfyldte kalenderfelter.

Find ledige tider #

GET /appointments/available-slots

Returnerer de tider, der er reelt ledige på en begivenhedstype mellem to tidspunkter. Dette er normalt det første kald i et booking-flow: vis disse tider, lad personen vælge en, og post derefter det valgte tidspunkt til Book en aftale.

Svaret tager allerede højde for begivenhedstypens egne åbningstider og varighed, dens lokaler, aftaler du allerede har booket på den, og alt, hvad der er blokeret i de forbundne Google-kalendere — så en tid, der returneres her, er en, du kan booke.

Resultaterne kommer tilbage grupperet efter dag — og når begivenhedstypen bruger lokaler, én gruppe pr. lokale pr. dag:

Hver post i available_slots har:

Tider er lokale for begivenhedstypen, ikke UTC. date, start_time og end_time er vægursværdier i begivenhedstypens egen tidszone (dens overstyring, eller din kontos tidszone, når den ikke har nogen). Book en aftale forventer et ISO 8601 UTC-øjeblik, så konverter den tid, du valgte, før du poster 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 uden ledige tider vises slet ikke. Manglende event_id, start_time eller end_time returnerer 400; en begivenhedstype, der ikke er på din konto, returnerer 404.

Book en aftale #

POST /appointments

Opretter en aftale for en af dine kontakter. Der er to måder at bruge den på:

• På en af dine begivenhedstyper — send event_id, og bookingen fungerer præcis som den altid har gjort: tilgængelighed og kapacitet respekteres, sluttidspunktet beregnes ud fra begivenhedstypens varighed, og aftalen synkroniseres til din Google Kalender, når en sådan er forbundet.
• Som en ekstern booking — udelad event_id og send en title i stedet. Dette registrerer en booking, der er foretaget et andet sted (dit eget CRM, en holdplan, et andet bookingsystem), så den vises på siden Aftaler sammen med resten.

En booking af en begivenhedstype med lokaler skal foretages på et tidspunkt, som Find ledige tider ville tilbyde: inden for lokalets åbningstider, uden for varslingsperioden, inden for hvor langt frem i tiden begivenhedstypen kan bookes, på tidsplanen, ikke i fortiden og ikke blokeret i en tilknyttet kalender. Ethvert andet tidspunkt afvises med en 400, og intet oprettes. Det samme gælder en room_name, der ikke matcher nogen af begivenhedstypens lokaler (beskeden viser de gyldige navne). Buffertider indstillet på begivenhedstypen (Buffer før og Buffer efter i editoren for begivenhedstyper, buffer_before og buffer_after i minutter) holdes fri omkring hver booking.

En booking af en begivenhedstype bliver også tjekket for konflikter: Hvis tidsrummet allerede er optaget, fejler anmodningen med en 409, og intet oprettes. En ekstern booking har ikke en begivenhedstype bag sig, så intet tjekkes mod din tilgængelighed eller kapacitet, og intet synkroniseres til en kalender.

Det er sikkert at prøve igen. Hvis den samme kontaktperson allerede har en bekræftet booking af den samme begivenhedstype på samme starttidspunkt (i samme lokale, hvis du angiver et), for eksempel fordi din første anmodning fik timeout efter den var gået igennem, får du den booking tilbage med en 200 og "replayed": true i stedet for en ekstra booking eller en 409.

En external_reference fungerer som en idempotensnøgle. Den er unik på din konto: Hvis en aftale allerede bærer den reference, du sender, returneres denne aftale med en 200 og "replayed": true, og intet nyt oprettes, selv når et nyt forsøg angiver et andet tidspunkt eller en anden kontakt, uanset hvad aftalens status er. Brug den til betalte bookinger (send dit betalings- eller ordrenummer), og send en ny reference for en reelt ny booking.

Send event_id og title sammen, eller ingen af de to, og anmodningen returnerer en 400 — det samme gør afsendelse af både end_time og duration_minutes.

cURL (ved brug af ?apiKey= forespørgselsformen)

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

Registrering af en booking foretaget et andet sted #

Samme endpoint, uden en begivenhedstype: en title og en start_time er nok, og duration_minutes indstiller hvor længe den varer.

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

Eksterne bookinger er almindelige aftaler derefter: de vises på siden Aftaler og i List aftaler, de kan ændres, annulleres eller slettes i appen eller gennem denne API, bekræftelsesmailen for bookingen sendes som sædvanlig, og automatiserings-triggeren Aftale booket samt webhook aktiveres for dem ligesom for enhver anden booking foretaget gennem API’en. De eneste forskelle er dem ovenfor — ingen tjek af tilgængelighed eller kapacitet, ingen kalendersynkronisering, og event_id forbliver null.

Hent en aftale #

GET /appointments/{appointmentId}

Returnerer en enkelt aftale via dens ID, inklusive dens kalendersynkroniseringstilstand.

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

List aftaler #

GET /appointments

Lister aftaler for din konto, nyeste først, med markør-baseret paginering.

Et par regler at huske på:

• Uden filtre får du hver aftale på kontoen, side for side.
• Efter kontakt — sæt contact_id for at se én kontakts bekræftede aftaler. Du kan indsnævre dette til en enkelt dag ved også at sende date.
• Efter status — sæt status (uden contact_id) for kun at liste Confirmed eller kun Canceled aftaler på tværs af kontoen.
• date-filteret uden contact_id, eller status=Canceled sammen med contact_id, returnerer en 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
}

For at bladre gennem resultaterne skal du sende next_cursor fra ét svar som cursor i den næste anmodning. Fortsæt indtil next_cursor er null. Se Fejl & Paginering for det fælles pagineringsmønster.

Opdater en aftale #

PUT /appointments/{appointmentId}

Omplanlæg en aftale eller skift dens detaljer. Send kun de felter, du ønsker at ændre — mindst ét er påkrævet. Den kombinerede start og slut skal forblive i kronologisk rækkefølge (end_time skal være efter start_time). Ændringer synkroniseres automatisk til den linkede kalenderbegivenhed.

Flytning af en bekræftet booking af en begivenhedstype (en ny start_time eller room_name) tjekkes for konflikter ligesom en ny booking: et tidsrum, der allerede er optaget, svarer med 409, og intet ændres, og en room_name, der ikke matcher nogen af begivenhedstypens lokaler, svarer med 400. Send kun start_time, så beholder bookingen sin varighed. Dine egne åbningstider og varslingsperioder anvendes ikke her, så du kan stadig flytte en booking til et hvilket som helst ledigt tidspunkt.

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

Annuller en aftale #

POST /appointments/{appointmentId}/cancel

Annullerer en bekræftet aftale, eventuelt med angivelse af en årsag. Aftalen forbliver på din konto med status Canceled, og den tilknyttede kalenderbegivenhed fjernes automatisk i baggrunden. Annullering af en allerede annulleret aftale returnerer 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"
}

Gensend bookingbekræftelsen #

POST /appointments/{appointmentId}/resend-confirmation

Sender kontaktpersonens bookingbekræftelse igen, for eksempel hvis de siger, at den aldrig ankom eller endte i spam. To dele, som begge sendes, medmindre du slår en af dem fra: bekræftelsesmailen (den samme mail, som kontaktpersonen modtog ved booking) og, når aftalen er i din Google Kalender, Google Kalender-invitationen. Begge sendes til kontaktpersonens e-mailadresse.

Hver del returneres med sit eget resultat: sent, not_requested, no_contact_email, turned_off_for_event_type (hvor begivenhedstypens Send aftalemail til kontaktperson-kontakt er slået fra), not_on_google_calendar, imported (aftaler importeret fra din kalender modtager ingen bekræftelsesmail) eller failed.

• 200 når mindst én del blev sendt. recipient er adressen, den blev sendt til.
• 409 for en annulleret aftale, en aftale der allerede er overstået, eller en booking foretaget via Zenchef, Formitable, OpenTable, TheFork eller Trafft (det system sender sin egen bekræftelse). code er appointment_canceled, appointment_in_past eller managed_by_provider.
• 422 når intet kunne sendes, med årsagen 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"
}

Slet en aftale #

DELETE /appointments/{appointmentId}

Sletter permanent en aftale og dens referencer. Hvis du kun ønsker at aflyse bookingen, men beholde posten, skal du i stedet bruge annuller.

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
}

List dine forbundne Google-kalendere #

GET /appointments/google-calendars

Returnerer de Google-kalendere, der er tilgængelige på denne konto, direkte fra Google — nyttigt til at vise kontohaveren en vælger af, hvilken kalender der skal importeres fra nedenfor, eller blot for at bekræfte, at forbindelsen er aktiv.

Dette virker kun, når kontoen har forbundet Google Kalender (Indstillinger → Integrationer) med mindst læseadgang. Hvis den ikke har, eller hvis den givne adgang ikke længere inkluderer scope for kalenderlæsning, får du en 400, der beder dig om at (gen)forbinde 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"
    }
  ]
}

Hver post er Googles egen CalendarListEntry-form, så feltnavne følger Googles camelCase, ikke denne API’s sædvanlige snake_case — det er Googles data, der sendes igennem som de er, ikke vores. En manglende eller tilbagekaldt forbindelse returnerer 400 med en fejl, der forklarer, at Google Kalender skal (gen)forbindes.

Importér begivenheder fra en Google Kalender #

POST /appointments/import-calendar-events

Henter de begivenheder, der allerede ligger i en kampagnes eller AI-agents forbundne Google Kalender(e), og omdanner dem til aftaler — nyttigt første gang du forbinder en kalender, der allerede har bookinger. Dette kan tage et stykke tid (hver begivenhed gennemgår ekstraktion for at finde ud af, hvem den er til), så den kører aldrig inline: anmodningen sætter et baggrundsjob i kø og giver dig en job_id tilbage, som du kan polle.

Send præcis én af campaign_id / agent_id, aldrig begge og aldrig ingen af dem — enhver anden kombination returnerer en 400. Den, du sender, skal tilhøre din konto, ellers får du en 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 og agent_id ekkoer den, du sendte; den anden er altid null.

Polling af 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å en jobId, der ikke eksisterer (eller tilhører en anden konto), returnerer 404.

Eksterne booking-integrationer (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef og Formitable er restaurant-reservationssystemer, som din AI-agent kan booke rigtige borde igennem; Trafft er en planlægningsplatform for virksomheder, der arbejder med aftaler, og som forbindes én gang pr. konto i stedet for pr. restaurant. De to restaurantplatforme har hver en offentlig, uautentificeret booking-widget (https://api.youraiconnector.com/v1/zenchef-widget/... og https://api.youraiconnector.com/v1/formitable-widget/...), der vises i chatten for gæsten — disse widget-ruter er almindelige HTML-sider beregnet til at blive åbnet i en browser, ikke JSON API-slutpunkter, så de er ikke dokumenteret her. Det, der følger, er slutpunkterne for kontostyring: verificering af, at et restaurant-ID tilhører kontohaveren, samt tilføjelse, opdatering eller fjernelse af det.

Zenchef #

Forbindelse af en Zenchef-restaurant er en to-trins bekræftelse, så kontohaveren beviser, at de rent faktisk driver restauranten, før den bliver forbundet til botten: tjek først, at ID’et eksisterer (uden at afsløre navnet), og få dem derefter til selv at indtaste restaurantens navn og bekræft, at det stemmer overens.

Trin 1 — Tjek om et restaurant-ID eksisterer

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, at ingen Zenchef-restaurant har det ID — der er ikke mere at gøre. Hastighedsbegrænset til 10 tjek pr. 5 minutter pr. konto; overskridelse returnerer 429.

Trin 2 — Bekræft restaurantens navn

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, at navnet ikke stemte overens — restaurantDetails udelades, bed kontohaveren om at prøve igen. Hastighedsbegrænset til 3 forsøg pr. 5 minutter (strammere end eksistenstjekket, da dette er selve bevisførelsen). Et restaurant_id, der ikke længere kan findes på Zenchef, returnerer 404.

Trin 3 — Gem restauranten

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

Opdater en gemt Zenchef-restaurant

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): samme format som gem-svaret ovenfor.

Fjern en Zenchef-restaurant

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, der ikke i øjeblikket er på kontoen, returnerer 404 ved opdatering eller sletning.

Formitable #

Formitable behøver ikke den to-trins navnebekræftelse, som Zenchef gør — dens restaurant-id’er er allerede afgrænset pr. virksomhed, så et enkelt bekræftelsesopkald er nok. Den har også et opslag af detaljer, der bruges til at cache restaurantens websteds-URL under opsætningen.

Bekræft et restaurant-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"
    }
  }
}

Et restaurant_id, som Formitable ikke genkender, returnerer 404. Hastighedsbegrænset til 10 forsøg pr. 5 minutter pr. konto.

Hent restaurantdetaljer

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

Henter restaurantens offentlige profil fra Formitable, inklusive dens websted — bruges til at cache websteds-URL’en, mens restauranten opsættes. language er en valgfri forespørgselsparameter, der som standard er "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"
  }
}

Gem restauranten

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

Opdater en gemt Formitable-restaurant

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): samme format som gem-svaret ovenfor.

Fjern en Formitable-restaurant

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, der ikke i øjeblikket er på kontoen, returnerer 404 ved opdatering eller sletning.

OpenTable #

OpenTable-restauranter nås gennem platformens OpenTable-partnerlegitimationsoplysninger, og OpenTable lader kun disse legitimationsoplysninger se restauranter, der har forbundet platformens registrering inde i OpenTable’s Integrations Marketplace. Så ligesom med Formitable er ét bekræftelsesopkald nok: et tilgængeligt Restaurant-ID (det numeriske “RID”) beviser både, at restauranten eksisterer, og at den har forbundet integrationen. Indtil OpenTable-partnerregistreringen er aktiveret på platformen, svarer bekræftelsesopkaldet med 503.

Verificer en OpenTable-restaurant

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, at ingen OpenTable-restaurant har det ID. En 403 betyder, at restauranten eksisterer, men endnu ikke har forbundet platformens integration inde i OpenTable. Hastighedsbegrænset til 10 forsøg pr. 5 minutter pr. konto.

Tilføj en OpenTable-restaurant

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

Opdater en gemt OpenTable-restaurant

PUT /appointments/opentable-restaurants/{restaurantId}

Send enhver af restaurant_name, is_active (pause med false) eller website_url (tom streng rydder den); udeladte felter forbliver uændrede.

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

Fjern en OpenTable-restaurant

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, der ikke i øjeblikket er på kontoen, returnerer 404 ved opdatering.

TheFork #

TheFork-restauranter nås gennem platformens TheFork-partnerlegitimationsoplysninger, og TheFork lader kun disse legitimationsoplysninger se restauranter, der har platformens partner aktiveret på deres TheFork-konto. Så ligesom med Formitable og OpenTable er ét bekræftelsesopkald nok: et tilgængeligt Restaurant-ID beviser både, at restauranten eksisterer, og at partneren er aktiveret på den. ID’et er den UUID, som TheFork giver restauranten i TheFork Manager, sendt som en streng. Indtil TheFork har godkendt platformen som partner og udstedt legitimationsoplysningerne, svarer bekræftelsesopkaldet 503 — se TheFork for hvad det betyder i dag.

Bekræft en TheFork-restaurant

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 er de gruppestørrelser, som restauranten tager imod online over de næste 30 dage. En 404 eller 403 betyder, at TheFork ikke ville give os en restaurant med det ID — enten er ID’et forkert, eller også er platformens partner endnu ikke aktiveret på den restaurant; en 400 betyder, at ID’et ikke er en UUID. Hastighedsbegrænset til 10 forsøg pr. 5 minutter pr. konto.

Tilføj en TheFork-restaurant

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

Opdater en gemt TheFork-restaurant

PUT /appointments/thefork-restaurants/{restaurantId}

Send enhver af restaurant_name, is_active (pause med false) eller website_url (tom streng rydder den); udeladte felter forbliver uændrede.

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

Fjern en TheFork-restaurant

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, der ikke i øjeblikket er på kontoen, returnerer 404 ved opdatering eller sletning.

Trafft #

Trafft forbindes én gang for hele kontoen, ikke pr. lokation: én virksomhedsadresse plus API-legitimationsoplysninger fra Trafft-administrationspanelet (Features & Integrations → API & Connectors, en del af Traffts Business-plan). Forbindelsesopkaldet tjekker disse legitimationsoplysninger mod Trafft, før noget gemmes, så en forkert adresse, forkerte legitimationsoplysninger eller en plan uden API-adgang fejler her i stedet for i en kundesamtale. Klienthemmeligheden gemmes krypteret og returneres aldrig af noget slutpunkt.

Alle tre skriveopkald (POST, PUT, DELETE) kræver redigerings-tilladelse til integrationer; status GET kræver visnings-tilladelse til integrationer.

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

Antallene kommer tilbage fra Trafft under tjekket — de er den hurtigste måde at bekræfte, at legitimationsoplysningerne peger på den konto, du mente.

Hent forbindelsesstatus

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, at intet er sat op endnu. Klienthemmeligheden er aldrig inkluderet i dette svar.

Opdater forbindelsen

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): det samme forbindelsesobjekt som GET ovenfor.

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

Afbrydelse fjerner kun de gemte legitimationsoplysninger. Aftaler, der allerede findes i Trafft, forbliver uberørte.

Fejlformat på alle Zenchef/Formitable/OpenTable/TheFork-slutpunkter: i modsætning til resten af denne side indeholder fejl her deres status to gange — én gang som HTTP-status og én gang som error_code i brødteksten — for eksempel { "success": false, "error": "Restaurant not found", "error_code": 404 }. Håndter det på samme måde som enhver anden fejl: tjek success, læs error for meddelelsen.

Fejl i Appointments API #

Appointment-slutpunkter returnerer standard-fejlkuverten:

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

De delte koder, som ethvert endpoint kan returnere — 401, 403 (din plan inkluderer ikke API-adgang), 429 (rate limit) og 500 — er angivet med vejledning om genforsøg i Errors & Pagination.

Næste skridt #

• Kontakter — opret og find de kontakter, du booker for.
• Beskeder og samtaler — send en bekræftelse eller påmindelse til en kontakt.
• Webhooks — få besked, når aftaler ændres.