Claims

Validate a claim

POST/api/v1/claims/validate

Checks a claim body the way creating it would and stores nothing: every finding together, errors (which keep a claim from being sent) and warnings. 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 findings. Status 200.

Response fields
Name	Type	Description
object	string	Always `claim_validation`.
valid	boolean	True when there is no error: the claim would be queued.
errors	integer	At least -9007199254740991.
warnings	integer	At least -9007199254740991.
findings	array of object
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.
findings[].code	string	A stable code for the finding.
findings[].message	string
findings[].severity	string	An error keeps the claim from being sent; a warning does not.One of: `error`, `warning`.

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.
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/validate" \
  -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: 200

JSON

{
  "object": "claim_validation",
  "valid": true,
  "errors": 0,
  "warnings": 0,
  "findings": []
}