Encounters

Create an encounter to send Branches the source data needed to prepare a claim. Branches accepts Candid-shaped encounter payloads so teams migrating from Candid-compatible workflows can reuse the same core object model.

Create an encounter

POST /api/encounters

curl https://api.withbranches.com/api/encounters \
  -H "Authorization: Bearer $BRANCHES_API_KEY" \
  -H "Content-Type: application/json" \
  -d @encounter.json

POST /api/encounters stores the raw request, validates the JSON body, and promotes valid payloads into encounters.

Required fields

The create payload follows Candid's professional encounter shape. Required top-level fields include:

Field	Notes
`external_id`	Caller-provided stable ID. Branches uses this as the idempotency key.
`patient_authorized_release`	Patient authorized release of medical information.
`benefits_assigned_to_provider`	Benefits assigned to provider.
`provider_accepts_assignment`	Provider accepts assignment.
`billable_status`	Usually `BILLABLE` or `NOT_BILLABLE`.
`responsible_party`	`INSURANCE_PAY`, `SELF_PAY`, or `UNKNOWN`.
`place_of_service_code`	CMS place of service code, such as `02` for telehealth or `11` for office.
`patient`	Patient demographics and address.
`billing_provider`	Provider or organization being reimbursed.
`rendering_provider`	Practitioner who performed the service.
`diagnoses`	Diagnosis codes for the encounter.

When responsible_party is INSURANCE_PAY, subscriber_primary is required.

Service lines are optional in the schema, but if you include them each line must include at least one diagnosis_pointers entry that points to a diagnosis in the top-level diagnoses array.

Idempotency

external_id is the idempotency key for encounter creation.

First accepted request:

{
  "encounter_id": "enc_123",
  "encounterId": "enc_123"
}

Replay with the same external_id:

{
  "encounter_id": "enc_123",
  "encounterId": "enc_123",
  "duplicate": true
}

Use stable, non-PHI identifiers for external_id.

List encounters

GET /api/encounters/candid-version

Supported query parameters:

Parameter	Notes
`external_id`	Return encounters with this caller-provided ID.
`claim_status`	Filter by latest claim status.
`limit`	Maximum page size. Defaults to 100 and must be between 1 and 100.
`page_token`	Cursor from `next_page_token`.

Response shape:

{
  "items": [],
  "next_page_token": null,
  "prev_page_token": null
}

Get one encounter

GET /api/encounters/candid-version/{encounter_id}

The response is Candid-shaped and includes Branches identifiers, the caller's external_id, the latest claim, the patient control number when present, and a url for the encounter.

Authentication

Events