> 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.

# Tenant scoping

Every Partner API credential belongs to one Taiga organization. That organization has a configured list of **billing-provider NPIs**.

Taiga uses that NPI allowlist to decide what the credential can read or write.

> **You never pass an organization ID.**
>
> Taiga resolves your tenant from the credential used to mint the bearer token. Tenancy is enforced server-side based on the allowed billing-provider NPIs.

## How scoping works

```mermaid
flowchart TD
  A[Incoming request] --> B{Credential valid?}
  B -- no --> X[401 / 403]
  B -- yes --> C[Resolve org from credential]
  C --> D[Load allowed billing NPIs]
  D --> E{Operation type?}
  E -- list --> F[Intersect filter with allowlist]
  E -- read one --> G[Fetch then check scope]
  E -- write --> H{NPI in allowlist?}
  H -- no --> X
  H -- yes --> I[Forward to clearinghouse]
  I --> J{Result still in scope?}
  J -- no --> Y[502 integration error]
  J -- yes --> K[Return result]
  F --> K
  G --> K
```

## List reads

For list endpoints that support billing-provider NPI filters, Taiga **intersects** the requested NPIs with your organization's allowed NPIs.

If no NPI filter is provided, Taiga still filters the response to your allowed NPIs.

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

## Object reads

For single-object reads, Taiga fetches the object and returns it only if it is in scope.

If the object is outside your scope, the response does not include the object. **Treat this the same way you would treat a missing resource.**

### Encounter sub-resources

Diagnoses, billing notes, guarantors, and tasks belong to an encounter, and the encounter's billing provider is what places them in your scope.

* A **diagnosis or guarantor id** becomes addressable once you created it through this API or read its encounter through this API. Any other id answers `404`, the same as an id that does not exist.
* A **billing note id** is addressable only when the note was created through this API. Notes the billing team writes appear on the encounter you read, but they are read-only: updating or deleting one answers `404`.
* A **task** on any encounter you can read is readable and updatable by id, with no prior read required. Taiga resolves the task to its encounter on first use.
* Creating a diagnosis or billing note requires `encounter_id` in the body. A missing or malformed value returns `422` naming the field; an encounter you cannot read returns `404`.

```bash
curl -X POST "https://api.taigabilling.com/api/billing_notes/v2" \
  -H "Authorization: Bearer $TAIGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "encounter_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "text": "Corrected member id; please resubmit." }'
```

> **Responding to a task**
>
> When a task asks you for data, correct the encounter, then `PATCH` the task
> with `status: "addressed_by_provider_group"`. The billing team re-reviews the
> claim from there.

## Writes

Writes are checked **before and after** forwarding.

| Stage       | Check                                               |
| ----------- | --------------------------------------------------- |
| Pre-flight  | Submitted billing-provider NPI is in your allowlist |
| Post-flight | Returned resource is still in scope                 |

If either check fails, Taiga returns an error and does not return the object.

### Patient payment allocations

`POST /api/patient-payments/v4` checks each claim or appointment allocation before creating a payment. Include exactly one allowed billing-provider NPI in `allocation_restrictions`, and use a patient and targets in your scope. Each request must use one allocation target type throughout; mixing claim and appointment allocations is refused. Unattributed payment creation is unsupported.

See [Creating patient payments](/patient-payments) for supported targets, the claim-payment requirements, rejection behavior, and a minimal request.

## Creating providers and service facilities

Creating an organization provider or service facility is the one write that can **extend your organization's scope**. Unlike other writes, the NPI on a provider create does not need to already be in your allowlist; this is how you register a new billing or rendering provider. On success, the new provider's NPI (and the provider or service-facility ID) is added to your organization's scope automatically, so follow-up requests that reference it are in scope.

```bash
curl -X POST "https://api.taigabilling.com/api/organization-providers/v3" \
  -H "Authorization: Bearer $TAIGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "npi": "1020555011", "is_rendering": true, "is_billing": false,
        "provider_type": "INDIVIDUAL", "license_type": "NP",
        "qualifications": [] }'
```

> **An NPI can belong to only one organization.**
>
> If the NPI you submit is already registered to another Taiga organization, the create is refused and Taiga responds as if the resource were not found. NPIs are not shared across organizations.

A few consequences to plan for:

* **Updates cannot move a provider to an NPI outside your scope.** A `PATCH` that changes a provider's `npi` to a value your organization does not already own is rejected. Only a create may introduce a new NPI.
* **Scope is additive.** Deleting a service facility, or terminating a provider with an `employment_termination_date`, does not remove it from your allowlist; the resource simply stops resolving. There is no request that shrinks your scope. Contact support to remove an entry.
* **Providers cannot be deleted** through the API. Use a `PATCH` with an `employment_termination_date` to deactivate one.

## Provisioning order

Scope starts empty. Until your organization has at least one **billing** provider, every create that has to be attributed to one is refused.

Create resources in this order:

1. **Billing provider**: `POST /api/organization-providers/v3` with `is_billing: true` and a `tax_id`. This is the request that gives your organization a billing-provider NPI.
2. **Rendering providers**: the same endpoint with `is_rendering: true`.
3. **Service facilities**: `POST /api/organization-service-facilities/v2`.
4. **Contracts, credentialing spans, and fee schedules.**
5. **Patients, coverages, encounters, and charge captures.**

> **Some creates are refused until step 1 succeeds.**
>
> Contracts, credentialing spans, fee schedules, encounters, and charge captures each depend on a billing provider. Created before one exists, they could not be attributed to one and would never appear in your reporting. Rather than accept them into that state, Taiga returns `422` naming the missing prerequisite.

Providers, service facilities, patients, and coverages carry no billing provider of their own, so you can create them at any point.

### contracting_provider_id names a billing provider

`contracting_provider_id` on a contract or credentialing span must be the `organization_provider_id` of a provider you created with `is_billing: true`. Passing a rendering-only provider returns `422`:

```json
{
  "errors": [
    {
      "expected": "a provider created with is_billing: true",
      "field": "contracting_provider_id",
      "message": "contracting_provider_id must name a billing provider; 8f2c… is a rendering-only provider",
      "received": "8f2c…"
    }
  ],
  "message": "Provisioning prerequisites are not met; complete the listed setup steps and retry"
}
```

A `contracting_provider_id` your organization does not own returns `404`, the same answer as an ID that does not exist. Treat both as "not available to you".

## Auditability

> **Audit metadata is scoped.**
>
> Partner API requests are audited with scoped metadata: credential, organization, method, path, status, request ID, upstream status or error class, and billing NPI when it is knowable.

Do not put PHI in:

* Credential labels
* Key names
* Operational notes
* Webhook configuration metadata