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

# Trigger a prior-authorization test status

POST https://api.taigabilling.com/api/prior-authorizations/v1/{id}/test-status
Content-Type: application/json

Sets a deterministic outcome on a request created with test_mode=true and enqueues the same signed webhook used by live status changes. Ordinary requests cannot use this endpoint. A terminal test outcome cannot be changed; create a separate test request for each terminal scenario. See [test statuses and webhook examples](/docs/prior-authorization-webhooks).

Reference: https://docs.taigabilling.com/api-reference/prior-authorizations/trigger-prior-authorization-test-status

## Authentication

- `Authorization` header (bearer token, required) — Send your Taiga API key as a Bearer token. Create and manage keys in the Taiga developer portal.

## Servers

- `https://api.taigabilling.com` (Production, default)
- `https://api-staging.taigabilling.com` (Staging)

## Request

### Path parameters

- `id` (string, required)

### Body (application/json)

This endpoint expects a PriorAuthorizationTestStatusRequest.

- `status` (enum, required) — The deterministic test outcome to emit.
  - Allowed values: `NEEDS_INFORMATION`, `PARTIALLY_APPROVED`, `DENIED`

## Response

### 200

Test status triggered

- `billing_provider_npi` (string, required)
- `coverage_id` (string, required) — Existing patient coverage. Taiga resolves payer, plan, member, and routing details from this coverage.
- `diagnosis_codes` (list of string, required)
- `external_id` (string, required) — Partner-generated idempotency key. Replays with an identical body return the existing request; a different body returns 409.
- `patient_id` (string, required)
- `place_of_service_code` (string, required) — Two-digit CMS place-of-service code for the requested care.
- `plan_of_care` (PriorAuthorizationPlanOfCare, required) — Requested treatment window, visits, frequency, and evaluation date.
- `rendering_provider_npi` (string, required) — Rendering therapist NPI. This NPI must be in the partner organization's scope.
- `request_type` (enum, required, default: INITIAL) — REAUTHORIZATION also requires previous_authorization. INITIAL is used for a new patient, condition, or payer-defined new episode.
  - Allowed values: `INITIAL`, `REAUTHORIZATION`, `MODIFICATION`, `RETROSPECTIVE`
- `service_facility_id` (string, required)
- `service_lines` (list of PriorAuthorizationServiceLinesItems, required) — Requested CPT/HCPCS codes. Procedure-level units and dates are optional when the plan_of_care supplies the visit-level request.
- `service_type` (enum, required, default: PHYSICAL_THERAPY)
  - Allowed values: `PHYSICAL_THERAPY`, `OCCUPATIONAL_THERAPY`, `SPEECH_THERAPY`, `OTHER`
- `supporting_documents` (list of PriorAuthorizationSupportingDocumentsItems, required) — Existing uploaded document IDs with semantic types. Upload the file first: POST /images/v1 returns an id, a version and a signed\_url; PUT the bytes to that signed\_url; then PUT /images/v1/\{id}/\{version} with status UPLOADED, where the version segment is the current version plus 1 (so 1 for a freshly created image). Use the image id as document\_id. Documents are optional at intake; missing payer-required documents produce NEEDS\_INFORMATION.
- `test_mode` (boolean, required)
- `urgency` (enum, required, default: ROUTINE) — URGENT requires urgency_reason and should only be used when the payer's expedited-review standard is met.
  - Allowed values: `ROUTINE`, `URGENT`
- `created_at` (datetime, required)
- `id` (string, required)
- `last_status_at` (datetime, required)
- `payer_id` (string, required)
- `payer_name` (string, required)
- `status` (enum, required)
  - Allowed values: `RECEIVED`, `NEEDS_INFORMATION`, `READY_FOR_REVIEW`, `AUTHORIZATION_NOT_REQUIRED`, `SUBMITTED`, `PENDING_PAYER`, `APPROVED`, `PARTIALLY_APPROVED`, `DENIED`, `CANCELLED`
