VSP claims in staging

Encounters whose patient's primary coverage resolves to VSP (payer ID 94163) are processed by Taiga's direct claims pipeline. Every other payer is unaffected. The request and response contracts are identical to the standard encounter create — no new fields are required.

In staging, VSP claims are always simulated: a deterministic validator produces the outcome and no claim is ever sent to a clearinghouse or payer.

Find VSP in the payer directory

Use List payers with search_term=VSP. The same search also matches 94163, GWRCD, Vision Service Plan, and Eyefinity.

VSP supports professional claim submission without enrollment. Eligibility checks are not supported, and electronic remittance requires enrollment.

Submit a synthetic claim

Use the standard encounter create with a patient whose primary coverage is VSP. All identifiers below are synthetic.

curl --request POST \
  --url https://api-staging.taigabilling.com/api/encounters/v4/create-from-pre-encounter \
  --header "Authorization: Bearer $TAIGA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "pre_encounter_patient_id": "6f9a2b1c-0000-4000-8000-000000000001",
    "pre_encounter_appointment_ids": [],
    "external_id": "vsp-test-0001",
    "billable_status": "BILLABLE",
    "benefits_assigned_to_provider": true,
    "patient_authorized_release": true,
    "provider_accepts_assignment": true,
    "place_of_service_code": "11",
    "billing_provider": {
      "npi": "1999999984",
      "organization_name": "Example Eye Care",
      "tax_id": "000000000",
      "address": {
        "address1": "100 Example Way",
        "city": "Springfield",
        "state": "NJ",
        "zip_code": "07000",
        "zip_plus_four_code": "1234"
      }
    },
    "rendering_provider": {
      "npi": "1999999992",
      "first_name": "Alex",
      "last_name": "Example"
    },
    "diagnoses": [{ "code": "H52.13", "code_type": "ABK" }],
    "service_lines": [
      {
        "procedure_code": "92014",
        "charge_amount_cents": 12500,
        "date_of_service": "2026-08-01",
        "quantity": "1",
        "units": "UN",
        "diagnosis_pointers": [0]
      }
    ]
  }'

VSP claims require the billing provider address and tax ID, appointment IDs, a standard place-of-service code, ICD-10 diagnoses (the principal ABK code first, then up to 11 ABF codes), and each service line's charge, quantity (whole or one decimal digit), units (UN or MJ), diagnosis pointers, up to four two-character modifiers, and a date of service (on the lines or the encounter, but not both); a request missing or violating any of these returns 422 listing the fields. service_facility and service_facility_id are mutually exclusive, and a facility must be provided inline. NOT_BILLABLE encounters are never routed as claims.

Coverage requirements

Once the patient's primary coverage resolves to VSP, the coverage itself must carry the demographics the claim is built from. The coverage must be a SELF subscriber relationship and include the member ID, the subscriber's first and last name, date of birth, and complete address (line, city, state, and postal code); the patient record must also have an MRN, name, date of birth, and a complete address.

If any of these are missing or unsupported, the request returns 422 with a message and field-level errors entries naming the coverage or patient fields to correct (for example coverage.subscriber.address.line). The claim is not created, nothing is submitted, and the request is not forwarded to the standard encounter pipeline — correct the coverage or patient data and retry with the same external_id. Non-SELF VSP coverage returns 422 on coverage.relationship.

The response is the standard encounter shape. encounter_id is the stable Taiga claim ID and claims[0].status carries the outcome: submitted_to_payer for an accepted test claim, rejected for a rejected one.

Trigger a rejected outcome

Outcomes are keyed on external_id: an external_id ending in -REJECT is deterministically rejected; every other claim is accepted.

{
  "external_id": "vsp-test-0002-REJECT"
}

Retries and idempotency

Retrying a create with the same external_id and a semantically identical JSON body replays the original claim (with an Idempotent-Replayed: true response header) — whitespace and object-key order do not matter, and the claim is never submitted twice. Reusing an external_id with different claim data returns 409 Conflict. If submission is temporarily unavailable the API returns 502; retry with the same external_id and the original claim ID is kept. A 202 Accepted response means the submission is still in flight or requires reconciliation; do not create a new external_id for it.

Read a claim back

curl --request GET \
  --url https://api-staging.taigabilling.com/api/encounters/v4/$ENCOUNTER_ID \
  --header "Authorization: Bearer $TAIGA_API_KEY"

Reads are tenant-scoped: claims outside your organization's billing-provider NPI scope are indistinguishable from unknown IDs.

You can also find a claim by its original external ID:

curl --request GET \
  --url "https://api-staging.taigabilling.com/api/encounters/v4?external_id=$EXTERNAL_ID" \
  --header "Authorization: Bearer $TAIGA_API_KEY"