Authorizations

An authorization in ARC is a sponsor's up-front approval for a covered service — a medication, a lab, an imaging study, an in-clinic procedure. The provider gets it before rendering the service so the sponsor can guarantee coverage and reimbursement.

ARC models this in two layers:

• Authorization request (authorization_request_id) — the submission the provider makes. One request can produce multiple authorizations because sponsors typically split responses by product type (e.g. one authorization per medication, one per lab).
• Authorization (authorization_code) — the sponsor's actual decision, tied to a product group and status.

Lifecycle of a request

Why two phases

The two-phase (initiate + complete) split lets you:

• Upload indications in whatever order suits your UI. Users often add medications one screen at a time; the request stays in PENDING_INDICATION until they hit "submit".
• Retry cleanly on client errors. If your UI blows up between initiate and complete, the request stays PENDING_INDICATION — no orphan authorizations, no double-charge.
• Attach different indication types. Some sponsors want a signed prescription; others want a lab order plus a diagnosis note. The complete step doesn't fire until you've attached what the sponsor expects — see getAuthorizationDocumentPolicy.

Shape of a request

The minimum payload for POST /arc/v1/authorization-requests:

{
  "beneficiary_id": "bnf_...",
  "sponsor_slug": "sponsor-name",
  "diagnosis_code": "R51",
  "products": [
    {"product_code": "MED-042", "product_type": "MEDICATION", "quantity": 30, "posology": "…"}
  ]
}

Optional fields many sponsors require:

Field	When
provider_branch_id	Multi-branch providers — specifies which branch is submitting.
service_type_code	When the sponsor differentiates outpatient vs. hospitalisation vs. emergency.
authorization_type	PRESCRIPTION, MEDICAL_INDICATION, LAB_ORDER, PROCEDURE, etc. Determined by sponsor rules.
professional_license_number	The prescribing doctor's registration. Often required for medications.
additional_data	Free-form key-value pairs the sponsor uses for country-specific validation.

The sponsor's getSponsorConfiguration response tells you which of these are required for your (sponsor, product_type) combination.

What comes back

POST /arc/v1/authorization-requests/{id}/complete returns the authorizations produced. Common statuses:

status	Meaning
APPROVED	Fully approved. authorization_code is redeemable.
REJECTED	Denied. rejection_reason explains why (surface it to the user).
PENDING_SPONSOR	The sponsor accepted the request but is processing asynchronously. A webhook (authorization.created or authorization.rejected) will follow.
PENDING_INDICATION	The complete call was made but the required indications weren't attached. Attach them, then call complete again.
EXPIRED	The authorization existed but its validity window elapsed before it was redeemed.
VOIDED	The authorization was cancelled — either by the provider (voidAuthorization) or by the sponsor.

See the full enum in the API reference under AuthorizationStatus.

Reading an existing authorization

Two lookup paths depending on what you have:

Endpoint	Use when
GET /arc/v1/authorizations/{authorizationId}	You have Osigu's internal UUID. Returns JSON or PDF (via Accept header).
GET /arc/v1/beneficiaries/{beneficiaryId}/authorizations/code/{authorizationCode}	You have the authorization code (e.g. from a QR code the beneficiary shows at the pharmacy).
GET /arc/v1/beneficiaries/{beneficiaryId}/authorizations	You want a paginated list — used by the pharmacy dispensation flow.

Modifying an authorization after issuance

Limited modifications are allowed while the authorization has not yet been redeemed:

• PUT /arc/v1/authorizations/{id}/payment-type — a sponsor changes how the authorization can be redeemed (cash, wallet, transfer, in-kind).
• PUT /arc/v1/authorizations/{id} — a sponsor modifies fields on a system-generated authorization.
• POST /arc/v1/sponsors/{slug}/authorizations — a sponsor imports an authorization created in its own system so Osigu can dispense it.

Related concepts

• Sponsors — the entity whose rules determine what to submit.
• Beneficiary Lookup — how to find who the authorization is for.
• Dispensing — how the authorization is redeemed at the pharmacy, lab or imaging centre. Osigu creates the claim automatically when this happens.
• Claims — the reimbursement side. Auto-generated from Dispensing for pharmacies / labs / imaging, or filed directly for outpatient encounters and medical procedures.
• Webhooks — the asynchronous outcomes for authorizations processed by the sponsor.