Accounts

An account in RCM is the billing wrapper for a patient's care under a specific provider-payer agreement. It groups one or more events (the clinical encounters) so that the whole package can be invoiced as a unit.

⚠️ Don't confuse Account with Event. In Brazilian Portuguese the clinical encounter is called atendimento; in Colombian Spanish, episodio. That's what RCM models as an Event, not an Account. An Account is purely the billing-side construct that bundles events together.

Account                                  ← billing wrapper (this page)
  ├── Event (base)                       ← clinical encounter (atendimento BR / episodio CO)
  │     ├── Charge                       ← billable line items
  │     ├── Charge
  │     └── SupportFile                  ← documents
  ├── Event (secondary)
  │     └── Charge
  └── ...

A typical account holds:

• A single base event (e.g. a hospital admission)
• Optional secondary events linked via parent_event_id (e.g. an outpatient follow-up that bills together with the admission)
• All the charges of every event in the account
• All the support files attached at event or account level
• One or more invoices that group charges for dispatch to the payer

Lifecycle

You never POST to create an account directly — RCM creates it implicitly when the first charge for a new origin_event_id arrives:

Throughout this, the account itself is read-only from your perspective in v1 — RCM creates it from your charge submissions; you operate on its children (events, charges, support files, invoices). The only mutation at account level is changing the payer/agreement before any item is invoiced (see Modifying account state).

Identifiers

An account is addressable two ways:

Identifier	Where it comes from	When to use it
account_id (UUID)	Returned by RCM after the first charge implicitly creates it	RCM endpoints that operate on an existing account. The stable internal identifier.
origin_event_id (string)	Sent by your HIS/PMS on each charge	When you don't know the account_id yet but you do know the encounter id from your system. GET /v1/accounts/base-accounts/origin-events/{originEventId}/deep-info

You normally don't track account_id on your side — your system thinks in terms of origin_event_id. RCM exposes both because some operations are scoped to the account (e.g. dispatch lookups, agreement changes).

Modifying account state

In v1, you can:

• Add metadata — a settlement protocol number with POST /v1/accounts/additional-data, an external guide id with POST /v1/accounts/additional-data/external-id, or a batch number with POST /v1/accounts/additional-data/batch-number.
• Change the payer/agreement before any invoicing has happened — see PUT /v3/accounts/origin-events/change-of-payer. The companion /validate endpoint surfaces conflicts (existing charges under different contracts, etc.) without committing the change. Use it first when the change might affect multiple charges.

Most other mutations happen at the charge or support-file level. The account is a coordinator, not a frequently-edited entity.

Reading account state

Endpoint	Returns
GET /v1/accounts/base-accounts/origin-events/{originEventId}/deep-info	Full account state + base event + provider + agreement + linked charges and support files, looked up by your HIS's origin_event_id.
GET /v1/accounts/sent-accounts-statuses	Paginated list of dispatch packages (accounts already sent to a payer) for the authenticated provider.
GET /v1/accounts/sent-accounts-statuses-details/{accountId}	Per-invoice detail for a dispatched account, including the S3 URLs of each support file.

Country specifics

Account semantics are the same everywhere — it's a billing wrapper — but the events it groups vary by country regulation:

• Brazil (BR): TISS guide is the standard support file. Charges reference TUSS procedure codes. Multiple atendimentos for the same hospital stay typically go in one account.
• Colombia / other LATAM: episodios are billed under each country's local catalogue. The same wrapper concept applies.

What changes per country is which support_file_code values exist in the catalogue and which validation rules DVS applies — not the account model itself.