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.

How scoping works

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.

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.

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." }'

Writes

Writes are checked before and after forwarding.

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

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": [] }'

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.

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:

{
  "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

Do not put PHI in:

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