Making Requests
Request format, headers, and common examples.
The Partner API preserves the endpoint paths and wire shapes shown in the
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:
Authorization: Bearer <api key>
Content-Type: application/jsonExamples
curl "https://api.taigabilling.com/api/encounters/v4?limit=10" \
-H "Authorization: Bearer $TAIGA_API_KEY"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.
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
{
"items": [],
"next_page_token": "",
"prev_page_token": null
}The exact item shape is documented in the 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 contains: