--- title: "Find availability" description: "Find the free appointment times for one patient and one service. With no date it answers with the soonest day that has room; with a date it answers for that day. times[] are the hours you may book, otherDates[] are other days that month with room, and otherProfessionals[] are the other doctors who see this service. Offer two or three times, never the whole list.\n\n- **Scopes:** any one of `sura:appointments:read`, `sura:appointments:write`\n- **Credentials:** an API key, a client-credentials token or a person's access token\n- **Effect:** read-only; safe to retry\n- **Limits:** request body up to 32 KB, response up to 256 KB\n- **CLI:** `arbol sura availability lookup` · **MCP tool:** `sura_availability_lookup`" --- > 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 › Availability `POST /v1/sura/availability/lookup` Find the free appointment times for one patient and one service. With no date it answers with the soonest day that has room; with a date it answers for that day. times[] are the hours you may book, otherDates[] are other days that month with room, and otherProfessionals[] are the other doctors who see this service. Offer two or three times, never the whole list. - **Scopes:** any one of `sura:appointments:read`, `sura:appointments:write` - **Credentials:** an API key, a client-credentials token or a person's access token - **Effect:** read-only; safe to retry - **Limits:** request body up to 32 KB, response up to 256 KB - **CLI:** `arbol sura availability lookup` · **MCP tool:** `sura_availability_lookup` ## Authentication Requires one of the following: - `arbolHuman`, oauth2, scopes: `sura:appointments:read` - `arbolHuman`, oauth2, scopes: `sura:appointments:write` - `arbolMachine`, oauth2, scopes: `sura:appointments:read` - `arbolMachine`, oauth2, scopes: `sura:appointments:write` - `arbolApiKey`, http, header `Authorization` ## Request body _Required._ - `documentNumber` (`sura.availability.lookup.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.availability.lookup.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.availability.lookup.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.availability.lookup.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. - `date` (`sura.availability.lookup.date`; string | null, optional) — A day to look at, as YYYY-MM-DD. Omit it for the soonest day with room. Resolve relative dates like "mañana" against the clinic's own timezone before calling. - `professional` (`sura.availability.lookup.professional`; string | null, optional) — Doctor's name, or part of it, when the caller asked for someone specific. Use list_professionals to check the service's registered doctors independently of available slots; absence from an open-agenda selector does not mean the doctor does not exist. Omit it to see whoever has room soonest. - `agentMode` (`sura.availability.lookup.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.availability.lookup.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.availability.lookup.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", "date": "string", "documentNumber": "string", "documentType": "ASI", "professional": "string", "serviceId": "string", "agentMode": false, "connectionId": "string", "channel": "voice" } ``` ## Code samples ### cURL ```bash curl https://api.getarbol.com/v1/sura/availability/lookup \ --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.availability.lookup({ 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() .availability() .lookup(&types::SuraAvailabilityLookupInput { document_number: "".into(), document_type: types::SuraAvailabilityLookupInputDocumentType::CC, service_id: "".into(), area_id: None, date: None, professional: None, agent_mode: None, connection_id: None, channel: None, }) .await?; ``` ### CLI ```bash arbol sura availability lookup --document-number '' --document-type CC --service-id '' ``` ### MCP ```json { "name": "sura_availability_lookup", "arguments": { "documentNumber": "", "documentType": "CC", "serviceId": "" } } ``` ## Responses ### 200 Successful operation. #### Body (application/json) - `success` (`sura.availability.lookup.response.200.success`; boolean, required) - one of `true` - `data` (`sura.availability.lookup.response.200.data`; any of, required) - any of: `SuraPendingResult`, `SuraRefusal`, `SuraPatientNotFound`, `SuraAvailability` - `error` (`sura.availability.lookup.response.200.error`; unknown, required) - `metadata` (`sura.availability.lookup.response.200.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.400.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.400.data`; unknown, required) - `error` (`sura.availability.lookup.response.400.error`; object, required) — The request does not match the published schema. - `code` (`sura.availability.lookup.response.400.error.code`; string, required) — The failure code, stable across releases. - one of `"INVALID_INPUT"` - `message` (`sura.availability.lookup.response.400.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.400.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.400.error.data`; object, required) - `issues` (`sura.availability.lookup.response.400.error.data.issues`; array, optional) - `path` (`sura.availability.lookup.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.availability.lookup.response.400.error.data.issues.message`; string, required) - maxLength 256 - `metadata` (`sura.availability.lookup.response.400.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.401.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.401.data`; unknown, required) - `error` (`sura.availability.lookup.response.401.error`; object, required) — A valid access token is required. - `code` (`sura.availability.lookup.response.401.error.code`; string, required) — The failure code, stable across releases. - one of `"UNAUTHORIZED"` - `message` (`sura.availability.lookup.response.401.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.401.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.401.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.401.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.403.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.403.data`; unknown, required) - `error` (`sura.availability.lookup.response.403.error`; object, required) — The token does not authorize this operation. - `code` (`sura.availability.lookup.response.403.error.code`; string, required) — The failure code, stable across releases. - one of `"FORBIDDEN"` - `message` (`sura.availability.lookup.response.403.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.403.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.403.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.403.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.404.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.404.data`; unknown, required) - `error` (`sura.availability.lookup.response.404.error`; object, required) — The organization has no such connection. - `code` (`sura.availability.lookup.response.404.error.code`; string, required) — The failure code, stable across releases. - one of `"CONNECTION_NOT_FOUND"` - `message` (`sura.availability.lookup.response.404.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.404.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.404.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.404.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.409.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.409.data`; unknown, required) - `error` (`sura.availability.lookup.response.409.error`; one of, required) - one of: `SuraPortalSessionConflictFailure`, `SuraConnectionNotConfiguredFailure` - discriminator: `code` - `metadata` (`sura.availability.lookup.response.409.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.413.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.413.data`; unknown, required) - `error` (`sura.availability.lookup.response.413.error`; object, required) — The request exceeds the allowed size. - `code` (`sura.availability.lookup.response.413.error.code`; string, required) — The failure code, stable across releases. - one of `"REQUEST_TOO_LARGE"` - `message` (`sura.availability.lookup.response.413.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.413.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.413.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.413.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.415.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.415.data`; unknown, required) - `error` (`sura.availability.lookup.response.415.error`; object, required) — The request content type is not supported. - `code` (`sura.availability.lookup.response.415.error.code`; string, required) — The failure code, stable across releases. - one of `"UNSUPPORTED_MEDIA_TYPE"` - `message` (`sura.availability.lookup.response.415.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.415.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.415.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.415.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.429.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.429.data`; unknown, required) - `error` (`sura.availability.lookup.response.429.error`; object, required) — The request rate limit was exceeded. Try again later. - `code` (`sura.availability.lookup.response.429.error.code`; string, required) — The failure code, stable across releases. - one of `"RATE_LIMITED"` - `message` (`sura.availability.lookup.response.429.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.429.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.availability.lookup.response.429.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.429.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.500.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.500.data`; unknown, required) - `error` (`sura.availability.lookup.response.500.error`; object, required) — The service could not complete the operation. - `code` (`sura.availability.lookup.response.500.error.code`; string, required) — The failure code, stable across releases. - one of `"INTERNAL_ERROR"` - `message` (`sura.availability.lookup.response.500.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.500.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.availability.lookup.response.500.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.500.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.502.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.502.data`; unknown, required) - `error` (`sura.availability.lookup.response.502.error`; one of, required) - one of: `OutcomeUnknownFailure`, `SuraPortalCredentialsRejectedFailure`, `SuraPortalUnavailableFailure` - discriminator: `code` - `metadata` (`sura.availability.lookup.response.502.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.503.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.503.data`; unknown, required) - `error` (`sura.availability.lookup.response.503.error`; object, required) — The upstream service could not complete the request. - `code` (`sura.availability.lookup.response.503.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_UNAVAILABLE"` - `message` (`sura.availability.lookup.response.503.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.503.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.availability.lookup.response.503.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.503.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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.availability.lookup.response.504.success`; boolean, required) - one of `false` - `data` (`sura.availability.lookup.response.504.data`; unknown, required) - `error` (`sura.availability.lookup.response.504.error`; object, required) — The upstream service did not respond before its deadline. - `code` (`sura.availability.lookup.response.504.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_TIMEOUT"` - `message` (`sura.availability.lookup.response.504.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.availability.lookup.response.504.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.availability.lookup.response.504.error.data`; object, required) — No fields. - `metadata` (`sura.availability.lookup.response.504.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.availability.lookup.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/availability/lookup/index.md