> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taigabilling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taigabilling.com/_mcp/server.

# Making requests

The Partner API preserves the endpoint paths and wire shapes shown in the [API Reference](/api-reference). Requests are sent to Taiga's API host: `https://api.taigabilling.com`.

## Required headers

Every API request needs your API key as a bearer token, and JSON request bodies must declare their content type:

```http
Authorization: Bearer <api key>
Content-Type: application/json
```

## Examples

#### List encounters

```bash
curl "https://api.taigabilling.com/api/encounters/v4?limit=10" \
  -H "Authorization: Bearer $TAIGA_API_KEY"
```

#### Fetch one

```bash
curl "https://api.taigabilling.com/api/encounters/v4/encounter_id_here" \
  -H "Authorization: Bearer $TAIGA_API_KEY"
```

#### Create a patient

```bash
curl "https://api.taigabilling.com/patients/v1" \
  -X POST \
  -H "Authorization: Bearer $TAIGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @patient.json
```

#### Create an encounter

```bash
curl "https://api.taigabilling.com/api/encounters/v4/create-from-pre-encounter" \
  -X POST \
  -H "Authorization: Bearer $TAIGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @encounter.json
```

## Patients come first

Encounters are created **from an existing patient record**. Register the patient and their coverage before billing for them:

#### Create the patient

`POST /patients/v1` registers the patient's demographics and returns the patient `id`. Note that patient endpoints are not prefixed with `/api`.

#### Add coverages

`POST /coverages/v1` attaches the patient's insurance, referencing the patient by the `patient` field. Keep each returned coverage `id` for the filing-order update.

#### Set the filing order

Update the patient with `PUT /patients/v1/{id}/{version}`, where `{version}` is the latest patient version plus one. Send the complete mutable patient body and set `filing_order.coverages` to the coverage ids in primary, secondary, then tertiary order. A coverage is not active for encounter creation until it is included in this list.

#### Create the encounter

`POST /api/encounters/v4/create-from-pre-encounter` with the patient's id as `pre_encounter_patient_id`. Demographics, subscriber, and responsible-party details are pulled from the patient record; you do not resend them on the encounter. Prior authorizations are different: keeping an authorization in the patient record does not populate the claim automatically. Send `prior_authorization_number` on each applicable `service_lines` item when you create the encounter. For a non-telehealth claim, also send a valid `service_facility`; its NPI, when present, must be a checksum-valid 10-digit NPI.

> **BILLABLE starts billing immediately.**
>
> Set `billable_status` to `BILLABLE` only when the encounter is ready for billing processing. Validation failures may place the resulting claim in a work queue before it can be submitted. `NOT_BILLABLE` is only for an intentional write-off; do not use it as a draft or staging status.

> **NOT_BILLABLE is rejected on create.**
>
> A create sending `billable_status: "NOT_BILLABLE"` returns `422` and is not forwarded for billing. A write-off is a decision about an encounter that already exists, so it cannot be declared before there is one, and an encounter created this way would silently never bill. There is no draft status; create the encounter when it is ready.

> **Keep patient records current.**
>
> The patient record is the source of truth for demographics and coverage. Claim activity does not update it. When details change in your system, push the change with the patient and coverage update endpoints, or downstream claims will be built from stale data.

### List response shape

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

The exact item shape is documented in the [API Reference](/api-reference) for each endpoint.

> **Task lists use one billing provider at a time.**
>
> If an API credential has more than one billing-provider NPI, requests to `GET /api/tasks/v3` must include exactly one in-scope `billing_provider_npi` query parameter.

### Single-object reads

Path parameters are included directly in the URL. If the object exists but is outside your organization's billing-provider NPI scope, Taiga returns a failure without exposing the object contents.

> **Treat out-of-scope results as missing.**
>
> Tenant-boundary failures and missing-resource failures look the same on the wire. This is intentional: it prevents the API from leaking the existence of out-of-scope records.

### Writes

Claim and financial writes must include an in-scope billing-provider NPI in the request body or endpoint-specific fields. Tenant-owned patient, coverage, and service-facility creates do not require a top-level provider NPI; any embedded provider references are still checked, and the returned resource is recorded under the calling credential's tenant.

#### Pre-flight check

Taiga verifies the submitted billing-provider NPI belongs to your organization before forwarding.

#### Forward to billing

Taiga sends the authorized payload into the billing workflow. Claim validation can still require customer action before a claim reaches the clearinghouse.

#### Post-flight check

Taiga verifies the returned resource is still in scope before returning it to you.

## Organization overrides

> **Don't send organization override fields.**
>
> Fields like `organization_id` are rejected. Your organization is resolved from the API credential, and billing tenancy is enforced by billing-provider NPI.

## OpenAPI reference

The generated [API Reference](/api-reference) contains:

#### Endpoints

Paths and HTTP methods

#### Parameters

Query and path parameters

#### Schemas

Request and response bodies

#### Examples

Generated request examples