--- title: "Book an appointment" description: "Book one appointment at an exact moment for one patient: startsAt, exactly as an option or the ready booking arguments answered it (or the former date and time). Only call it after the caller has confirmed the day, the hour and the service out loud. The moment must be one that find_availability just returned; the tool re-checks it against the live agenda and refuses if it was taken in the meantime. ok:true with booked:true means the appointment exists.\n\n- **Scope:** `sura:appointments:write`\n- **Credentials:** an API key, a client-credentials token or a person's access token\n- **Effect:** writes; not idempotent: check the outcome before you retry\n- **Limits:** request body up to 32 KB, response up to 256 KB\n- **CLI:** `arbol sura appointments create` · **MCP tool:** `sura_appointments_create`" --- > Documentation Index > Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt > Use this file to discover all available pages before exploring further. Path: SURA API › Appointments `POST /v1/sura/appointments` Book one appointment at an exact moment for one patient: startsAt, exactly as an option or the ready booking arguments answered it (or the former date and time). Only call it after the caller has confirmed the day, the hour and the service out loud. The moment must be one that find_availability just returned; the tool re-checks it against the live agenda and refuses if it was taken in the meantime. ok:true with booked:true means the appointment exists. - **Scope:** `sura:appointments:write` - **Credentials:** an API key, a client-credentials token or a person's access token - **Effect:** writes; not idempotent: check the outcome before you retry - **Limits:** request body up to 32 KB, response up to 256 KB - **CLI:** `arbol sura appointments create` · **MCP tool:** `sura_appointments_create` ## Authentication Requires one of the following: - `arbolHuman`, oauth2, scopes: `sura:appointments:write` - `arbolMachine`, oauth2, scopes: `sura:appointments:write` - `arbolApiKey`, http, header `Authorization` ## Request body _Required._ - `documentNumber` (`sura.appointments.create.documentNumber`; string, required) — Complete document number of the patient receiving care, from readable original evidence or their message. Normalize separators without changing digits. Request correction only for missing, illegible or conflicting identity; never guess digits. - `documentType` (`sura.appointments.create.documentType`; string, required) — Patient document type read legibly from the original or explicitly supplied. Ask only if unknown or genuinely conflicting; never infer it from age or number length. - one of `"ASI"`, `"CC"`, `"CD"`, `"CE"`, `"CN"`, `"DE"`, `"IFE"`, `"MS"`, `"NIT"`, `"NUIP"`, `"PA"`, `"PC"`, `"PD"`, `"PE"`, `"PF"`, `"PT"`, `"RC"`, `"RCP"`, `"RES"`, `"SC"`, `"TE"`, `"TI"` - `serviceId` (`sura.appointments.create.serviceId`; string, required) — What the appointment is for: either an id from list_services or the service's own name, in the caller's words ("neurología", "control"). A name that matches more than one service is answered with the choices, so you can ask which one instead of guessing. - `areaId` (`sura.appointments.create.areaId`; string | null, optional) — The areaId list_services returned beside that service. Pass it with an exact serviceId to skip a catalog lookup; omit it whenever you are naming the service in words. - `idempotencyKey` (`sura.appointments.create.idempotencyKey`; string | null, optional) — Stable 32-character lowercase hexadecimal command key supplied by a trusted coordinator. Reuse it only for the same accepted offer. - `professional` (`sura.appointments.create.professional`; string | null, optional) — Doctor's name when the caller chose one. Pass the same value used in find_availability, so the hour booked is that doctor's. - `startsAt` (`sura.appointments.create.startsAt`; string, optional) — The appointment's moment, as an RFC 3339 instant with its offset, exactly as an answer gave it in startsAt (for example "2026-11-04T17:00:00-05:00"). Send it in place of the former date and time; sent beside them, they must name the same moment. - format `date-time` - `date` (`sura.appointments.create.date`; string, optional, deprecated) — Deprecated: use `startsAt`. Answered until 2027-01-28. - `time` (`sura.appointments.create.time`; string, optional, deprecated) — Deprecated: use `startsAt`. Answered until 2027-01-28. - `agentMode` (`sura.appointments.create.agentMode`; boolean, optional) — Set agentMode=true when calling this tool for an AI agent. The answer is concise Spanish text instead of JSON. Omit it for structured machine data. This changes presentation only, never authorization, consent or idempotency. - default `false` - `connectionId` (`sura.appointments.create.connectionId`; string, optional) — Which of the organization's SURA connections to run on, by its id. Optional while the organization has one; required when it has several. - minLength 1; maxLength 128 - `channel` (`sura.appointments.create.channel`; string, optional) — The channel the caller is waiting on, which sets how long it waits before an answer comes back pending, and puts a phone call's reads ahead of others. Defaults to web. - one of `"voice"`, `"whatsapp"`, `"web"` ## Example request ```json { "areaId": "string", "documentNumber": "string", "documentType": "ASI", "idempotencyKey": "string", "professional": "string", "serviceId": "string", "startsAt": "2019-08-24T14:15:22Z", "date": "string", "time": "string", "agentMode": false, "connectionId": "string", "channel": "voice" } ``` ## Code samples ### cURL ```bash curl https://api.getarbol.com/v1/sura/appointments \ --request POST \ --header "Authorization: Bearer $ARBOL_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "documentNumber": "", "documentType": "CC", "serviceId": "" }' ``` ### TypeScript ```typescript import { createClient } from "@arbol-ai/sdk"; const arbol = createClient({ baseUrl: "https://api.getarbol.com", token: process.env.ARBOL_API_KEY!, }); const { data } = await arbol.sura.appointments.create({ documentNumber: "", documentType: "CC", serviceId: "", }); ``` ### Rust ```rust use arbol_sdk::{types, Client, Credential}; let arbol = Client::new(Credential::ApiKey(std::env::var("ARBOL_API_KEY")?))?; let data = arbol .sura() .appointments() .create(&types::SuraAppointmentsCreateInput { document_number: "".into(), document_type: types::SuraAppointmentsCreateInputDocumentType::CC, service_id: "".into(), area_id: None, idempotency_key: None, professional: None, starts_at: None, date: None, time: None, agent_mode: None, connection_id: None, channel: None, }) .await?; ``` ### CLI ```bash arbol sura appointments create --document-number '' --document-type CC --service-id '' ``` ### MCP ```json { "name": "sura_appointments_create", "arguments": { "documentNumber": "", "documentType": "CC", "serviceId": "" } } ``` ## Responses ### 200 Successful operation. #### Body (application/json) - `success` (`sura.appointments.create.response.200.success`; boolean, required) - one of `true` - `data` (`sura.appointments.create.response.200.data`; any of, required) - any of: `SuraPendingResult`, `SuraRefusal`, `SuraPatientNotFound`, `SuraBookedAppointment` - `error` (`sura.appointments.create.response.200.error`; unknown, required) - `metadata` (`sura.appointments.create.response.200.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.200.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": true, "data": { "ai_hint": "string", "ok": true, "operationId": "string", "position": 0, "retryAfterSeconds": 1, "status": "pending" }, "error": null, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 400 `INVALID_INPUT`: The request does not match the published schema. #### Body (application/json) - `success` (`sura.appointments.create.response.400.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.400.data`; unknown, required) - `error` (`sura.appointments.create.response.400.error`; object, required) — The request does not match the published schema. - `code` (`sura.appointments.create.response.400.error.code`; string, required) — The failure code, stable across releases. - one of `"INVALID_INPUT"` - `message` (`sura.appointments.create.response.400.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.400.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.400.error.data`; object, required) - `issues` (`sura.appointments.create.response.400.error.data.issues`; array, optional) - `path` (`sura.appointments.create.response.400.error.data.issues.path`; string, required) — RFC 6901 JSON Pointer to the refused field; empty for the whole input. - maxLength 256 - `message` (`sura.appointments.create.response.400.error.data.issues.message`; string, required) - maxLength 256 - `metadata` (`sura.appointments.create.response.400.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.400.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "INVALID_INPUT", "message": "string", "retryable": false, "data": { "issues": [ { "path": "string", "message": "string" } ] } }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 401 `UNAUTHORIZED`: A valid access token is required. #### Body (application/json) - `success` (`sura.appointments.create.response.401.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.401.data`; unknown, required) - `error` (`sura.appointments.create.response.401.error`; object, required) — A valid access token is required. - `code` (`sura.appointments.create.response.401.error.code`; string, required) — The failure code, stable across releases. - one of `"UNAUTHORIZED"` - `message` (`sura.appointments.create.response.401.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.401.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.401.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.401.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.401.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "UNAUTHORIZED", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 403 `FORBIDDEN`: The token does not authorize this operation. #### Body (application/json) - `success` (`sura.appointments.create.response.403.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.403.data`; unknown, required) - `error` (`sura.appointments.create.response.403.error`; object, required) — The token does not authorize this operation. - `code` (`sura.appointments.create.response.403.error.code`; string, required) — The failure code, stable across releases. - one of `"FORBIDDEN"` - `message` (`sura.appointments.create.response.403.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.403.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.403.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.403.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.403.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 404 `CONNECTION_NOT_FOUND`: The organization has no such connection. #### Body (application/json) - `success` (`sura.appointments.create.response.404.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.404.data`; unknown, required) - `error` (`sura.appointments.create.response.404.error`; object, required) — The organization has no such connection. - `code` (`sura.appointments.create.response.404.error.code`; string, required) — The failure code, stable across releases. - one of `"CONNECTION_NOT_FOUND"` - `message` (`sura.appointments.create.response.404.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.404.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.404.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.404.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.404.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "CONNECTION_NOT_FOUND", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 409 - `PORTAL_SESSION_CONFLICT`: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team. - `CONNECTION_NOT_CONFIGURED`: The organization has no SURA connection that can run this operation. #### Body (application/json) - `success` (`sura.appointments.create.response.409.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.409.data`; unknown, required) - `error` (`sura.appointments.create.response.409.error`; one of, required) - one of: `SuraPortalSessionConflictFailure`, `SuraConnectionNotConfiguredFailure` - discriminator: `code` - `metadata` (`sura.appointments.create.response.409.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.409.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "PORTAL_SESSION_CONFLICT", "message": "string", "retryable": true }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 413 `REQUEST_TOO_LARGE`: The request exceeds the allowed size. #### Body (application/json) - `success` (`sura.appointments.create.response.413.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.413.data`; unknown, required) - `error` (`sura.appointments.create.response.413.error`; object, required) — The request exceeds the allowed size. - `code` (`sura.appointments.create.response.413.error.code`; string, required) — The failure code, stable across releases. - one of `"REQUEST_TOO_LARGE"` - `message` (`sura.appointments.create.response.413.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.413.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.413.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.413.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.413.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "REQUEST_TOO_LARGE", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 415 `UNSUPPORTED_MEDIA_TYPE`: The request content type is not supported. #### Body (application/json) - `success` (`sura.appointments.create.response.415.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.415.data`; unknown, required) - `error` (`sura.appointments.create.response.415.error`; object, required) — The request content type is not supported. - `code` (`sura.appointments.create.response.415.error.code`; string, required) — The failure code, stable across releases. - one of `"UNSUPPORTED_MEDIA_TYPE"` - `message` (`sura.appointments.create.response.415.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.415.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.415.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.415.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.415.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 429 `RATE_LIMITED`: The request rate limit was exceeded. Try again later. #### Body (application/json) - `success` (`sura.appointments.create.response.429.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.429.data`; unknown, required) - `error` (`sura.appointments.create.response.429.error`; object, required) — The request rate limit was exceeded. Try again later. - `code` (`sura.appointments.create.response.429.error.code`; string, required) — The failure code, stable across releases. - one of `"RATE_LIMITED"` - `message` (`sura.appointments.create.response.429.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.429.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.appointments.create.response.429.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.429.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.429.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "RATE_LIMITED", "message": "string", "retryable": true, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 500 `INTERNAL_ERROR`: The service could not complete the operation. #### Body (application/json) - `success` (`sura.appointments.create.response.500.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.500.data`; unknown, required) - `error` (`sura.appointments.create.response.500.error`; object, required) — The service could not complete the operation. - `code` (`sura.appointments.create.response.500.error.code`; string, required) — The failure code, stable across releases. - one of `"INTERNAL_ERROR"` - `message` (`sura.appointments.create.response.500.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.500.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.appointments.create.response.500.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.500.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.500.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "INTERNAL_ERROR", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 502 - `OUTCOME_UNKNOWN`: The operation may have been applied; check its result before repeating it. - `PORTAL_CREDENTIALS_REJECTED`: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team. - `PORTAL_UNAVAILABLE`: The organization's connection to this integration couldn't complete the request. Don't retry it automatically; if it keeps happening, contact your Arbol team. #### Body (application/json) - `success` (`sura.appointments.create.response.502.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.502.data`; unknown, required) - `error` (`sura.appointments.create.response.502.error`; one of, required) - one of: `OutcomeUnknownFailure`, `SuraPortalCredentialsRejectedFailure`, `SuraPortalUnavailableFailure` - discriminator: `code` - `metadata` (`sura.appointments.create.response.502.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.502.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "OUTCOME_UNKNOWN", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 503 `UPSTREAM_UNAVAILABLE`: The upstream service could not complete the request. #### Body (application/json) - `success` (`sura.appointments.create.response.503.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.503.data`; unknown, required) - `error` (`sura.appointments.create.response.503.error`; object, required) — The upstream service could not complete the request. - `code` (`sura.appointments.create.response.503.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_UNAVAILABLE"` - `message` (`sura.appointments.create.response.503.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.503.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.appointments.create.response.503.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.503.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.503.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "string", "retryable": true, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` ### 504 `UPSTREAM_TIMEOUT`: The upstream service did not respond before its deadline. #### Body (application/json) - `success` (`sura.appointments.create.response.504.success`; boolean, required) - one of `false` - `data` (`sura.appointments.create.response.504.data`; unknown, required) - `error` (`sura.appointments.create.response.504.error`; object, required) — The upstream service did not respond before its deadline. - `code` (`sura.appointments.create.response.504.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_TIMEOUT"` - `message` (`sura.appointments.create.response.504.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.appointments.create.response.504.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.appointments.create.response.504.error.data`; object, required) — No fields. - `metadata` (`sura.appointments.create.response.504.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.appointments.create.response.504.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "UPSTREAM_TIMEOUT", "message": "string", "retryable": true, "data": {} }, "metadata": { "requestId": "string" } } ``` #### Body (text/plain) ##### Example ```text string ``` Source: https://docs.getarbol.com/api/sura/appointments/create/index.md