--- title: "List registered professionals" description: "List SURA's registered professionals for a service at this connection's institution, including doctors without published or free appointments. First obtain serviceId and optionally areaId from list_services. No patient identity is needed. Follow pageInfo.nextCursor while hasNextPage is true before concluding a name is absent from this scoped directory. Absence does not establish that a doctor does not exist or works nowhere else. Registration does not establish coverage, authorization, or availability: use prepare_appointment with the patient's evidence and the requested professional name to find actual slots. Never substitute another doctor without the patient's agreement. An unreadable or incomplete provider directory is a technical failure, not an empty list. A refusal, or a call still running, is the failure TOOL_REFUSED: data.reason says why, data.guidance what to do next and data.details what it offers instead (OPERATION_PENDING: poll data.details.operationId with operations.get); it is never an outage.\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:** response up to 256 KB\n- **CLI:** `arbol sura professionals list` · **MCP tool:** `sura_professionals_list`" --- > 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 › Professionals `GET /v1/sura/professionals` List SURA's registered professionals for a service at this connection's institution, including doctors without published or free appointments. First obtain serviceId and optionally areaId from list_services. No patient identity is needed. Follow pageInfo.nextCursor while hasNextPage is true before concluding a name is absent from this scoped directory. Absence does not establish that a doctor does not exist or works nowhere else. Registration does not establish coverage, authorization, or availability: use prepare_appointment with the patient's evidence and the requested professional name to find actual slots. Never substitute another doctor without the patient's agreement. An unreadable or incomplete provider directory is a technical failure, not an empty list. A refusal, or a call still running, is the failure TOOL_REFUSED: data.reason says why, data.guidance what to do next and data.details what it offers instead (OPERATION_PENDING: poll data.details.operationId with operations.get); it is never an outage. - **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:** response up to 256 KB - **CLI:** `arbol sura professionals list` · **MCP tool:** `sura_professionals_list` ## 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` ## Query parameters - `serviceId` (`sura.professionals.list.query.serviceId`; string, required) — Exact numeric service id returned by list_services. This directory is not filtered by patient coverage or available appointments. - pattern `^[0-9]{1,20}$` - `areaId` (`sura.professionals.list.query.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. - `cursor` (`sura.professionals.list.query.cursor`; string, optional) — Opaque cursor returned by pageInfo; omit it to request the first page. - `direction` (`sura.professionals.list.query.direction`; string, optional) — Direction to traverse the stable keyset ordering from the supplied cursor. - one of `"forward"`, `"backward"`; default `"forward"` - `limit` (`sura.professionals.list.query.limit`; integer, optional) — Maximum items returned in one page. Defaults to 25; larger reads require another cursor. - min 1; max 100; default `25` - `agentMode` (`sura.professionals.list.query.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.professionals.list.query.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.professionals.list.query.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"` ## Code samples ### cURL ```bash curl "https://api.getarbol.com/v1/sura/professionals?serviceId=" \ --header "Authorization: Bearer $ARBOL_API_KEY" ``` ### 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.professionals.list({ 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() .professionals() .list(&types::SuraProfessionalsListInput { service_id: "".into(), area_id: None, cursor: None, direction: None, limit: None, agent_mode: None, connection_id: None, channel: None, }) .await?; ``` ### CLI ```bash arbol sura professionals list --service-id '' ``` ### MCP ```json { "name": "sura_professionals_list", "arguments": { "serviceId": "" } } ``` ## Responses ### 200 Successful operation. #### Body (application/json) - `success` (`sura.professionals.list.response.200.success`; boolean, required) - one of `true` - `data` (`sura.professionals.list.response.200.data`; object, required) - `data` (`sura.professionals.list.response.200.data.data`; array, required) — Items admitted by this resource contract within the verified organization. - `id` (`sura.professionals.list.response.200.data.data.id`; string, required) — Opaque directory identity. Use name, not this id, when requesting availability. - `name` (`sura.professionals.list.response.200.data.data.name`; string, required) - `areaId` (`sura.professionals.list.response.200.data.data.areaId`; string, required) - `serviceId` (`sura.professionals.list.response.200.data.data.serviceId`; string, required) - `serviceName` (`sura.professionals.list.response.200.data.data.serviceName`; string, required) - `registered` (`sura.professionals.list.response.200.data.data.registered`; boolean, required) - `availabilityChecked` (`sura.professionals.list.response.200.data.data.availabilityChecked`; boolean, required) - `object` (`sura.professionals.list.response.200.data.object`; string, required) — Discriminator for a resource list response. - `pageInfo` (`sura.professionals.list.response.200.data.pageInfo`; object, required) — Opaque navigation cursors for this page’s stable keyset order. - `hasNextPage` (`sura.professionals.list.response.200.data.pageInfo.hasNextPage`; boolean, required) — Whether a later page exists in the current ordering. - `hasPreviousPage` (`sura.professionals.list.response.200.data.pageInfo.hasPreviousPage`; boolean, required) — Whether an earlier page exists in the current ordering. - `nextCursor` (`sura.professionals.list.response.200.data.pageInfo.nextCursor`; string | null, required) — Opaque cursor for the next page, or null when there is none. - `previousCursor` (`sura.professionals.list.response.200.data.pageInfo.previousCursor`; string | null, required) — Opaque cursor for the previous page, or null when there is none. - `error` (`sura.professionals.list.response.200.error`; unknown, required) - `metadata` (`sura.professionals.list.response.200.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.response.200.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": true, "data": { "data": [ { "id": "string", "name": "string", "areaId": "string", "serviceId": "string", "serviceName": "string", "registered": true, "availabilityChecked": false } ], "object": "list", "pageInfo": { "hasNextPage": true, "hasPreviousPage": true, "nextCursor": "string", "previousCursor": "string" } }, "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.professionals.list.response.400.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.400.data`; unknown, required) - `error` (`sura.professionals.list.response.400.error`; object, required) — The request does not match the published schema. - `code` (`sura.professionals.list.response.400.error.code`; string, required) — The failure code, stable across releases. - one of `"INVALID_INPUT"` - `message` (`sura.professionals.list.response.400.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.400.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.professionals.list.response.400.error.data`; object, required) - `issues` (`sura.professionals.list.response.400.error.data.issues`; array, optional) - `path` (`sura.professionals.list.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.professionals.list.response.400.error.data.issues.message`; string, required) - maxLength 256 - `metadata` (`sura.professionals.list.response.400.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.401.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.401.data`; unknown, required) - `error` (`sura.professionals.list.response.401.error`; object, required) — A valid access token is required. - `code` (`sura.professionals.list.response.401.error.code`; string, required) — The failure code, stable across releases. - one of `"UNAUTHORIZED"` - `message` (`sura.professionals.list.response.401.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.401.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.professionals.list.response.401.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.401.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.403.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.403.data`; unknown, required) - `error` (`sura.professionals.list.response.403.error`; object, required) — The token does not authorize this operation. - `code` (`sura.professionals.list.response.403.error.code`; string, required) — The failure code, stable across releases. - one of `"FORBIDDEN"` - `message` (`sura.professionals.list.response.403.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.403.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.professionals.list.response.403.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.403.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.404.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.404.data`; unknown, required) - `error` (`sura.professionals.list.response.404.error`; object, required) — The organization has no such connection. - `code` (`sura.professionals.list.response.404.error.code`; string, required) — The failure code, stable across releases. - one of `"CONNECTION_NOT_FOUND"` - `message` (`sura.professionals.list.response.404.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.404.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.professionals.list.response.404.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.404.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.409.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.409.data`; unknown, required) - `error` (`sura.professionals.list.response.409.error`; one of, required) - one of: `SuraPortalSessionConflictFailure`, `SuraConnectionNotConfiguredFailure` - discriminator: `code` - `metadata` (`sura.professionals.list.response.409.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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 ``` ### 422 `TOOL_REFUSED`: The request was not answered as a page: data.reason says why and data.guidance what to do next. Nothing was changed. #### Body (application/json) - `success` (`sura.professionals.list.response.422.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.422.data`; unknown, required) - `error` (`sura.professionals.list.response.422.error`; object, required) — The request was not answered as a page: data.reason says why and data.guidance what to do next. Nothing was changed. - `code` (`sura.professionals.list.response.422.error.code`; string, required) — The failure code, stable across releases. - one of `"TOOL_REFUSED"` - `message` (`sura.professionals.list.response.422.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.422.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.professionals.list.response.422.error.data`; object, required) - `reason` (`sura.professionals.list.response.422.error.data.reason`; string, required) — Why, as a stable code: NO_SERVICES, PORTAL_BUSY, OPERATION_PENDING… - pattern `^[A-Z][A-Z0-9_]{1,63}$` - `detail` (`sura.professionals.list.response.422.error.data.detail`; string, required) — What was refused, in English, for logs and people. - `details` (`sura.professionals.list.response.422.error.data.details`; object, required) — What the refusal offers to continue (the choices, the operation to poll), as the guidance names it. - `guidance` (`sura.professionals.list.response.422.error.data.guidance`; string, optional) — What an Agent does next, in the language it speaks to the person. - `say` (`sura.professionals.list.response.422.error.data.say`; string, optional) — A sentence an Agent may say to the person as it is. - `metadata` (`sura.professionals.list.response.422.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.response.422.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ##### Example ```json { "success": false, "data": null, "error": { "code": "TOOL_REFUSED", "message": "string", "retryable": false, "data": { "reason": "string", "detail": "string", "guidance": "string", "say": "string", "details": {} } }, "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.professionals.list.response.429.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.429.data`; unknown, required) - `error` (`sura.professionals.list.response.429.error`; object, required) — The request rate limit was exceeded. Try again later. - `code` (`sura.professionals.list.response.429.error.code`; string, required) — The failure code, stable across releases. - one of `"RATE_LIMITED"` - `message` (`sura.professionals.list.response.429.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.429.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.professionals.list.response.429.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.429.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.500.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.500.data`; unknown, required) - `error` (`sura.professionals.list.response.500.error`; object, required) — The service could not complete the operation. - `code` (`sura.professionals.list.response.500.error.code`; string, required) — The failure code, stable across releases. - one of `"INTERNAL_ERROR"` - `message` (`sura.professionals.list.response.500.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.500.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.professionals.list.response.500.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.500.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.502.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.502.data`; unknown, required) - `error` (`sura.professionals.list.response.502.error`; one of, required) - one of: `OutcomeUnknownFailure`, `SuraPortalCredentialsRejectedFailure`, `SuraPortalUnavailableFailure` - discriminator: `code` - `metadata` (`sura.professionals.list.response.502.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.503.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.503.data`; unknown, required) - `error` (`sura.professionals.list.response.503.error`; object, required) — The upstream service could not complete the request. - `code` (`sura.professionals.list.response.503.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_UNAVAILABLE"` - `message` (`sura.professionals.list.response.503.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.503.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.professionals.list.response.503.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.503.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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.professionals.list.response.504.success`; boolean, required) - one of `false` - `data` (`sura.professionals.list.response.504.data`; unknown, required) - `error` (`sura.professionals.list.response.504.error`; object, required) — The upstream service did not respond before its deadline. - `code` (`sura.professionals.list.response.504.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_TIMEOUT"` - `message` (`sura.professionals.list.response.504.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.professionals.list.response.504.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.professionals.list.response.504.error.data`; object, required) — No fields. - `metadata` (`sura.professionals.list.response.504.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.professionals.list.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/professionals/list/index.md