---
title: "Integrations"
description: "How to call Arbol's integrations with insurers, public registries and clinical systems, what you need before the first call, and how to read the results."
---

> 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.

# Integrations

An integration lets your organization work with an insurer's, a public registry's or a clinical system's data through the Arbol API: check eligibility and affiliations, look up patients, read availability, book appointments. You call the integration's operations; Arbol handles the provider's side.

## How you call an integration

Each integration is a service of the API, and you call it like any other: the same base URL, the same credential and the same response envelope.

| | |
|---|---|
| Path | `https://api.getarbol.com/v1/<service>/…`, such as `/v1/sura/…` |
| Reference | `/api/<service>/`, such as the [SURA reference](/api/sura/) |
| Scopes | Named after the service, such as `sura:appointments:write`. Each operation's reference lists the ones it accepts. |
| Credential | The same as the whole API: see [Authentication](/en/developers/authentication/). When you create an API key with [`account.apiKeys.create`](/api/account/api-keys/create/), you can also limit it to some operations and connections of an integration. |

## Available integrations

## Before the first call

Your organization needs the integration active:

- **Insurers and clinical systems**, such as SURA, Nueva EPS, gMedic or Visoft, need a [connection](#connections), which the Arbol team sets up with your organization and keeps working. To add one, write to your Arbol team.
- **Colombian registries** (ADRES, Sisbén and Policía Colombia): they're included with Arbol. The organization's **Owner** turns each one on in **Integrations** in Arbol Account ([how](/en/account/colombian-registries/)), or they're turned on with [`account.registryInstallations.update`](/api/account/registry-installations/update/).

## Connections

Your organization reaches each insurer or clinical system through a **connection**. Connections hold no data you need to send, and no operation returns anything secret about them.

To see your organization's connections, call [`account.connections.list`](/api/account/connections/list/). Each one has:

| Field | Meaning |
|---|---|
| `id` | The connection's id (`con_…`). Integration operations take it as `connectionId`. |
| `integration` | The integration it belongs to, such as `sura`. |
| `name` | The name people and agents choose it by, such as `Sede Norte`. |
| `status` | `active` when it can be used. |
| `tools` | The tools it offers a [Raíz agent](/en/developers/guides/create-an-agent/). |

When a connection stops being `active`, write to your Arbol team.

### Choosing a connection

Most integration operations take an optional `connectionId`. While your organization has one connection to an integration, you can leave it out; with several, send the one to use. Some operations always require it: their reference marks it as required. When no connection can run the call, the operation answers an error saying the integration isn't configured for your organization.

## Colombian registries

ADRES, Sisbén and Policía Colombia are independent integrations, with one lookup operation each:

| Registry | What it returns | Operation | CLI |
| --- | --- | --- | --- |
| ADRES | A person's EPS affiliations | [`adres.affiliations.lookup`](/api/adres/affiliations/lookup/) | `arbol adres affiliations lookup` |
| Sisbén | The Sisbén registration, group and subgroup | [`sisben.classifications.lookup`](/api/sisben/classifications/lookup/) | `arbol sisben classifications lookup` |
| Policía Colombia | The judicial statement for a document | [`policia-colombia.judicialRecords.lookup`](/api/policia-colombia/judicial-records/lookup/) | `arbol policiacolombia judicial-records lookup` |

ADRES returns EPS affiliations only: for Sisbén, call its own operation. An EPS regime says nothing about a Sisbén group.

### Make a lookup

Each operation is a `POST` that takes `documentType` and `documentNumber` in the body. Send the number as a string, keeping its leading zeros, and use the document types the operation's reference lists. Only look up the document of a person who authorized it:

```bash
curl https://api.getarbol.com/v1/adres/affiliations/lookup \
  --request POST \
  --header "Authorization: Bearer $ARBOL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "documentType": "CC", "documentNumber": "<documentNumber>" }'
```

With the [TypeScript SDK](/en/developers/sdks/typescript/), it's `arbol.adres.affiliations.lookup({ documentType, documentNumber })`; the other two are `arbol.sisben.classifications.lookup()` and `arbol.policiaColombia.judicialRecords.lookup()`.

All three accept any of the scopes `account:organizations:read`, `account:connections:read` or `account:connections:write`. A restricted API key must also allow the exact operation, such as `adres.affiliations.lookup`. A scope doesn't install the registry or bypass the key's restrictions. For one-off lookups, create an API key with a short expiry, which you choose when you create it in Arbol Account, and keep it out of source code, agent instructions and logs.

### Read the result

By default, `data` holds the registry's structured result:

| Registry | Fields of `data` |
| --- | --- |
| ADRES | `outcome`, `person.fullName`, all `affiliations` with their EPS, status, regime and dates, and `consultedAt` and `verification`. |
| Sisbén | `registered`, `group`, `subgroup`, `observedAt` and `verification`. |
| Policía Colombia | `documentType`, `documentNumber`, `fullName`, `identityStatus`, `judicialStatus`, `details` and `observedAt`. |

A previously known result keeps the time it was observed: for ADRES and Sisbén, `verification: "last_known"` marks it. An error or an unverified result doesn't prove that something is absent.

**Sisbén.** `registered: true` confirms the registration, `false` is an explicit negative report, and `null` means it couldn't be verified. Report the full subgroup when it comes, such as `C12`. An EPS affiliation doesn't establish eligibility for social programs.

| `group` | `subgroup` range |
| --- | --- |
| A | A1–A5 |
| B | B1–B7 |
| C | C1–C18 |
| D | D1–D21 |

**Policía Colombia.** `fullName` is the name as the source reports it. `identityStatus: "document_matched"` means the returned document matches the one looked up; it doesn't authenticate whoever presents it. Keep the official text of `details`, and tell `no_pending_matters` apart from `not_currently_required`: a statement about current judicial requirements isn't a complete conviction history. With `judicialStatus: "unverified"`, no verified statement was obtained: never present it as no pending matters.

### Text for AI agents

Add `"agentMode": true` to get the same observation as concise Spanish text: in `data.text` with `Accept: application/json`, or as a text body with `Accept: text/plain`. Use the structured result when your program needs the fields; the SDK returns the typed data.

### Over MCP

The same lookups are tools of the [MCP server](/en/developers/mcp/): `adres_affiliations_lookup`, `sisben_classifications_lookup` and `policia_colombia_judicial_records_lookup`. They take the same fields, `agentMode` included, and apply the same installation and credential restrictions. A tool appearing in the list doesn't mean a lookup succeeded.

## Salud Total

Salud Total answers with your organization's IPS accounts. The Arbol team connects each account for one use, **post-consultation** or **billing**, and every lookup takes the `connectionId` of the active connection for that use (see [Connections](#connections)).

| Question | HTTP request | TypeScript SDK | CLI | Connection |
| --- | --- | --- | --- | --- |
| Is this person enrolled? | `POST /v1/salud-total/affiliations/lookup` | `arbol.saludTotal.affiliations.lookup(input)` | `arbol saludtotal affiliations lookup` | Post-consultation |
| Does this person have authorizations that day? | `POST /v1/salud-total/authorizations/lookup` | `arbol.saludTotal.authorizations.lookup(input)` | `arbol saludtotal authorizations lookup` | Post-consultation |
| Does this person have filed requests that day? | `POST /v1/salud-total/filings/lookup` | `arbol.saludTotal.filings.lookup(input)` | `arbol saludtotal filings lookup` | Post-consultation |
| Does this invoice exist? | `POST /v1/salud-total/invoices/lookup` | `arbol.saludTotal.invoices.lookup(input)` | `arbol saludtotal invoices lookup` | Billing |
| How many objection and devolution notices are there? | `GET /v1/salud-total/notices/count` | `arbol.saludTotal.notices.count(input)` | `arbol saludtotal notices count` | Billing |

A person's lookups take `documentType: "CC"` and their `documentNumber` in the body; authorizations and filings also take the day (`day`, `YYYY-MM-DD`).

| Answer | What it means |
| --- | --- |
| `matched` | The affiliation found exactly one person; `providerStatus` is their enrollment status as Salud Total writes it. |
| `no_match`, `ambiguous` | Nobody has that document, or more than one person matches. It is not an outage. |
| `location_required` | For authorizations and filings: the account has several sites. Ask which one applies and repeat the lookup with the chosen id in the field `field` names. |
| `records_found`, `no_records` | There are records that day (`recordCount`), or none. A record does not approve a procedure. |
| `REPORTING_WINDOW_CLOSED` | For invoices: Salud Total's report is closed at that hour. The error says when it opens and closes (`opensAtHour`, `closesAtHour`, Bogotá time). |

A failed lookup, or an expired Salud Total session, does not mean there are no records: the error says so with its code, and the [Salud Total reference](/api/salud-total/) lists them all.

## Integrations in Raíz agents

A Raíz agent uses an integration through tools: each of its `integrationTools` pairs a `connectionId` with a tool that connection offers, as `account.connections.list` shows them. For an agent to use a Colombian registry, also assign it the registry's tool. See [Create an agent](/en/developers/guides/create-an-agent/).

## New integrations

New integrations arrive as new services of the API, and appear on this page and in the [API reference](/api/) as the API adds them.

Source: https://docs.getarbol.com/en/developers/integrations/index.mdx