Skip to main content

Introduction

RCM (Revenue Cycle Management) is OSIGU's API for managing the financial lifecycle of medical billing across LATAM: events (the clinical encounters — atendimento in Brazil, episodio in Colombia), accounts (the billing wrappers that group events together), charges (the billable line items inside each event), invoices (what gets sent to the payer), and the support files that document each charge for the payer to honour it.

This documentation is for engineers integrating their hospital, clinic, or billing system directly with RCM.

What you can do with RCM​

Send events and charges

Send charges referencing your HIS's origin_event_id. RCM creates the event (atendimento / episodio) and account behind the scenes and groups them for billing.

Upload support files

Send the documents that back each charge — medical orders, TISS guides, pathology reports, OPME requests. RCM hands them to DVS for content validation against the payer's rule set.

Assign charges to invoices

Group charges into invoices ready to dispatch. Processing is async — track progress via the assignment-status endpoint.

Receive webhook events

Async classification and validation outcomes delivered as HMAC-signed callbacks. Enriched with RCM context: account_id, charge_id, support_file_id.

Core ideas​

Events are clinical encounters, accounts are billing wrappers, charges are line items

An event in RCM is one clinical encounter — atendimento in Brazilian Portuguese, episodio in Colombian Spanish. An account is the billing wrapper that groups one or more events for the same patient under one provider-payer agreement. A charge is one billable line inside an event: a procedure code, a material consumed, an executor service. You only ever POST charges — the event and account are created implicitly from the origin_event_id you include.

Support files are documents that justify a charge

To collect on a charge, the payer needs evidence — the TISS guide, the medical order, the OPME request, the pathology report. You upload these as support files linked to a charge or an account. RCM passes each file to DVS (Document Validation Service) for classification (if needed) and validation against the payer's rule set; the verdict comes back via webhook.

Invoices group charges and dispatch them to the payer

An invoice is a billable bundle: one or more charges attached to it via assign-charges, then dispatched to the payer once all required support files are validated. The assignment endpoint is asynchronous — call it, get a 202 with a Location header, then poll the assignment-status endpoint to know when all charges are bound.

Almost everything that touches DVS is async, delivered via webhook

Support file classification and validation run in the background (5–60 seconds typically). The upload returns 202 Accepted immediately with a support_file_id; the result arrives as a webhook event. Your receiver must be idempotent — see Webhook events.

Per-tenant access by provider, payer, and agreement

OSIGU grants each integrator explicit access to specific (provider, payer, agreement_code) combinations. Default-deny: you can't operate on charges or upload support files for a combination that's not in your contract. New combinations are added via the OSIGU operations team during onboarding.

API is versioned with /v1/ — some endpoints have moved to /v3/

Public endpoints live under /v1/. Additive changes (new optional fields, new endpoints) don't bump the version; breaking changes get a new major (/v2/, /v3/). Deprecated endpoints emit Deprecation: true and Sunset: <date> headers — see API versioning.

Who this is for​

RCM is built for organisations who need any of the following:

  • Hospitals and clinics that want to push patient encounters, services, and supporting documentation into OSIGU's billing pipeline.
  • Hospital Information Systems (HIS) and PMS integrators that need to sync admissions, procedure catalogues, and medical orders into RCM as they happen.
  • Billing systems that want to compose invoices from RCM charges and dispatch them to payers, then track validation outcomes via webhooks.

If you're consuming RCM through one of OSIGU's product UIs (operator portal, provider portal), this documentation isn't your entry point — it's for direct API integration.

Environments​

RCM provides two independent environments. Build and validate against sandbox first — every code sample defaults to sandbox.

Sandbox

RCM API: https://sandbox.osigu.com/rcm

OAuth token: https://sandbox.osigu.com/v1/oauth/token

Integration testing. Non-billable. Use while building.

Production

RCM API: https://api.osigu.com/rcm

OAuth token: https://api.osigu.com/v1/oauth/token

Live traffic. Real billing. Switch after sandbox is green.

Each environment has its own RCM host and its own OAuth token endpoint. Credentials are also environment-scoped — your sandbox client_id will not work against the production OAuth endpoint, and vice versa.

Getting started​

  1. 1Sign an integration agreement with OSIGU

    OSIGU's commercial team will provision your client_id, client_secret, and webhook secret, and configure the (provider, payer, agreement_code) combinations you can operate on.

  2. 2Obtain an OAuth access token

    Use the client credentials grant against the OAuth endpoint of your target environment. Cache the token for ~50 minutes (default TTL is 1 hour).

  3. 3Send your first request

    Follow the quickstart to create an account, attach a charge, upload a support file, and observe the webhook callback — all in under 10 minutes.

  4. 4Implement a webhook receiver

    For async flows, expose an HTTPS endpoint and verify HMAC signatures. Use ngrok or similar for local testing.

Support​

For onboarding, secret rotation, or production incidents: support@osigu.com.