- `updated_at` (datetime, required)
- `clinical_information` (PriorAuthorizationClinicalInformation, optional, nullable)
- `clinical_notes` (string, optional, nullable)
- `contact` (PriorAuthorizationContact, optional, nullable)
- `ordering_provider` (PriorAuthorizationOrderingProvider, optional, nullable)
- `payer_specific_fields` (map from string to PriorAuthorizationPayerSpecificFields, optional, default: {}) — Escape hatch for payer questions discovered during requirements review. Use stable snake_case keys supplied by Taiga.
- `previous_authorization` (PriorAuthorizationPreviousAuthorization, optional, nullable)
- `referring_provider` (PriorAuthorizationReferringProvider, optional, nullable)
- `requesting_provider_npi` (string, optional, nullable)
- `therapy_attestations` (PriorAuthorizationTherapyAttestations, optional, default: {})
- `urgency_reason` (string, optional, nullable)
- `approved_unit_type` (string, optional, nullable)
- `approved_units` (integer, optional, nullable)
- `authorized_service_lines` (list of PriorAuthorizationAuthorizedServiceLinesItems, optional)
- `determined_at` (datetime, optional, nullable)
- `effective_date` (date, optional, nullable)
- `expiration_date` (date, optional, nullable)
- `plan_name` (string, optional, nullable)
- `plan_type` (string, optional, nullable)
- `portal_reference_number` (string, optional, nullable)
- `prior_authorization_number` (string, optional, nullable)
- `requirements_checked_at` (datetime, optional, nullable)
- `status_message` (string, optional, nullable)
- `submission_channel` (enum, optional, nullable)
  - Allowed values: `PORTAL`, `PHONE`, `FAX`, `API`, `OTHER`
- `submission_destination` (string, optional, nullable)
- `submitted_at` (datetime, optional, nullable)

## Errors

### 400 Bad Request Error

The request could not be completed.

- `message` (string, required)

### 401 Unauthorized Error

The request could not be completed.

- `message` (string, required)

### 404 Not Found Error

The request could not be completed.

- `message` (string, required)

### 409 Conflict Error

The request could not be completed.

- `message` (string, required)

## Types

### PriorAuthorizationPlanOfCare

Requested treatment window, visits, frequency, and evaluation date.

- `end_date` (date, required)
- `evaluation_date` (date, required)
- `frequency` (PriorAuthorizationPlanOfCareFrequency, required)
- `requested_visits` (integer, required) — Total visits requested for the plan of care. This is the plan-level request and is never divided or copied across service lines; it is inherited by a service line only when the request has exactly one line with unit_type VISITS and no requested_units.
- `start_date` (date, required)
- `frequency_notes` (string, optional)

### PriorAuthorizationServiceLinesItems

- `procedure_code` (string, required)
- `end_date` (date, optional)
- `frequency` (string, optional)
- `modifiers` (list of string, optional, default: [])
- `place_of_service_code` (string, optional)
- `requested_units` (integer, optional) — Requested quantity for this service line. Optional at intake; payers that authorize per service line require it on every line before submission. Sole exception: a request with exactly one service line whose unit_type is VISITS inherits plan_of_care.requested_visits. With multiple lines the plan total is never divided or copied — missing values result in a NEEDS_INFORMATION status naming the affected procedure codes when the clinic runs its Availity readiness review.
- `start_date` (date, optional)
- `unit_type` (enum, optional, default: VISITS) — Unit of the requested quantity. VISITS and UNITS have verified payer-portal quantity codes; other values are accepted at intake but produce a NEEDS_INFORMATION status when the clinic runs its Availity readiness review before submission.
  - Allowed values: `VISITS`, `UNITS`, `DAYS`, `PROCEDURES`, `OTHER`

### PriorAuthorizationSupportingDocumentsItems

- `document_id` (string, required)
- `document_type` (enum, required)
  - Allowed values: `INITIAL_EVALUATION`, `PLAN_OF_CARE`, `PHYSICIAN_ORDER`, `PROGRESS_NOTE`, `OUTCOME_MEASURE`, `IEP`, `IMAGING_REPORT`, `OPERATIVE_REPORT`, `OTHER`
- `title` (string, optional)

### PriorAuthorizationClinicalInformation

