--- title: "Look up an authorization" description: "Read an existing SaludWeb authorization for the exact CC patient, issuer and authorization number. Reports delivered status, dates, explicit charge type, fixed fee or copay percentage and provider-reported payments. Unknown balance and copay cap remain null. Does not issue, attend, modify or pay an authorization.\n\n- **Scope:** `sura:affiliations:read`\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 authorizations lookup` · **MCP tool:** `sura_authorizations_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 › Authorizations `POST /v1/sura/authorizations/lookup` Read an existing SaludWeb authorization for the exact CC patient, issuer and authorization number. Reports delivered status, dates, explicit charge type, fixed fee or copay percentage and provider-reported payments. Unknown balance and copay cap remain null. Does not issue, attend, modify or pay an authorization. - **Scope:** `sura:affiliations:read` - **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 authorizations lookup` · **MCP tool:** `sura_authorizations_lookup` ## Authentication Requires one of the following: - `arbolHuman`, oauth2, scopes: `sura:affiliations:read` - `arbolMachine`, oauth2, scopes: `sura:affiliations:read` - `arbolApiKey`, http, header `Authorization` ## Request body _Required._ - `authorizationNumber` (`sura.authorizations.lookup.authorizationNumber`; string, required) — Authorization number after the hyphen in the authorization identifier. - `documentNumber` (`sura.authorizations.lookup.documentNumber`; string, required) — Exact patient document number. - `issuerCode` (`sura.authorizations.lookup.issuerCode`; string, required) — Issuer code before the hyphen in the authorization identifier. - `documentType` (`sura.authorizations.lookup.documentType`; string | null, optional) — Document type. Defaults to CC. - one of `"CC"`, `null` - `agentMode` (`sura.authorizations.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.authorizations.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.authorizations.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 { "authorizationNumber": "string", "documentNumber": "string", "documentType": "CC", "issuerCode": "string", "agentMode": false, "connectionId": "string", "channel": "voice" } ``` ## Code samples ### cURL ```bash curl https://api.getarbol.com/v1/sura/authorizations/lookup \ --request POST \ --header "Authorization: Bearer $ARBOL_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "authorizationNumber": "", "documentNumber": "", "issuerCode": "" }' ``` ### 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.authorizations.lookup({ authorizationNumber: "", documentNumber: "", issuerCode: "", }); ``` ### Rust ```rust use arbol_sdk::{types, Client, Credential}; let arbol = Client::new(Credential::ApiKey(std::env::var("ARBOL_API_KEY")?))?; let data = arbol .sura() .authorizations() .lookup(&types::SuraAuthorizationsLookupInput { authorization_number: "".into(), document_number: "".into(), issuer_code: "".into(), document_type: None, agent_mode: None, connection_id: None, channel: None, }) .await?; ``` ### CLI ```bash arbol sura authorizations lookup --authorization-number '' --document-number '' --issuer-code '' ``` ### MCP ```json { "name": "sura_authorizations_lookup", "arguments": { "authorizationNumber": "", "documentNumber": "", "issuerCode": "" } } ``` ## Responses ### 200 Successful operation. #### Body (application/json) - `success` (`sura.authorizations.lookup.response.200.success`; boolean, required) - one of `true` - `data` (`sura.authorizations.lookup.response.200.data`; any of, required) - any of: `SuraPendingResult`, `SuraRefusal`, `SuraAuthorization` - `error` (`sura.authorizations.lookup.response.200.error`; unknown, required) - `metadata` (`sura.authorizations.lookup.response.200.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.400.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.400.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.400.error`; object, required) — The request does not match the published schema. - `code` (`sura.authorizations.lookup.response.400.error.code`; string, required) — The failure code, stable across releases. - one of `"INVALID_INPUT"` - `message` (`sura.authorizations.lookup.response.400.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.400.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.400.error.data`; object, required) - `issues` (`sura.authorizations.lookup.response.400.error.data.issues`; array, optional) - `path` (`sura.authorizations.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.authorizations.lookup.response.400.error.data.issues.message`; string, required) - maxLength 256 - `metadata` (`sura.authorizations.lookup.response.400.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.401.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.401.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.401.error`; object, required) — A valid access token is required. - `code` (`sura.authorizations.lookup.response.401.error.code`; string, required) — The failure code, stable across releases. - one of `"UNAUTHORIZED"` - `message` (`sura.authorizations.lookup.response.401.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.401.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.401.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.401.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.403.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.403.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.403.error`; object, required) — The token does not authorize this operation. - `code` (`sura.authorizations.lookup.response.403.error.code`; string, required) — The failure code, stable across releases. - one of `"FORBIDDEN"` - `message` (`sura.authorizations.lookup.response.403.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.403.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.403.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.403.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.404.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.404.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.404.error`; object, required) — The organization has no such connection. - `code` (`sura.authorizations.lookup.response.404.error.code`; string, required) — The failure code, stable across releases. - one of `"CONNECTION_NOT_FOUND"` - `message` (`sura.authorizations.lookup.response.404.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.404.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.404.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.404.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.409.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.409.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.409.error`; one of, required) - one of: `SuraPortalSessionConflictFailure`, `SuraConnectionNotConfiguredFailure` - discriminator: `code` - `metadata` (`sura.authorizations.lookup.response.409.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.413.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.413.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.413.error`; object, required) — The request exceeds the allowed size. - `code` (`sura.authorizations.lookup.response.413.error.code`; string, required) — The failure code, stable across releases. - one of `"REQUEST_TOO_LARGE"` - `message` (`sura.authorizations.lookup.response.413.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.413.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.413.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.413.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.415.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.415.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.415.error`; object, required) — The request content type is not supported. - `code` (`sura.authorizations.lookup.response.415.error.code`; string, required) — The failure code, stable across releases. - one of `"UNSUPPORTED_MEDIA_TYPE"` - `message` (`sura.authorizations.lookup.response.415.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.415.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.415.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.415.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.429.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.429.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.429.error`; object, required) — The request rate limit was exceeded. Try again later. - `code` (`sura.authorizations.lookup.response.429.error.code`; string, required) — The failure code, stable across releases. - one of `"RATE_LIMITED"` - `message` (`sura.authorizations.lookup.response.429.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.429.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.authorizations.lookup.response.429.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.429.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.500.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.500.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.500.error`; object, required) — The service could not complete the operation. - `code` (`sura.authorizations.lookup.response.500.error.code`; string, required) — The failure code, stable across releases. - one of `"INTERNAL_ERROR"` - `message` (`sura.authorizations.lookup.response.500.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.500.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`sura.authorizations.lookup.response.500.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.500.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.502.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.502.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.502.error`; one of, required) - one of: `OutcomeUnknownFailure`, `SuraPortalCredentialsRejectedFailure`, `SuraPortalUnavailableFailure` - discriminator: `code` - `metadata` (`sura.authorizations.lookup.response.502.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.503.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.503.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.503.error`; object, required) — The upstream service could not complete the request. - `code` (`sura.authorizations.lookup.response.503.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_UNAVAILABLE"` - `message` (`sura.authorizations.lookup.response.503.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.503.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.authorizations.lookup.response.503.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.503.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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.authorizations.lookup.response.504.success`; boolean, required) - one of `false` - `data` (`sura.authorizations.lookup.response.504.data`; unknown, required) - `error` (`sura.authorizations.lookup.response.504.error`; object, required) — The upstream service did not respond before its deadline. - `code` (`sura.authorizations.lookup.response.504.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_TIMEOUT"` - `message` (`sura.authorizations.lookup.response.504.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`sura.authorizations.lookup.response.504.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`sura.authorizations.lookup.response.504.error.data`; object, required) — No fields. - `metadata` (`sura.authorizations.lookup.response.504.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`sura.authorizations.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/authorizations/lookup/index.md