Guides

Ask a payer what it would pay before the treatment, read the estimate it sends back, and turn the predetermination into a claim once the work is done.

A predetermination asks the payer, before the treatment, what it would pay for it. In Claim House it is a claim of a second kind: you make it with the same endpoints and the same body as a claim, with "kind": "predetermination" and no service dates. It is validated, sent in the batch, acknowledged (997) and accepted (277) as a claim is. Then, instead of a payment, the payer sends back its estimate: what it would allow, what it would pay, and the patient's share. Once the work is done, you convert the predetermination into a claim, add the service dates, and send it.

With a test key, the sandbox answers every predetermination it accepts with its estimate 2 minutes after accepting it: on each line, an allowed amount below the fee, of which the payer would pay 80% and the patient 20%. The member ID scenarios that reject a claim reject a predetermination too. A key needs submit permission to make or convert one and read permission to read one. Live predeterminations open with live claims (see Going live).

Make a predetermination#

It names a rendering provider, as a claim does. Add one (or use the one from the Claims guide):

curl "https://sandbox.myclaimhouse.com/api/v1/providers" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "first_name": "Jordan",
  "last_name": "Example",
  "credential": "DMD",
  "npi": "1999990033",
  "license": { "number": "GA-000001", "state": "GA" }
}
EOF

Then POST /claims with "kind": "predetermination", and lines without a service_date:

curl "https://sandbox.myclaimhouse.com/api/v1/claims" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "kind": "predetermination",
  "office_id": "$OFFICE_ID",
  "payer_id": "$PAYER_ID",
  "rendering_provider_id": "$PROVIDER_ID",
  "subscriber": {
    "first_name": "Sam",
    "last_name": "Sample",
    "date_of_birth": "1980-02-02",
    "gender": "F",
    "member_id": "CH-ACTIVE-FULL",
    "address": { "line1": "1 Sample Street", "city": "Sampleville", "state": "GA", "postal_code": "30301" }
  },
  "lines": [{ "cdt": "D2740", "fee": 1140.00, "tooth": "3" }]
}
EOF

Everything a claim is checked for, a predetermination is checked for (the same findings), except the service dates: it has none, and a service_date on a line is an error, SERVICE_DATE_NOT_ALLOWED, on that line. The 837D carries the predetermination indicator on the claim (CLM19 PB) and no service date on any line: Claim House never sends a predetermination with one. Attachments work as on a claim, and an attachment for a predetermination needs no dates of service.

The kind is set when the predetermination is made and never changes: a PATCH with another kind is refused.

Find your predeterminations#

A list holds one kind: GET /claims lists your claims only, unless you ask for kind=predetermination:

curl "https://sandbox.myclaimhouse.com/api/v1/claims?kind=predetermination&limit=10" -H "Authorization: Bearer $CLAIMHOUSE_KEY"

Read one with GET /claims/{id}, and follow it on its timeline, as a claim:

curl "https://sandbox.myclaimhouse.com/api/v1/claims/$PREDETERMINATION_ID" -H "Authorization: Bearer $CLAIMHOUSE_KEY"

The estimate#

The payer answers a predetermination with a remittance (an 835) whose claim status is 25, "predetermination pricing only": it pays nothing. Claim House reads it as any ERA, matches it to your predetermination, and moves the predetermination to returned with its estimate:

{
  "era_id": "era_...",
  "allowed": "1026.00",
  "pay": "820.80",
  "patient": "205.20",
  "returned_at": "2026-09-24T21:03:30.000000+00:00",
  "lines": [{ "line_number": 1, "allowed": "1026.00", "pay": "820.80", "patient": "205.20" }]
}

allowed is what the payer would allow, pay what it would pay once the treatment is done (adjustment reason 101), and patient the patient's estimated share, for the whole and per line where the payer said. You get predetermination.returned (see Events and webhooks). A later estimate for the same predetermination replaces the first, even after it was converted (the claim made from it is not changed). An estimate that arrives while a void of the predetermination is open, or after it was voided, is left unmatched (claim_not_payable); if the payer rejects the void, match it by hand.

An estimate is never a payment: a predetermination has no payment, is never paid, denied or reconciled, posting its ERA reconciles nothing, and it sends no claim.paid. A status 25 answer that names one of your claims, or a payment that names a predetermination, is not applied: it stays unmatched in its ERA, with unmatched_reason estimate_for_claim or payment_for_predetermination, for you to look at. An ERA that carries only estimates is not a billable ERA (see Billing).

Convert it into a claim#

Once the treatment is done, POST /claims/{id}/convert makes a new claim from a returned predetermination: a draft with the same patient, subscriber, payer, office, provider and lines, and no service dates yet. The two are linked (converted_to on the predetermination, converted_from on the claim), and the predetermination's attachments move to the claim. Converting again answers with the same claim, unless that claim was voided before it was ever sent: then converting again makes a new claim, and the attachments the void released go on it. A predetermination with a void open cannot be converted. Before the estimate is back, the conversion is refused:

curl -X POST "https://sandbox.myclaimhouse.com/api/v1/claims/$PREDETERMINATION_ID/convert" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

When it is returned, the same request answers 200 with the predetermination and the new claim (claim.id). Add the service dates with PATCH /claims/{id} (send the lines with their service_date), then submit the claim as any other.

Corrections and voids#

• Rejected. A rejected predetermination is corrected and resubmitted as a claim is (POST /claims/{id}/resubmit): it goes out again as an original. A predetermination is never sent as a replacement.
• Accepted by the payer. To withdraw it, void it: a void transaction (itself a predetermination, with no service dates) goes to the payer. To change it, void it and make a new one.
• Returned. Convert it, leave it, or withdraw it with a void: a void transaction goes to the payer, and the predetermination becomes voided when the payer accepts it. A converted predetermination cannot be voided: void the claim made from it instead.

Billing#

A predetermination is billed like a claim: one claims unit when its file is handed to the network, under a reason of its own, never as a payment. A remittance that carries only estimates is recorded but not billed as an ERA (reason estimate_only); one that also pays claims is one ERA, as any other.