- `accident_date` (date, optional)
- `accident_state` (string, optional)
- `accident_type` (enum, optional)
  - Allowed values: `AUTO`, `EMPLOYMENT`, `OTHER`
- `body_regions` (list of string, optional)
- `clinical_summary` (string, optional)
- `comorbidities` (list of string, optional)
- `cva_date` (date, optional)
- `functional_limitations` (list of string, optional)
- `home_exercise_program` (string, optional)
- `laterality` (enum, optional)
  - Allowed values: `LEFT`, `RIGHT`, `BILATERAL`, `NOT_APPLICABLE`
- `medical_necessity_rationale` (string, optional)
- `objective_findings` (string, optional)
- `onset_date` (date, optional)
- `prior_treatments_and_response` (string, optional)
- `prognosis` (string, optional)
- `progress_summary` (string, optional)
- `standardized_tests` (list of PriorAuthorizationClinicalInformationStandardizedTestsItems, optional)
- `surgery_date` (date, optional)
- `surgery_procedure` (string, optional)
- `treatment_goals` (list of string, optional)

### PriorAuthorizationContact

- `name` (string, required)
- `email` (string, optional)
- `fax` (string, optional)
- `phone` (string, optional)

### PriorAuthorizationOrderingProvider

- `npi` (string, required)
- `contact_name` (string, optional)
- `fax` (string, optional)
- `name` (string, optional)
- `phone` (string, optional)

### PriorAuthorizationPayerSpecificFields

- string
- double
- boolean
- any
- list of any

### PriorAuthorizationPreviousAuthorization

- `prior_authorization_number` (string, required)
- `approved_visits` (integer, optional)
- `effective_date` (date, optional)
- `expiration_date` (date, optional)
- `used_visits` (integer, optional)

### PriorAuthorizationReferringProvider

- `npi` (string, required)
- `contact_name` (string, optional)
- `fax` (string, optional)
- `name` (string, optional)
- `phone` (string, optional)

### PriorAuthorizationTherapyAttestations

- `ordering_provider_approved_plan_of_care` (boolean, optional)
- `ordering_provider_will_be_notified_at_discharge` (boolean, optional)
- `plan_of_care_reviewed_with_patient` (boolean, optional)
- `school_iep_unavailable_reason` (string, optional)

### PriorAuthorizationAuthorizedServiceLinesItems

- `approved_units` (integer, required)
- `procedure_code` (string, required)
- `unit_type` (enum, required)
  - Allowed values: `VISITS`, `UNITS`, `DAYS`, `PROCEDURES`, `OTHER`
- `effective_date` (date, optional)
- `expiration_date` (date, optional)
- `modifiers` (list of string, optional)

### PriorAuthorizationPlanOfCareFrequency

- `count` (integer, required)
- `period` (enum, required)
  - Allowed values: `WEEK`, `MONTH`

### PriorAuthorizationClinicalInformationStandardizedTestsItems

- `name` (string, required)
- `result` (string, required)
- `date` (date, optional)

## Examples

### denied

**Request**

```json
{
  "status": "DENIED"
}
```

**Response**

