Claims

Create a claim

POST/api/v1/claims

Makes a dental claim from JSON. With submit true (the default) it is validated at once and, when it has no errors, queued for the next batch; with submit false it is saved as a draft. A claim with errors is still made: it comes back with state needs_attention and its findings (validation.findings), with 201 like any other. A body that is not a claim, or that names an office, provider or payer that does not exist, is refused with 422 and nothing is stored. With kind predetermination it makes a predetermination: the same body with no service dates (a date on a line is a SERVICE_DATE_NOT_ALLOWED error); in test mode the sandbox answers one it accepts with its estimate two minutes after the 277. In test mode the sandbox network answers each file with a 997 after 30 seconds and a 277 after 60; the subscriber's member ID picks a scenario (CH-REJECT-A7, CH-REJECT-A3, CH-997-REJECT, CH-ATTACH-REQUIRED, CH-SOLICITED, CH-PAID-ERA, CH-DENIED). In test mode, a claim with the member ID CH-ATTACH-REQUIRED needs a closed attachment before it can be sent. 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}$`.

Body

Body
Name	Type	Required	Description
kind	string	optional	claim (the default): treatment done. predetermination: sent before treatment to ask what the payer would pay; it has no service dates and comes back with an estimate. Set when the claim is made; it never changes.One of: `claim`, `predetermination`.
office_id	string	required	The office that bills the claim (off_...).
payer_id	string	required	The payer (a Claim House payer ID, pyr_..., a payer ID or an alias from the payer directory).
rendering_provider_id	string	required	The dentist who did the treatment (prv_...).
subscriber	object	required	The person who holds the coverage. Also the patient unless patient is given.
subscriber.first_name	string	required
subscriber.last_name	string	required
subscriber.date_of_birth	value	optional
subscriber.gender	string or null	optional	One of: `F`, `M`, `U`.
subscriber.member_id	string	required
subscriber.group_number	value	optional
subscriber.address	object or null	optional
subscriber.address.line1	string	required
subscriber.address.line2	value	optional
subscriber.address.city	string	required
subscriber.address.state	string	required
subscriber.address.postal_code	string	required
patient	object or null	optional	The patient, when not the subscriber.
patient.first_name	string	required
patient.last_name	string	required
patient.date_of_birth	value	optional
patient.gender	string or null	optional	One of: `F`, `M`, `U`.
patient.relationship	string	required	One of: `spouse`, `child`, `other`.
patient.address	object or null	optional
patient.address.line1	string	required
patient.address.line2	value	optional
patient.address.city	string	required
patient.address.state	string	required
patient.address.postal_code	string	required
place_of_service	string	optional	The place of service code. Default 11 (office).
lines	array of object	required	The procedures, one line each. At least one for a claim to be sent.At most 100 items.
lines[].cdt	string	required
lines[].description	value	optional
lines[].service_date	value	optional
lines[].fee	number	optional
lines[].quantity	integer	optional	At least 0.At most 99999.
lines[].tooth	value	optional
lines[].surfaces	value	optional
lines[].area	value	optional
total	value	optional	The total the claim comes to, in dollars: checked against the lines.
remarks	value	optional	Notes for the payer: up to 5 notes of 80 characters, split between words (about 370 characters of ordinary text); a remark that does not fit is a TOO_LONG finding.
metadata	object	optional	Up to 20 pairs of your own, returned with the claim and never sent to the payer.
patient_control_number	value	optional	Your identifier for the claim, sent on the claim and returned on its status: unique in your organization. Made for you when omitted.
attachments	array of string	optional	The attachments the claim carries (att_...), at most 5: of your organization and mode, for the claim's payer, unsolicited and on no other claim. Each must be closed before the claim is sent (ATTACHMENT_OPEN); the claim file carries a PWK and a note for each.At most 5 items.
submit	boolean	optional	true (the default): validate the claim and queue it when it has no errors. false: save it as a draft.

Response

The claim, as it is now: queued, validated, a draft, or needing attention. Status 201.

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.
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" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "office_id": "off_01JM000000E008000000000003",
  "payer_id": "pyr_01JM000000E008000000000004",
  "rendering_provider_id": "prv_01JM000000E008000000000005",
  "subscriber": {
    "first_name": "Alex",
    "last_name": "Example",
    "date_of_birth": "1985-04-12",
    "gender": "F",
    "member_id": "CH-ACTIVE-FULL",
    "address": {
      "line1": "1 Example Street",
      "city": "Exampleville",
      "state": "GA",
      "postal_code": "30000"
    }
  },
  "lines": [
    {
      "cdt": "D2740",
      "fee": 1140,
      "service_date": "2026-09-24",
      "tooth": "3"
    }
  ],
  "metadata": {
    "pms_claim_number": "PMS-1042"
  },
  "attachments": [
    "att_01JM000000E00800000000003G"
  ]
}'

Example response: 201

JSON

{
  "id": "clm_01JM000000E00800000000002G",
  "object": "claim",
  "kind": "claim",
  "state": "queued",
  "next_step": "This claim is queued and goes out in the next batch.",
  "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": null,
  "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": null,
    "clearinghouse_claim_id": null,
    "payer_claim_number": null,
    "rejection": null
  },
  "idempotency_key": "pms-1042"
}