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.

Available integrations

• SURA12 endpoints

  Eligibility, patients, services, professionals, availability, appointments, authorizations and copays through your SURA connections.

  ReferenceOpenAPI/v1/sura

• Nueva EPS1 endpoint

  Member affiliation lookups through your Nueva EPS connections.

  ReferenceOpenAPI/v1/nueva-eps

• gMedic23 endpoints

  Patients and patient notes, agendas, availability and appointments, sessions, branch offices and reference lists from gMedic.

  ReferenceOpenAPI/v1/gmedic

• Visoft12 endpoints

  Clinics, contracts and services, professionals, patients, availability and appointments from Visoft.

  ReferenceOpenAPI/v1/visoft

• AXA3 endpoints

  Beneficiary eligibility, medical authorizations and the provider profile from AXA.

  ReferenceOpenAPI/v1/axxa

• Salud Total5 endpoints

  Member affiliation, authorization and filing records, invoices and objection notices through your Salud Total IPS connections.

  ReferenceOpenAPI/v1/salud-total

• ADRES1 endpoint

  A person and every EPS affiliation they have, from Colombia's national affiliate database.

  ReferenceOpenAPI/v1/adres

• Policía Colombia1 endpoint

  The judicial statement the Colombian National Police publish for a document, word for word.

  ReferenceOpenAPI/v1/policia-colombia

• Sisbén1 endpoint

  A person's Sisbén IV registration, with its official group and subgroup.

  ReferenceOpenAPI/v1/sisben

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, 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), or they’re turned on with account.registryInstallations.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. Each one has:

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:

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:

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, 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:

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.

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

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

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

New integrations

New integrations arrive as new services of the API, and appear on this page and in the API reference as the API adds them.