```json
{
  "billing_provider_npi": "string",
  "coverage_id": "string",
  "diagnosis_codes": [
    "string"
  ],
  "external_id": "string",
  "patient_id": "string",
  "place_of_service_code": "string",
  "plan_of_care": {
    "end_date": "2023-01-15",
    "evaluation_date": "2023-01-15",
    "frequency": {
      "count": 1,
      "period": "WEEK"
    },
    "requested_visits": 1,
    "start_date": "2023-01-15",
    "frequency_notes": "string"
  },
  "rendering_provider_npi": "string",
  "request_type": "INITIAL",
  "service_facility_id": "string",
  "service_lines": [
    {
      "procedure_code": "string",
      "end_date": "2023-01-15",
      "frequency": "string",
      "modifiers": [
        "string"
      ],
      "place_of_service_code": "string",
      "requested_units": 1,
      "start_date": "2023-01-15",
      "unit_type": "VISITS"
    }
  ],
  "service_type": "PHYSICAL_THERAPY",
  "supporting_documents": [
    {
      "document_id": "string",
      "document_type": "INITIAL_EVALUATION",
      "title": "string"
    }
  ],
  "test_mode": true,
  "urgency": "ROUTINE",
  "created_at": "2024-01-15T09:30:00Z",
  "id": "string",
  "last_status_at": "2024-01-15T09:30:00Z",
  "payer_id": "string",
  "payer_name": "string",
  "status": "RECEIVED",
  "updated_at": "2024-01-15T09:30:00Z",
  "clinical_information": {
    "accident_date": "2023-01-15",
    "accident_state": "string",
    "accident_type": "AUTO",
    "body_regions": [
      "string"
    ],
    "clinical_summary": "string",
    "comorbidities": [
      "string"
    ],
    "cva_date": "2023-01-15",
    "functional_limitations": [
      "string"
    ],
    "home_exercise_program": "string",
    "laterality": "LEFT",
    "medical_necessity_rationale": "string",
    "objective_findings": "string",
    "onset_date": "2023-01-15",
    "prior_treatments_and_response": "string",
    "prognosis": "string",
    "progress_summary": "string",
    "standardized_tests": [
      {
        "name": "string",
        "result": "string",
        "date": "2023-01-15"
      }
    ],
    "surgery_date": "2023-01-15",
    "surgery_procedure": "string",
    "treatment_goals": [
      "string"
    ]
  },
  "clinical_notes": "string",
  "contact": {
    "name": "string",
    "email": "string",
    "fax": "string",
    "phone": "string"
  },
  "ordering_provider": {
    "npi": "string",
    "contact_name": "string",
    "fax": "string",
    "name": "string",
    "phone": "string"
  },
  "payer_specific_fields": {},
  "previous_authorization": {
    "prior_authorization_number": "string",
    "approved_visits": 1,
    "effective_date": "2023-01-15",
    "expiration_date": "2023-01-15",
    "used_visits": 1
  },
  "referring_provider": {
    "npi": "string",
    "contact_name": "string",
    "fax": "string",
    "name": "string",
    "phone": "string"
  },
  "requesting_provider_npi": "string",
  "therapy_attestations": {
    "ordering_provider_approved_plan_of_care": true,
    "ordering_provider_will_be_notified_at_discharge": true,
    "plan_of_care_reviewed_with_patient": true,
    "school_iep_unavailable_reason": "string"
  },
  "urgency_reason": "string",
  "approved_unit_type": "string",
  "approved_units": 1,
  "authorized_service_lines": [
    {
      "approved_units": 1,
      "procedure_code": "string",
      "unit_type": "VISITS",
      "effective_date": "2023-01-15",
      "expiration_date": "2023-01-15",
      "modifiers": [
        "string"
      ]
    }
  ],
  "determined_at": "2024-01-15T09:30:00Z",
  "effective_date": "2023-01-15",
  "expiration_date": "2023-01-15",
  "plan_name": "string",
  "plan_type": "string",
  "portal_reference_number": "string",
  "prior_authorization_number": "string",
  "requirements_checked_at": "2024-01-15T09:30:00Z",
  "status_message": "string",
  "submission_channel": "PORTAL",
  "submission_destination": "string",
  "submitted_at": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python denied
import requests

url = "https://api.taigabilling.com/api/prior-authorizations/v1/id/test-status"

payload = { "status": "DENIED" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

### needsInformation

**Request**

```json
{
  "status": "NEEDS_INFORMATION"
}
```

**Response**

```json
{
  "billing_provider_npi": "string",
  "coverage_id": "string",
  "diagnosis_codes": [
    "string"
  ],
  "external_id": "string",
  "patient_id": "string",
  "place_of_service_code": "string",
  "plan_of_care": {
    "end_date": "2023-01-15",
    "evaluation_date": "2023-01-15",
    "frequency": {
      "count": 1,
      "period": "WEEK"
    },
    "requested_visits": 1,
    "start_date": "2023-01-15",
    "frequency_notes": "string"
  },
  "rendering_provider_npi": "string",
  "request_type": "INITIAL",
  "service_facility_id": "string",
  "service_lines": [
    {
      "procedure_code": "string",
      "end_date": "2023-01-15",
      "frequency": "string",
      "modifiers": [
        "string"
      ],
      "place_of_service_code": "string",
      "requested_units": 1,
      "start_date": "2023-01-15",
      "unit_type": "VISITS"
    }
  ],
  "service_type": "PHYSICAL_THERAPY",
  "supporting_documents": [
    {
      "document_id": "string",
      "document_type": "INITIAL_EVALUATION",
      "title": "string"
    }
  ],
  "test_mode": true,
  "urgency": "ROUTINE",
  "created_at": "2024-01-15T09:30:00Z",
  "id": "string",
  "last_status_at": "2024-01-15T09:30:00Z",
  "payer_id": "string",
  "payer_name": "string",
  "status": "RECEIVED",
  "updated_at": "2024-01-15T09:30:00Z",
  "clinical_information": {
    "accident_date": "2023-01-15",
    "accident_state": "string",
    "accident_type": "AUTO",
    "body_regions": [
      "string"
    ],
    "clinical_summary": "string",
    "comorbidities": [
      "string"
    ],
    "cva_date": "2023-01-15",
    "functional_limitations": [
      "string"
    ],
    "home_exercise_program": "string",
    "laterality": "LEFT",
    "medical_necessity_rationale": "string",
    "objective_findings": "string",
    "onset_date": "2023-01-15",
    "prior_treatments_and_response": "string",
    "prognosis": "string",
    "progress_summary": "string",
    "standardized_tests": [
      {
        "name": "string",
        "result": "string",
        "date": "2023-01-15"
      }
    ],
    "surgery_date": "2023-01-15",
    "surgery_procedure": "string",
    "treatment_goals": [
      "string"
    ]
  },
  "clinical_notes": "string",
  "contact": {
    "name": "string",
    "email": "string",
    "fax": "string",
    "phone": "string"
  },
  "ordering_provider": {
    "npi": "string",
    "contact_name": "string",
    "fax": "string",
    "name": "string",
    "phone": "string"
  },
  "payer_specific_fields": {},
  "previous_authorization": {
    "prior_authorization_number": "string",
    "approved_visits": 1,
    "effective_date": "2023-01-15",
    "expiration_date": "2023-01-15",
    "used_visits": 1
  },
  "referring_provider": {
    "npi": "string",
    "contact_name": "string",
    "fax": "string",
    "name": "string",
    "phone": "string"
  },
  "requesting_provider_npi": "string",
  "therapy_attestations": {
    "ordering_provider_approved_plan_of_care": true,
    "ordering_provider_will_be_notified_at_discharge": true,
    "plan_of_care_reviewed_with_patient": true,
    "school_iep_unavailable_reason": "string"
  },
  "urgency_reason": "string",
  "approved_unit_type": "string",
  "approved_units": 1,
  "authorized_service_lines": [
    {
      "approved_units": 1,
      "procedure_code": "string",
      "unit_type": "VISITS",
      "effective_date": "2023-01-15",
      "expiration_date": "2023-01-15",
      "modifiers": [
        "string"
      ]
    }
  ],
  "determined_at": "2024-01-15T09:30:00Z",
  "effective_date": "2023-01-15",
  "expiration_date": "2023-01-15",
  "plan_name": "string",
  "plan_type": "string",
  "portal_reference_number": "string",
  "prior_authorization_number": "string",
  "requirements_checked_at": "2024-01-15T09:30:00Z",
  "status_message": "string",
  "submission_channel": "PORTAL",
  "submission_destination": "string",
  "submitted_at": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python needsInformation
import requests

url = "https://api.taigabilling.com/api/prior-authorizations/v1/id/test-status"

payload = { "status": "NEEDS_INFORMATION" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

### partiallyApproved

**Request**

```json
{
  "status": "PARTIALLY_APPROVED"
}
```

**Response**

```json
{
  "billing_provider_npi": "string",
  "coverage_id": "string",
  "diagnosis_codes": [
    "string"
  ],
  "external_id": "string",
  "patient_id": "string",
  "place_of_service_code": "string",
  "plan_of_care": {
    "end_date": "2023-01-15",
    "evaluation_date": "2023-01-15",
    "frequency": {
      "count": 1,
      "period": "WEEK"
    },
    "requested_visits": 1,
    "start_date": "2023-01-15",
    "frequency_notes": "string"
  },
  "rendering_provider_npi": "string",
  "request_type": "INITIAL",
  "service_facility_id": "string",
  "service_lines": [
    {
      "procedure_code": "string",
      "end_date": "2023-01-15",
      "frequency": "string",
      "modifiers": [
        "string"
      ],
      "place_of_service_code": "string",
      "requested_units": 1,
      "start_date": "2023-01-15",
      "unit_type": "VISITS"
    }
  ],
  "service_type": "PHYSICAL_THERAPY",
  "supporting_documents": [
    {
      "document_id": "string",
      "document_type": "INITIAL_EVALUATION",
      "title": "string"
    }
  ],
  "test_mode": true,
  "urgency": "ROUTINE",
  "created_at": "2024-01-15T09:30:00Z",
  "id": "string",
  "last_status_at": "2024-01-15T09:30:00Z",
  "payer_id": "string",
  "payer_name": "string",
  "status": "RECEIVED",
  "updated_at": "2024-01-15T09:30:00Z",
  "clinical_information": {
    "accident_date": "2023-01-15",
    "accident_state": "string",
    "accident_type": "AUTO",
    "body_regions": [
      "string"
    ],
    "clinical_summary": "string",
    "comorbidities": [
      "string"
    ],
    "cva_date": "2023-01-15",
    "functional_limitations": [
      "string"
    ],
    "home_exercise_program": "string",
    "laterality": "LEFT",
    "medical_necessity_rationale": "string",
    "objective_findings": "string",
    "onset_date": "2023-01-15",
    "prior_treatments_and_response": "string",
    "prognosis": "string",
    "progress_summary": "string",
    "standardized_tests": [
      {
        "name": "string",
        "result": "string",
        "date": "2023-01-15"
      }
    ],
    "surgery_date": "2023-01-15",
    "surgery_procedure": "string",
    "treatment_goals": [
      "string"
    ]
  },
  "clinical_notes": "string",
  "contact": {
    "name": "string",
    "email": "string",
    "fax": "string",
    "phone": "string"
  },
  "ordering_provider": {
    "npi": "string",
    "contact_name": "string",
    "fax": "string",
    "name": "string",
    "phone": "string"
  },
  "payer_specific_fields": {},
  "previous_authorization": {
    "prior_authorization_number": "string",
    "approved_visits": 1,
    "effective_date": "2023-01-15",
    "expiration_date": "2023-01-15",
    "used_visits": 1
  },
  "referring_provider": {
    "npi": "string",
    "contact_name": "string",
    "fax": "string",
    "name": "string",
    "phone": "string"
  },
  "requesting_provider_npi": "string",
  "therapy_attestations": {
    "ordering_provider_approved_plan_of_care": true,
    "ordering_provider_will_be_notified_at_discharge": true,
    "plan_of_care_reviewed_with_patient": true,
    "school_iep_unavailable_reason": "string"
  },
  "urgency_reason": "string",
  "approved_unit_type": "string",
  "approved_units": 1,
  "authorized_service_lines": [
    {
      "approved_units": 1,
      "procedure_code": "string",
      "unit_type": "VISITS",
      "effective_date": "2023-01-15",
      "expiration_date": "2023-01-15",
      "modifiers": [
        "string"
      ]
    }
  ],
  "determined_at": "2024-01-15T09:30:00Z",
  "effective_date": "2023-01-15",
  "expiration_date": "2023-01-15",
  "plan_name": "string",
  "plan_type": "string",
  "portal_reference_number": "string",
  "prior_authorization_number": "string",
  "requirements_checked_at": "2024-01-15T09:30:00Z",
  "status_message": "string",
  "submission_channel": "PORTAL",
  "submission_destination": "string",
  "submitted_at": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python partiallyApproved
import requests

url = "https://api.taigabilling.com/api/prior-authorizations/v1/id/test-status"

payload = { "status": "PARTIALLY_APPROVED" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```