Skip to main content

API Reference

This is the complete reference of every public endpoint exposed by ARC (Authorizations + Claims + Dispensing) and ePrescription (Osigu's EHR product), plus the auxiliary services that back the widgets. The two products are separate but share the OAuth model, provider identity, catalogues, and the Dispensing endpoints.

Each operation has its own page with request/response schemas, examples in multiple languages, and an interactive playground you can hit against sandbox right from this site. The pages are auto-generated from the OpenAPI spec — if you spot a discrepancy with the live API, email support@osigu.com with the endpoint and the divergence.

Endpoints under /arc/..., /dispensing/..., and /v3/settlements belong to ARC. Endpoints under /ehr/... belong to the ePrescription product. Everything else (catalogues, auth) is shared.

Where to start​

If you're…Read first
New to Osigu ARC / ePrescription and want the big pictureIntroduction → Quickstart → this reference
Implementing a specific operationJump to the operation page in the sidebar
Embedding the widget in your web appWidgets — the widget docs cover initialization, events, and customization. This reference is what the widget calls under the hood.
Building a webhook receiverWebhook events — the events Osigu emits, separate from this reference

Resource groups​

Endpoints are organised by tag:

TagWhat's there
Authentication & OTPsendOtp, validateOtp. OAuth2 client-credentials access token lives on the SSO server — see Obtaining tokens.
Beneficiary LookupSearch a beneficiary and list the sponsor-defined search forms before initiating an authorization or dispensation.
Pre-authorizationsFull pre-auth lifecycle — initiate the request, attach the indication (multipart / form-data / Base64), complete it, retrieve authorizations, biometric readings, sponsor configuration.
ClaimsOutpatient care claims and medical-procedure claims — create, retrieve, complete, void.
DispensingStart a dispensation at a pharmacy, change products, complete or void. Includes verification-status polling for insured authorizations.
Prescriptions (ePrescription product)Issue an electronic prescription (three versions coexisting), retrieve, list, resend, plus the medical catalogs (diagnoses / medications / products / patients).
Provider ProductsRegister or remove products from the provider's catalogue so Osigu recognises them in pre-authorizations and prescriptions.
Settlement Batches (Radicaciones)Legacy Dominican Republic flow to submit claim batches to sponsors. Includes attaching invoices, listing pending authorizations, and closing the batch.
AffiliationsWhich sponsors a provider is affiliated with, plus external-provider search.
CatalogsReference data — countries, states, cities, subdivisions, medical boards, medical specialties.

Base URLs​

Both environments are hosted on osigu.com without a per-product path prefix. The prefix is baked into each endpoint's path (/arc/..., /dispensing/..., /ehr/..., /v3/settlements, /medical-catalogs/...).

EnvironmentBase URLWhen to use
Sandboxhttps://sandbox.osigu.comBuilding, testing. Non-billable.
Productionhttps://api.osigu.comLive traffic.

Authentication​

Every endpoint requires a bearer token obtained via the OAuth2 client-credentials grant on Osigu's SSO server. Some sensitive operations (e.g. authorization approval, dispensation completion, settlement finalisation) additionally require an OTP token obtained via sendOtp + validateOtp.

curl -X POST https://sandbox.osigu.com/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

# Then on every ARC / Dispensing / EHR call:
curl https://sandbox.osigu.com/arc/v1/authorization-requests \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Full flow, cache guidance, and OTP details: Obtaining tokens and OTP flow.

Versioning​

Public endpoints carry an explicit major version in the path (/v1/, /v2/, /v3/). Within a major, additive changes don't bump the version; breaking changes do, and the old endpoint is deprecated with a Sunset date.

Today's mix:

  • /v1/ — the majority of endpoints: pre-authorizations, claims, dispensing, prescriptions (v1 base), catalogs, provider products.
  • /v1.1/ — one prescription variant that adds patient-data-consent validation.
  • /v2/ — biometric-reading v2, some pre-authorization document-policy endpoints, catalogs.
  • /v3/ — settlement batches (the current version of the RD flow).

See API versioning for the full deprecation rules.

Error format​

Every error response uses a consistent shape:

{
  "error_code": "071-XXX",
  "message": "Human-readable explanation in English",
  "additional_information": {
    "field": "value that helps debug — e.g. the invalid parameter name"
  }
}

error_code is a stable identifier you can match against in your client. message may be tweaked across releases for clarity — log it for debugging but don't switch on it.

Common HTTP statuses:

StatusMeaning
200 OKSuccess with response body.
201 CreatedResource created. Response body contains the new resource.
202 AcceptedAsync work started — body or Location header points to a monitor endpoint.
204 No ContentSuccess, no body (typical for delete-style endpoints).
400 Bad RequestRequest malformed. Response body contains error_code and message.
401 UnauthorizedBearer token missing, invalid, or expired.
403 ForbiddenToken valid but lacks the scope for this action, or provider not authorised for this sponsor.
404 Not FoundResource not found, or scoped out by your provider's permissions.
409 ConflictState conflict (e.g. trying to modify a completed authorization request).
413 Payload Too LargeFile exceeds 25 MB on upload endpoints.
422 Validation errorBody parsed but failed business validation. additional_information includes the offending field.
5xxServer-side issue. Safe to retry with exponential backoff.

Rate limits​

Sandbox rate limits are set per client_id:

  • 50 requests / minute on most endpoints
  • 10 requests / minute on the OAuth token endpoint (cache your tokens!)
  • 20 uploads / minute on file upload endpoints (indication, settlement documents)

Hitting the limit returns 429 Too Many Requests with a Retry-After header (seconds). Production limits are higher and are configured per integration during onboarding.

Interactive playground​

Every operation page in the sidebar has a "Send API Request" panel. It pre-fills the path and headers from the OpenAPI spec; you fill in the body, paste your sandbox token, and hit Send. Useful for one-off verifications without writing code.

The playground uses sandbox by default. If you want to try a production endpoint, change the server in the dropdown — but be careful, production is billable and audited.

OpenAPI spec download​

The raw OpenAPI 3.0.1 spec backing this reference is at:

https://auth-docs.osigu.com/openapi.json

Drop it into Postman, Insomnia, openapi-generator, or any other tool that consumes OpenAPI. We bump this spec on every release.

Next steps​