Slot booking

The slot-booking endpoints let a partner app book a video-call verification appointment for an applicant: list the free time intervals on a date, save a meeting request for one of them, then read, move or cancel it. Bookings land on the same scheduling engine the hosted flow uses, so agents see them under Video Calls → Upcoming bookings, the applicant is reminded when joining opens, and the call runs in the verification session's Video Call step.

The two core calls keep the widely used slot-booking contract — the same paths, field names, DD/MM/YYYY dates, 24-hour preferredTime, "hh:mm AM/PM" slot times, the flat [{id, time}] list and the {message, status, data: {meetingRequestId}} booking response — so an app that already integrates a backend with this contract switches by changing its base URL and adding the API key header — even the numeric purposeId it already sends keeps working once the workflow is given that code (see Purpose codes).

Endpoints

{meeting_request} is either the booking's booking_id (uuid) or its meetingRequestId (000000324 — zero padding optional).

How the contract maps onto ThirdFactor

ThirdFactor adds, alongside the contract's keys: booking_id, session_id and session_url (the verification session hosting the call and the link the applicant joins from), booking_status, queue_state (where the call stands for agents), workflow_id, and the slot's starts_at / ends_at as ISO 8601 instants. None of the contract's keys change shape.

Purpose codes

Every workflow of your tenant is numbered once, in creation order, and keeps its number — that 9-digit code is its purposeId. GET /v3/meeting-purpose lists the bookable ones; Console → Video calls → Availability → Booking API purposes shows every workflow's code with a copy button, and an admin with Manage KYC can renumber a workflow — e.g. to 000000011, the purposeId an existing integration already hard-codes — so that integration needs no change. Codes are unique per tenant and never reused.

No session needed — or bring your own

A booking needs no verification session up front. When you send applicant details without session_id, the booking creates the session that will host the call:

• It runs the purpose workflow, with the applicant's name, email and phone filled in, and stays open until a day after the booked slot.
• It is charged like POST /v3/session/ — the SESSION_CREATE rate (1 credit unless your platform manager set another). A booking the balance can't cover is refused with 402 and nothing is booked.
• The applicant gets a confirmation with the verification link — by email (with an add-to-calendar link) when you sent one, else by SMS — and a reminder 10 minutes before the slot, when joining opens. Send notify: false if you message the applicant yourself.
• Open session_url for the applicant at the booked time (in a web view, or send it on). The hosted flow runs the workflow's steps and puts them in the call; a booked applicant is served ahead of walk-ups once the slot is due. An applicant who opens the link early can join straight away: they wait in the agents' queue — shown as waiting for their booked time — and an agent may take them before it (queue_state: "waiting").

Already created a session with POST /v3/session/? Book its Video Call step by sending session_id instead — purposeId and the applicant details become optional, nothing is charged, and the slot must start before that session expires.

Switching an existing integration

Add an Idempotency-Key header to save while you're there — a fresh value per booking attempt makes a retried booking safe (see Idempotency).

Try it in the API Explorer

The API Explorer sends real requests to your tenant — put your API key in x-api-key, then:

1. GET /v3/meeting-purpose — copy a purpose's id (e.g. 000000001).
2. POST /v3/meeting-time/get-available — set purposeId to that id and date to a future working day within the next 14 days that your agents have availability on (DD/MM/YYYY). The example's date is only a sample: a past date, or a day nobody works, lists []. Copy an interval's id and time.
3. POST /v3/meeting-request/save — same purposeId, the date as preferredDate, the interval's id as timeIntervalId and its time in 24-hour form as preferredTime (01:00 PM → 13:00). Leave Idempotency-Key empty, or give every attempt a fresh value — reusing one for a different booking is refused with 422 idempotency_key_reused.

List booking purposes

GET /v3/meeting-purpose
x-api-key: <tenant_api_key>

[
  {
    "id": "000000001",
    "workflow_id": "b2c1e9f0-4a3d-4c1b-9e2a-8f7d6c5b4a30",
    "name": "Video KYC",
    "timezone": "Asia/Kathmandu",
    "schedule_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "schedule_name": "Branch hours"
  }
]

