Events

Use encounter events to reconcile Branches status changes back into your system.

GET /api/encounters/candid-version/events

The endpoint returns Candid-shaped event pages for the authenticated workspace.

Event types

Branches currently emits:

Event type	Meaning
`CandidApi.Encounter.Created`	An encounter was accepted and created.
`CandidApi.Encounter.StatusUpdated`	The latest claim status changed.

List events

curl "https://api.withbranches.com/api/encounters/candid-version/events?limit=25" \
  -H "Authorization: Bearer $BRANCHES_API_KEY"

Supported query parameters:

Parameter	Notes
`event_types`	Comma-separated event types, or repeated `event_types` parameters.
`created_before`	Return events created before this ISO timestamp, inclusive.
`created_after`	Return events created after this ISO timestamp, inclusive.
`limit`	Maximum page size. Defaults to 100 and must be between 1 and 100.
`page_token`	Cursor from `next_page_token`.

Response shape:

{
  "items": [
    {
      "id": "evt_123",
      "created_at": "2026-06-17T12:00:00.000Z",
      "timestamp": "2026-06-17T12:00:00.000Z",
      "event_type": "CandidApi.Encounter.StatusUpdated",
      "schema_version": "branches.candid-version.v1",
      "payload": {
        "encounter_id": "enc_123",
        "external_id": "visit_456",
        "claim_id": "claim_789",
        "previous_status": "submitted_to_payer",
        "status": "era_received"
      }
    }
  ],
  "next_page_token": null,
  "prev_page_token": null
}

Get one event

GET /api/encounters/candid-version/events/{event_id}

Use this endpoint when a stored event ID needs to be rehydrated or inspected.

Claim statuses

Claim statuses use the Candid-version vocabulary exposed in the API reference. Common statuses include biller_received, submitted_to_payer, rejected, denied, paid, era_received, and finalized_paid.

Encounters

Errors