Claims

Reconcile a claim

POST/api/v1/claims/{id}/reconcile

Says you posted the claim's payment in your system: a paid or denied claim becomes reconciled (a reconciled one is returned as it is). If the payer later reverses or corrects the payment, the claim leaves reconciled with a timeline entry and an event (claim.payment_reversed or claim.paid), so you can undo or redo the posting. To post every claim of a remittance at once, post its ERA. Send an empty JSON object as the body. Needs an Idempotency-Key header and a key with the submit permission.

Needs a key with submit permission.

Request

Headers

Headers
Name	Type	Required	Description
Idempotency-Key	string	required	Makes the request safe to repeat: a request with the same key and body returns the first answer (the reply has an idempotent-replayed header), and the same key with a different request is refused. 1 to 255 printable characters; a UUID is a good choice.At least 1 character.At most 255 characters.Matches `^[\x21-\x7e]{1,255}$`.

Path parameters

Path parameters
Name	Type	Required	Description
id	string	required	A claim ID (clm_...).

Response

The claim as it is now. Status 200.

Response fields
Name	Type	Description
id	string	An ID that starts with clm_.
object	string	Always `claim`.
kind	string	claim, or predetermination (sent before treatment; its answer is an estimate). Set when it was made.One of: `claim`, `predetermination`.
state	string	One of: `draft`, `validated`, `needs_attention`, `queued`, `submitted`, `accepted_clearinghouse`, `accepted_payer`, `rejected`, `voided`, `paid`, `denied`, `reconciled`, `returned`.
next_step	string	One sentence saying what happens next, or what you must do.
frequency	string	original; replacement for a resubmission of a claim the payer has; void for a void transaction.One of: `original`, `replacement`, `void`.
parent_id	string or null	The claim a void transaction voids.
patient_control_number	string	Your identifier for the claim, or the one we made: unique in your organization, sent on the claim and returned on its status.
office	object
office.id	string	An ID that starts with off_.
office.name	string
payer	object
payer.id	string	An ID that starts with pyr_.
payer.payer_id	string	The payer's own payer ID.
payer.name	string
rendering_provider	object
rendering_provider.id	string	An ID that starts with prv_.
rendering_provider.first_name	string
rendering_provider.last_name	string
rendering_provider.npi	string
patient_name	object	The patient: the dependent when there is one, else the subscriber.
patient_name.first_name	string
patient_name.last_name	string
patient_id	string or null	The patient this is about (pat_...) in the patient directory: the dependent when there is one, else the subscriber. Set by Claim House when a check completes or a claim's patient is written; null while a check is pending, and when the patient has no date of birth or a name with no letters or digits to compare.
service_dates	object
service_dates.first	string (date) or null
service_dates.last	string (date) or null
totals	object
totals.charge	string	The sum of the line fees, in dollars, as a decimal string.Matches `^-?\d+\.\d{2}$`.
totals.lines	integer	At least -9007199254740991.
payment	object or null	What the payer paid (states paid, denied and reconciled), from its remittances; null before one arrives, when every payment was reversed, and always on a predetermination.
payment.outcome	string	paid or denied: the outcome of the claim's current payment (the latest one no reversal cancelled). A reconciled claim keeps it.One of: `paid`, `denied`.
payment.era_id	string	The ERA of the claim's current payment (era_...): the latest one, when that is not certain.
payment.paid	string	What the payer paid in all: the sum of every payment applied, reversals subtracted.Matches `^-?\d+\.\d{2}$`.
payment.allowed	string or null	The amount the current payment allowed, when it said.Matches `^-?\d+\.\d{2}$`.
payment.patient_responsibility	string	What the patient owes, as the payer says (deductible, coinsurance and the like).Matches `^-?\d+\.\d{2}$`.
payment.payment_date	string (date) or null	The payment date of the ERA.
payment.reconciled_at	string (date-time) or null	When you confirmed you posted the payment (state reconciled); null until then.
estimate	object or null	A predetermination's estimate (state returned); null before it arrives, and always on a claim.
estimate.era_id	string	The ERA that carried the estimate (era_...).
estimate.allowed	string or null	What the payer would allow, when it said.Matches `^-?\d+\.\d{2}$`.
estimate.pay	string	What the payer would pay once the treatment is done.Matches `^-?\d+\.\d{2}$`.
estimate.patient	string	The patient's estimated share.Matches `^-?\d+\.\d{2}$`.
estimate.returned_at	string (date-time)	When the estimate arrived.
estimate.lines	array of object	The estimate per line, where the payer said (line_number is the predetermination's).
estimate.lines[].line_number	integer	At least 1.
estimate.lines[].allowed	string or null	An amount in dollars, as a decimal string with two places (such as "113.60").Matches `^-?\d+\.\d{2}$`.
estimate.lines[].pay	string	An amount in dollars, as a decimal string with two places (such as "113.60").Matches `^-?\d+\.\d{2}$`.
estimate.lines[].patient	string	An amount in dollars, as a decimal string with two places (such as "113.60").Matches `^-?\d+\.\d{2}$`.
converted_from	string or null	On a claim made from a predetermination: the predetermination.
converted_to	string or null	On a converted predetermination: the claim made from it.
request_id	string or null	The API request that made the claim (the x-request-id of its response); null for a claim made in the dashboard.
created_at	string (date-time)
updated_at	string (date-time)
subscriber	object
subscriber.first_name	string
subscriber.last_name	string
subscriber.date_of_birth	string (date) or null
subscriber.gender	string or null	One of: `F`, `M`, `U`.
subscriber.member_id	string
subscriber.group_number	value
subscriber.address	object or null
subscriber.address.line1	string
subscriber.address.line2	value
subscriber.address.city	string
subscriber.address.state	string
subscriber.address.postal_code	string
patient	object or null	The patient, when not the subscriber.
patient.first_name	string
patient.last_name	string
patient.date_of_birth	string (date) or null
patient.gender	string or null	One of: `F`, `M`, `U`.
patient.relationship	string	One of: `spouse`, `child`, `other`.
patient.address	object or null
patient.address.line1	string
patient.address.line2	value
patient.address.city	string
patient.address.state	string
patient.address.postal_code	string
place_of_service	string
lines	array of object
lines[].line_number	integer	At least 1.
lines[].cdt	string
lines[].description	value	The description you sent, or our short description of the code when you sent none and it is a common one.
lines[].service_date	string (date) or null	The date of service. Null on a predetermination (it has none), and on a claim made from one until you add it.
lines[].fee	string	The charge for the whole line, in dollars, as a decimal string (never multiplied by the quantity).Matches `^-?\d+\.\d{2}$`.
lines[].quantity	integer	How many units the line is for: a count sent with the line (SV306).At least -9007199254740991.
lines[].tooth	value
lines[].surfaces	value
lines[].area	value	The oral cavity code: a quadrant (10, 20, 30, 40), an arch (01, 02) or 00.
remarks	value
metadata	object
attachments	array of string	The attachments the claim carries, in the order the claim file writes them (a PWK and a note for each).Each item matches `^att_[0-9A-HJKMNP-TV-Z]{26}$`.
validation	object or null	The result of the last validation; null while the claim has not been validated.
validation.validated_at	string (date-time)
validation.errors	integer	At least -9007199254740991.
validation.warnings	integer	At least -9007199254740991.
validation.findings	array of object
validation.findings[].field	value	The request field the finding is about, as a dotted path (lines[0].tooth), or null for the claim as a whole.
validation.findings[].code	string	A stable code for the finding.
validation.findings[].message	string
validation.findings[].severity	string	An error keeps the claim from being sent; a warning does not.One of: `error`, `warning`.
network	object
network.submitted_at	string (date-time) or null
network.clearinghouse_claim_id	value
network.payer_claim_number	value	The payer's own number for the claim, once it has accepted it.
network.rejection	object or null
network.rejection.source	string	One of: `clearinghouse`, `payer`.
network.rejection.category	value	The status category code from the 277 (such as A7).
network.rejection.code	value	The status code from the 277 (such as 33).
network.rejection.message	string	Why, in plain words.
network.rejection.fix	value	What to change, when it is known.
idempotency_key	value	The Idempotency-Key the claim was sent with.

Errors

Errors
HTTP status	Code	What it means
401	UNAUTHORIZED	A valid API key is required. Send it as "Authorization: Bearer <key>".
403	PERMISSION_DENIED	This API key is not allowed to do that.
404	NOT_FOUND	Not found.
422	INVALID_REQUEST	The request is not valid.
400	IDEMPOTENCY_KEY_REQUIRED	POST and PATCH requests need an Idempotency-Key header.
422	IDEMPOTENCY_KEY_REUSED	That Idempotency-Key was already used with a different request.
409	IDEMPOTENCY_KEY_IN_USE	A request with that Idempotency-Key is still running. Retry shortly.
413	PAYLOAD_TOO_LARGE	The request body is larger than 1 MB.
504	TIMEOUT	The request took too long to finish. It may still have taken effect: look it up before sending it again with a new Idempotency-Key. What it made is found with GET /api/v1/eligibility?request_id=<this request_id>, and the same filter on /api/v1/claims and /api/v1/attachments (a key with read permission).
503	CLAIMS_UNAVAILABLE	Claims are not available in live mode yet. Use a test key.
409	CONFLICT	The resource is not in a state that allows this, or it changed while the request was handled. Read it, then decide whether to send the request again.
500	INTERNAL	Something went wrong on our side. Quote the request ID if you contact us.

Example

Example request

Shell

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

Example response: 200

JSON

{
  "id": "clm_01JM000000E00800000000002G",
  "object": "claim",
  "kind": "claim",
  "state": "reconciled",
  "next_step": "The payment is posted. Nothing is needed unless the payer changes or reverses it.",
  "frequency": "original",
  "parent_id": null,
  "patient_control_number": "CH4Q7M2K9TRB",
  "office": {
    "id": "off_01JM000000E008000000000003",
    "name": "Example Family Dental"
  },
  "payer": {
    "id": "pyr_01JM000000E008000000000004",
    "payer_id": "00000",
    "name": "Example Dental Plan"
  },
  "rendering_provider": {
    "id": "prv_01JM000000E008000000000005",
    "first_name": "Riley",
    "last_name": "Example",
    "npi": "1999990017"
  },
  "patient_name": {
    "first_name": "Alex",
    "last_name": "Example"
  },
  "service_dates": {
    "first": "2026-09-24",
    "last": "2026-09-24"
  },
  "totals": {
    "charge": "1140.00",
    "lines": 1
  },
  "payment": {
    "outcome": "paid",
    "era_id": "era_01JM000000E00800000000003G",
    "paid": "820.80",
    "allowed": "1026.00",
    "patient_responsibility": "205.20",
    "payment_date": "2026-09-24",
    "reconciled_at": "2026-09-25T09:00:00.000000+00:00"
  },
  "estimate": null,
  "converted_from": null,
  "converted_to": null,
  "patient_id": "pat_01JM000000E00800000000004K",
  "request_id": "req_01JM000000E00800000000002J",
  "created_at": "2026-09-24T21:00:00.120000+00:00",
  "updated_at": "2026-09-24T21:00:00.310000+00:00",
  "subscriber": {
    "first_name": "Alex",
    "last_name": "Example",
    "date_of_birth": "1985-04-12",
    "gender": "F",
    "member_id": "CH-ACTIVE-FULL",
    "group_number": null,
    "address": {
      "line1": "1 Example Street",
      "line2": null,
      "city": "Exampleville",
      "state": "GA",
      "postal_code": "30000"
    }
  },
  "patient": null,
  "place_of_service": "11",
  "lines": [
    {
      "line_number": 1,
      "cdt": "D2740",
      "description": "Porcelain or ceramic crown",
      "service_date": "2026-09-24",
      "fee": "1140.00",
      "quantity": 1,
      "tooth": "3",
      "surfaces": null,
      "area": null
    }
  ],
  "remarks": null,
  "metadata": {
    "pms_claim_number": "PMS-1042"
  },
  "attachments": [
    "att_01JM000000E00800000000003G"
  ],
  "validation": {
    "validated_at": "2026-09-24T21:00:00.300000+00:00",
    "errors": 0,
    "warnings": 0,
    "findings": []
  },
  "network": {
    "submitted_at": "2026-09-24T21:00:30.000000+00:00",
    "clearinghouse_claim_id": "SBXEXAMPLE1042",
    "payer_claim_number": "990000001042",
    "rejection": null
  },
  "idempotency_key": "pms-1042"
}