Only workflows whose Video Call step allows appointment booking are listed (archived workflows never are). id is the numeric purposeId to send; workflow_id (the same purpose's UUID) is accepted too. schedule_id is null when no availability schedule governs the workflow — then only hand-published one-off slots are offered.

Get available time intervals

POST /v3/meeting-time/get-available
x-api-key: <tenant_api_key>
Content-Type: application/json

{
  "date": "05/10/2026",
  "purposeId": "000000001"
}

[
  { "id": "fe65740f-f776-4eec-a607-22c59fb3b1db", "time": "12:30 PM" },
  { "id": "374b53f3-d7ed-464c-ac0f-06e4167f2cf6", "time": "01:00 PM" },
  { "id": "5f4f786c-520f-4668-afd3-64087e80eaad", "time": "01:30 PM" }
]

[
  {
    "id": "374b53f3-d7ed-464c-ac0f-06e4167f2cf6",
    "time": "01:00 PM",
    "time_24h": "13:00",
    "date": "05/10/2026",
    "starts_at": "2026-10-05T13:00:00+05:45",
    "ends_at": "2026-10-05T13:30:00+05:45",
    "seats_left": 2,
    "timezone": "Asia/Kathmandu"
  }
]

The response is a bare JSON array of exactly {id, time}, soonest first — [] when nothing is free, exactly as the contract returns it. Send the chosen time to save as 24-hour preferredTime (01:00 PM → 13:00); with details: true, time_24h and date are those values ready-made.

An interval is listed only when it can really be booked:

• Inside the agents' availability — generated from the purpose schedule's weekly windows, or published by hand as a one-off. Switching a schedule off stops its hours being offered.
• Not started yet — past intervals, and intervals already under way today, are never listed.
• With a seat left — capacity comes from the availability window. Several agents available at the same time appear once, with their seats summed in seats_left; booking that id takes whichever of them is free.
• Within the booking horizon — slots are offered up to 14 days ahead. A date in the past or beyond the horizon returns [].

Availability an admin saves is bookable immediately — listed here, in the hosted flow's picker and on the console's slot list at once, with no refresh.

Book a time interval

POST /v3/meeting-request/save
x-api-key: <tenant_api_key>
Idempotency-Key: <a new UUID per booking attempt — optional>
Content-Type: application/json

{
  "email": "[email protected]",
  "existingCustomer": false,
  "fullname": "Sita Sharma",
  "phone": "9800000001",
  "preferredDate": "05/10/2026",
  "preferredTime": "13:00",
  "purposeId": "000000001",
  "timeIntervalId": "374b53f3-d7ed-464c-ac0f-06e4167f2cf6",
  "title": "Sita Sharma"
}

{
  "message": "Saved the Meeting Request data.",
  "status": "CREATED",
  "data": {
    "meetingRequestId": "000000324",
    "booking_id": "7f1c2a90-4b6d-4e15-9a02-3d8c1b7e5f44",
    "booking_status": "CONFIRMED",
    "queue_state": "scheduled",
    "applicant_waiting": false,
    "applicant_joined_at": null,
    "purposeId": "000000001",
    "workflow_id": "b2c1e9f0-4a3d-4c1b-9e2a-8f7d6c5b4a30",
    "purpose_name": "Video KYC",
    "timeIntervalId": "374b53f3-d7ed-464c-ac0f-06e4167f2cf6",
    "preferredDate": "05/10/2026",
    "preferredTime": "13:00",
    "time": "01:00 PM",
    "starts_at": "2026-10-05T13:00:00+05:45",
    "ends_at": "2026-10-05T13:30:00+05:45",
    "timezone": "Asia/Kathmandu",
    "session_id": "6f0e2b7a-1c2d-4e5f-8a9b-0c1d2e3f4a5b",
    "session_url": "https://acme.v3.thirdfactor.ai/verify/Qm9va2luZy10b2tlbg",
    "applicant": {
      "fullname": "Sita Sharma",
      "email": "[email protected]",
      "phone": "9800000001",
      "title": "Sita Sharma",
      "existingCustomer": false
    },
    "video_call": {
      "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
      "status": "waiting",
      "verdict": null
    },
    "cancelled_at": null,
    "cancel_reason": "",
    "created_at": "2026-09-24T08:15:02.118000+00:00",
    "updated_at": "2026-09-24T08:15:02.301000+00:00"
  }
}

status names the HTTP status — CREATED here, OK on the other calls; the booking's own state is data.booking_status. Treat any 2xx as success.

The time must be the interval's. preferredTime is checked against timeIntervalId in the purpose's timezone; a different time is 422 slot_mismatch, naming the interval's own start time in message and errors, so a mixed-up pick never books the wrong hour. An interval is a time of day: the same timeIntervalId with another preferredDate books that interval on that date (422 slot_mismatch on preferredDate when there is no such interval then). An id that is no longer offered — availability was edited since you listed — books the free interval at preferredDate + preferredTime instead; data.timeIntervalId always names the interval actually booked.

Seats are claimed atomically. Two requests racing for the last seat can't both win: the second gets 409 slot_full, and nothing — no booking, no session, no charge — is left behind. If the id you sent filled up but another agent is free at the very same time, that seat is booked instead (data.timeIntervalId tells you which).

Booking status

GET /v3/meeting-request/{meeting_request}
x-api-key: <tenant_api_key>

Returns {message: "Fetched the Meeting Request data.", status: "OK", data} with the same data as save. booking_status follows the call itself, so it also reflects what happened outside this API — the applicant moving or cancelling the appointment from their verification link, the agent taking the call, its outcome:

CONFIRMED and RESCHEDULED are upcoming; IN_PROGRESS is live; COMPLETED, NO_SHOW and CANCELLED are final — except that a NO_SHOW whose call is still waiting can be rescheduled or cancelled.

queue_state says where the call stands for agents meanwhile:

An applicant still waiting in the queue after their slot ended is not a NO_SHOW — they came; the booking stays upcoming until an agent takes them.

The full verification outcome (documents, liveness, the agent's notes and recording) is on the session: GET /v3/session/{session_id}/decision/.

Reschedule

POST /v3/meeting-request/{meeting_request}/reschedule
x-api-key: <tenant_api_key>
Idempotency-Key: <unique-per-move>
Content-Type: application/json

{
  "preferredDate": "05/10/2026",
  "preferredTime": "14:30",
  "timeIntervalId": "2a99dc6d-cc5f-403d-b97a-0bcf81d79e39"
}

Pick the new interval from get-available and send it exactly as for save (optionally with notify, which then applies from here on). The old seat is released and the new one taken in one step — a refused move leaves the booking where it was. booking_status becomes RESCHEDULED and the applicant is told the new time. A session the booking created stays open until a day after the new slot.

Refused with 409: booking_not_modifiable when the booking is IN_PROGRESS, COMPLETED or CANCELLED (the body carries booking_status), slot_unchanged when it already holds that time, and slot_full / slot_in_past as for save.

Cancel

POST /v3/meeting-request/{meeting_request}/cancel
x-api-key: <tenant_api_key>
Content-Type: application/json

{ "reason": "Customer asked to cancel" }

Frees the seat and sets booking_status to CANCELLED; reason (optional, up to 255 characters) comes back as cancel_reason. If the booking created its own verification session and the applicant never opened it, that session is retired too — its link stops working and it expires like any unused session. A session you created yourself is left alone.

Status reads and cancellations keep working even if Video Call is later switched off for your tenant, so existing bookings can always be released. IN_PROGRESS, COMPLETED and already-CANCELLED bookings answer 409 booking_not_modifiable.

Idempotency

Send an Idempotency-Key header (any string up to 128 characters) on save, reschedule and cancel — a new value for every attempt, e.g. a UUID from uuidgen or crypto.randomUUID(). It is optional: leave it out (or empty in the API Explorer) when you don't need retry safety.

Keys are per tenant and remembered for the life of the booking. A replay returns the response as it was when first made; read GET /v3/meeting-request/{meeting_request} for the booking's current state.

Errors

Every error — validation, business rules, authentication, throttling and malformed JSON alike — uses one envelope:

{
  "message": "That time interval is fully booked — fetch fresh slots and pick another.",
  "status": "CONFLICT",
  "detail": "slot_full",
  "data": null
}

Branch on the HTTP status first, then on detail — always a stable machine code. status names the HTTP status; message is a sentence you can log or show an operator. Validation errors add errors, a per-field map of messages; some refusals add context keys (features, booking_status, booking_id, meetingRequestId, retry_after).

End to end

curl -X POST "https://<your-domain>/v3/meeting-time/get-available" \
  -H "x-api-key: $TF_API_KEY" -H "Content-Type: application/json" \
  -d '{"date": "05/10/2026", "purposeId": "000000001"}'

curl -X POST "https://<your-domain>/v3/meeting-request/save" \
  -H "x-api-key: $TF_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email": "[email protected]", "existingCustomer": false,
       "fullname": "Sita Sharma", "phone": "9800000001",
       "preferredDate": "05/10/2026", "preferredTime": "13:00",
       "purposeId": "000000001",
       "timeIntervalId": "374b53f3-d7ed-464c-ac0f-06e4167f2cf6",
       "title": "Sita Sharma"}'

Try every call live in the API Explorer under Slot Booking.