--- title: "Look up an exact IPS invoice reference" description: "Look up one exact invoice prefix and number in the active billing connection’s institution. Returns the number of matching rows. Outside the provider’s live reporting hours, REPORTING_WINDOW_CLOSED gives the opening hour (inclusive), closing hour (exclusive) and time zone. Payment or rejection requires separate evidence.\n\n- **Scope:** `salud-total:invoices: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 saludtotal invoices lookup` · **MCP tool:** `salud_total_invoices_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: Salud Total API › Invoices `POST /v1/salud-total/invoices/lookup` Look up one exact invoice prefix and number in the active billing connection’s institution. Returns the number of matching rows. Outside the provider’s live reporting hours, REPORTING_WINDOW_CLOSED gives the opening hour (inclusive), closing hour (exclusive) and time zone. Payment or rejection requires separate evidence. - **Scope:** `salud-total:invoices: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 saludtotal invoices lookup` · **MCP tool:** `salud_total_invoices_lookup` ## Authentication Requires one of the following: - `arbolHuman`, oauth2, scopes: `salud-total:invoices:read` - `arbolMachine`, oauth2, scopes: `salud-total:invoices:read` - `arbolApiKey`, http, header `Authorization` ## Request body _Required._ - `connectionId` (`salud-total.invoices.lookup.connectionId`; string, required) - pattern `^con_[0-7][0-9a-hjkmnp-tv-z]{25}$` - `prefix` (`salud-total.invoices.lookup.prefix`; string, required) - pattern `^[a-zA-Z0-9_-]{1,15}$` - `invoiceNumber` (`salud-total.invoices.lookup.invoiceNumber`; string, required) - pattern `^[0-9]{1,18}$` ## Example request ```json { "connectionId": "string", "prefix": "string", "invoiceNumber": "string" } ``` ## Code samples ### cURL ```bash curl https://api.getarbol.com/v1/salud-total/invoices/lookup \ --request POST \ --header "Authorization: Bearer $ARBOL_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "connectionId": "", "prefix": "", "invoiceNumber": "" }' ``` ### 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.saludTotal.invoices.lookup({ connectionId: "", prefix: "", invoiceNumber: "", }); ``` ### Rust ```rust use arbol_sdk::{types, Client, Credential}; let arbol = Client::new(Credential::ApiKey(std::env::var("ARBOL_API_KEY")?))?; let data = arbol .salud_total() .invoices() .lookup(&types::SaludTotalInvoicesLookupInput { connection_id: "".into(), prefix: "".into(), invoice_number: "".into(), }) .await?; ``` ### CLI ```bash arbol saludtotal invoices lookup --connection-id '' --prefix '' --invoice-number '' ``` ### MCP ```json { "name": "salud_total_invoices_lookup", "arguments": { "connectionId": "", "prefix": "", "invoiceNumber": "" } } ``` ## Responses ### 200 Successful operation. #### Example ```json { "success": true, "data": { "status": "no_match", "recordCount": 0 }, "error": null, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.200.success`; boolean, required) - one of `true` - `data` (`salud-total.invoices.lookup.response.200.data`; any of, required) - any of: `object`, `object` - `error` (`salud-total.invoices.lookup.response.200.error`; unknown, required) - `metadata` (`salud-total.invoices.lookup.response.200.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.200.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 400 `INVALID_INPUT`: The request does not match the published schema. #### Example ```json { "success": false, "data": null, "error": { "code": "INVALID_INPUT", "message": "string", "retryable": false, "data": { "issues": [ { "path": "string", "message": "string" } ] } }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.400.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.400.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.400.error`; object, required) — The request does not match the published schema. - `code` (`salud-total.invoices.lookup.response.400.error.code`; string, required) — The failure code, stable across releases. - one of `"INVALID_INPUT"` - `message` (`salud-total.invoices.lookup.response.400.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.400.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`salud-total.invoices.lookup.response.400.error.data`; object, required) - `issues` (`salud-total.invoices.lookup.response.400.error.data.issues`; array, optional) - `path` (`salud-total.invoices.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` (`salud-total.invoices.lookup.response.400.error.data.issues.message`; string, required) - maxLength 256 - `metadata` (`salud-total.invoices.lookup.response.400.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.400.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 401 `UNAUTHORIZED`: A valid access token is required. #### Example ```json { "success": false, "data": null, "error": { "code": "UNAUTHORIZED", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.401.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.401.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.401.error`; object, required) — A valid access token is required. - `code` (`salud-total.invoices.lookup.response.401.error.code`; string, required) — The failure code, stable across releases. - one of `"UNAUTHORIZED"` - `message` (`salud-total.invoices.lookup.response.401.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.401.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`salud-total.invoices.lookup.response.401.error.data`; object, required) — No fields. - `metadata` (`salud-total.invoices.lookup.response.401.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.401.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 403 - `FORBIDDEN`: The token does not authorize this operation. - `PORTAL_ACCESS_UNVERIFIED`: 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. - `MODULE_FORBIDDEN`: The account cannot access the required module. - `SITE_UNAVAILABLE`: This branch or site is not available to the selected IPS connection. #### Example ```json { "success": false, "data": null, "error": { "code": "FORBIDDEN", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.403.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.403.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.403.error`; one of, required) - one of: `ForbiddenFailure`, `SaludTotalPortalAccessUnverifiedFailure`, `SaludTotalModuleForbiddenFailure`, `SaludTotalSiteUnavailableFailure` - discriminator: `code` - `metadata` (`salud-total.invoices.lookup.response.403.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.403.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 409 - `REPORTING_WINDOW_CLOSED`: Invoice reporting is closed. Retry during the provider’s reporting hours. - `CONNECTION_UNAVAILABLE`: This operation requires an active IPS connection in this organization with the matching workflow tag. - `SESSION_CLOSED`: 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. - `INTERACTIVE_VERIFICATION_REQUIRED`: The IPS operator must complete an interactive portal step. - `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. - `IPS_IDENTITY_MISMATCH`: The provider returned a different IPS identity. #### Example ```json { "success": false, "data": null, "error": { "code": "REPORTING_WINDOW_CLOSED", "message": "string", "retryable": true, "data": { "opensAtHour": 0, "closesAtHour": 1, "timeZone": "America/Bogota" } }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.409.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.409.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.409.error`; one of, required) - one of: `SaludTotalReportingWindowClosedFailure`, `SaludTotalConnectionUnavailableFailure`, `SaludTotalSessionClosedFailure`, `SaludTotalInteractiveVerificationRequiredFailure`, `SaludTotalCredentialsRejectedFailure`, `SaludTotalIpsIdentityMismatchFailure` - discriminator: `code` - `metadata` (`salud-total.invoices.lookup.response.409.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.409.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 413 `REQUEST_TOO_LARGE`: The request exceeds the allowed size. #### Example ```json { "success": false, "data": null, "error": { "code": "REQUEST_TOO_LARGE", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.413.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.413.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.413.error`; object, required) — The request exceeds the allowed size. - `code` (`salud-total.invoices.lookup.response.413.error.code`; string, required) — The failure code, stable across releases. - one of `"REQUEST_TOO_LARGE"` - `message` (`salud-total.invoices.lookup.response.413.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.413.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`salud-total.invoices.lookup.response.413.error.data`; object, required) — No fields. - `metadata` (`salud-total.invoices.lookup.response.413.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.413.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 415 `UNSUPPORTED_MEDIA_TYPE`: The request content type is not supported. #### Example ```json { "success": false, "data": null, "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.415.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.415.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.415.error`; object, required) — The request content type is not supported. - `code` (`salud-total.invoices.lookup.response.415.error.code`; string, required) — The failure code, stable across releases. - one of `"UNSUPPORTED_MEDIA_TYPE"` - `message` (`salud-total.invoices.lookup.response.415.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.415.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`salud-total.invoices.lookup.response.415.error.data`; object, required) — No fields. - `metadata` (`salud-total.invoices.lookup.response.415.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.415.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 429 - `RATE_LIMITED`: The request rate limit was exceeded. Try again later. - `LOGIN_COOLING_DOWN`: 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. #### Example ```json { "success": false, "data": null, "error": { "code": "RATE_LIMITED", "message": "string", "retryable": true, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.429.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.429.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.429.error`; one of, required) - one of: `RateLimitedFailure`, `SaludTotalLoginCoolingDownFailure` - discriminator: `code` - `metadata` (`salud-total.invoices.lookup.response.429.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.429.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 500 `INTERNAL_ERROR`: The service could not complete the operation. #### Example ```json { "success": false, "data": null, "error": { "code": "INTERNAL_ERROR", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.500.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.500.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.500.error`; object, required) — The service could not complete the operation. - `code` (`salud-total.invoices.lookup.response.500.error.code`; string, required) — The failure code, stable across releases. - one of `"INTERNAL_ERROR"` - `message` (`salud-total.invoices.lookup.response.500.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.500.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`salud-total.invoices.lookup.response.500.error.data`; object, required) — No fields. - `metadata` (`salud-total.invoices.lookup.response.500.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.500.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 502 `OUTCOME_UNKNOWN`: The operation may have been applied; check its result before repeating it. #### Example ```json { "success": false, "data": null, "error": { "code": "OUTCOME_UNKNOWN", "message": "string", "retryable": false, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.502.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.502.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.502.error`; object, required) — The operation may have been applied; check its result before repeating it. - `code` (`salud-total.invoices.lookup.response.502.error.code`; string, required) — The failure code, stable across releases. - one of `"OUTCOME_UNKNOWN"` - `message` (`salud-total.invoices.lookup.response.502.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.502.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `false` - `data` (`salud-total.invoices.lookup.response.502.error.data`; object, required) — No fields. - `metadata` (`salud-total.invoices.lookup.response.502.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.502.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 503 - `UPSTREAM_UNAVAILABLE`: The upstream service could not complete the request. - `ACCOUNT_UNAVAILABLE`: The connection directory or vault is unavailable. - `SESSION_EXPIRED`: 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. - `PROVIDER_UNAVAILABLE`: The provider response is unavailable or unrecognized. #### Example ```json { "success": false, "data": null, "error": { "code": "UPSTREAM_UNAVAILABLE", "message": "string", "retryable": true, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.503.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.503.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.503.error`; one of, required) - one of: `UpstreamUnavailableFailure`, `SaludTotalAccountUnavailableFailure`, `SaludTotalSessionExpiredFailure`, `SaludTotalProviderUnavailableFailure` - discriminator: `code` - `metadata` (`salud-total.invoices.lookup.response.503.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.503.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. ### 504 `UPSTREAM_TIMEOUT`: The upstream service did not respond before its deadline. #### Example ```json { "success": false, "data": null, "error": { "code": "UPSTREAM_TIMEOUT", "message": "string", "retryable": true, "data": {} }, "metadata": { "requestId": "string" } } ``` - `success` (`salud-total.invoices.lookup.response.504.success`; boolean, required) - one of `false` - `data` (`salud-total.invoices.lookup.response.504.data`; unknown, required) - `error` (`salud-total.invoices.lookup.response.504.error`; object, required) — The upstream service did not respond before its deadline. - `code` (`salud-total.invoices.lookup.response.504.error.code`; string, required) — The failure code, stable across releases. - one of `"UPSTREAM_TIMEOUT"` - `message` (`salud-total.invoices.lookup.response.504.error.message`; string, required) — What went wrong, for people; it never contains input values. - `retryable` (`salud-total.invoices.lookup.response.504.error.retryable`; boolean, required) — Whether repeating the same request may succeed. - one of `true` - `data` (`salud-total.invoices.lookup.response.504.error.data`; object, required) — No fields. - `metadata` (`salud-total.invoices.lookup.response.504.metadata`; object, required) — What every answer carries besides its data or error. - `requestId` (`salud-total.invoices.lookup.response.504.metadata.requestId`; string, required) — Request correlation identifier, also sent as X-Request-Id. Source: https://docs.getarbol.com/api/salud-total/invoices/lookup/index.md