Skip to main content

Beneficiary Lookup

Every ARC operation targets a specific beneficiary — the person who's covered by the sponsor and who will receive the service. Before you can issue a pre-authorization, create a prescription, or start a dispensation, you have to find that beneficiary in the sponsor's directory and get back their beneficiary_id.

The trick is that every sponsor defines its own search form. Osigu doesn't hard-code a fixed set of fields. Your integration reads the form dynamically and renders it (if you have a UI) or fills it in (if you have machine-readable input).

The two-step dance​

1. Get the form​

GET /v1/sponsors/{sponsorSlug}/forms returns the list of search forms this sponsor accepts. A form is a set of typed fields:

[
  {
    "form_id": "national-id",
    "label": "Cédula",
    "fields": [
      {"key": "document_type", "type": "enum", "values": ["CC", "CE", "TI", "PA"], "required": true},
      {"key": "document_number", "type": "string", "required": true}
    ]
  },
  {
    "form_id": "member-id",
    "label": "Member number",
    "fields": [
      {"key": "member_id", "type": "string", "required": true}
    ]
  }
]

Most sponsors expose 1–3 forms. Pick the one you can fill in, or (in a UI) let the user pick.

POST /v1/sponsors/{sponsorSlug}/search with the field values:

curl -X POST https://sandbox.osigu.com/v1/sponsors/sponsor-sandbox/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document_type":"CC","document_number":"1000000001"}'

Response:

{
  "beneficiary_id": "bnf_01HW8GQ2KMNP3F4R5T6Y7U8I9O",
  "first_name": "MARIA",
  "last_name": "GONZALEZ",
  "coverage": {
    "plan_code": "GOLD-100",
    "active": true,
    "effective_until": "2027-01-31"
  }
}

Persist the beneficiary_id — pass it to every subsequent authorization / prescription / dispensing call.

Dependants and family groups​

Some sponsors organise coverage as a holder + dependants unit. Search results for the holder can also expose the family group via a dependants list. Once you find the holder, use getDependents to enumerate the covered relatives and pick the one you're actually treating.

What happens when the beneficiary isn't found​

Three failure modes to handle in your integration:

ResultMeaningWhat to do
404 Not FoundNo matching beneficiary in the sponsor's directory.Surface a friendly error to the user; suggest they check the identifier or contact the sponsor.
200 with coverage.active = falseBeneficiary exists but coverage is expired / suspended.Do not proceed — the sponsor will reject any authorization.
403 ForbiddenYour provider isn't affiliated with this sponsor.Check listSponsors and confirm with Osigu support.
  • Sponsors — the form and search rules come from here.
  • Authorizations — the next step after finding the beneficiary.
  • Dispensing — dispensations also require a beneficiary ID.