Patients

Search patients

POST/api/v1/patients/search

Finds patients by the words of their name, their date of birth or a member ID on any of their checks or claims (all that are given must match), inside the list's filters, newest first. A search is sent as a POST so that what you search for travels in the body, never in an address or a log; it needs a key with read and no Idempotency-Key. Two different people with the same name and date of birth share one record. A person with no date of birth, or with a name that has no letters or digits to compare (written in another script), is linked to no record.

Needs a key with read permission.

Request

Body

Body
Name	Type	Required	Description
name	string	optional	Words of the patient's name, in any order and case; each must be in the family or given name (accents and punctuation ignored).
date_of_birth	string (date)	optional	The patient's date of birth (YYYY-MM-DD).
member_id	string	optional	A member ID on any of the patient's checks or claims, in any case.
office_id	string	optional	Only the patients last seen at this office (off_...).
coverage	string	optional	verified: the newest completed check was answered by the payer in the last 30 days; unverified: not that; inactive: that answer says the coverage is inactive.One of: `verified`, `unverified`, `inactive`.
limit	integer	optional	How many patients to return, from 1 to 100. Default 25.At least 1.At most 100.
cursor	string	optional	The next_cursor of the previous answer, to get the patients after it.

Response

A page of the patients found. Status 200.

Response fields
Name	Type	Description
data	array of object
data[].id	string	An ID that starts with pat_.
data[].object	string	Always `patient`.
data[].first_name	string	As first seen on a check or claim.
data[].last_name	string	As first seen on a check or claim.
data[].date_of_birth	string (date)
data[].office_id	string or null	Office, primary insurance and member ID are those of the newest completed check or claim.
data[].primary_insurance	object or null	The payer of the newest completed check or claim.
data[].primary_insurance.id	string	An ID that starts with pyr_.
data[].primary_insurance.payer_id	string	The payer's own payer ID.
data[].primary_insurance.name	string
data[].member_id	value	The member ID of the newest completed check or claim.
data[].coverage	object or null	Coverage as last verified: the result of the newest completed check, in the Eligibility screen's words, with its date. Verified: the payer answered that check in the last 30 days. Inactive: that answer says the coverage is inactive. Null when no check of the patient has completed.
data[].coverage.check_id	string	An ID that starts with elg_.
data[].coverage.checked_at	string (date-time)
data[].coverage.outcome	string	One of: `answered`, `rejected`, `payer_unavailable`, `error`.
data[].coverage.status	string or null	One of: `active`, `inactive`, `unknown`.
data[].coverage.label	string	The result in words, as the Eligibility screen says it.
data[].coverage.verified	boolean	True when the payer answered this check in the last 30 days.
data[].open_claims	integer	Open claims: the patient's claims not paid, denied, reconciled or voided (drafts included; predeterminations and void transactions are not claims here).At least -9007199254740991.
data[].open_charges	object	Open charges: the charges of the open claims, plus what the patient owes on the paid, denied and reconciled ones, where the payer's remittance says.
data[].open_charges.total	string	An amount in dollars, as a decimal string with two places (such as "113.60").Matches `^-?\d+\.\d{2}$`.
data[].open_charges.claims	string	The charges of the open claims.Matches `^-?\d+\.\d{2}$`.
data[].open_charges.patient_owes	string	What the patient owes on the paid, denied and reconciled claims, where known.Matches `^-?\d+\.\d{2}$`.
data[].created_at	string (date-time)	When Claim House first saw the patient.
next_cursor	value	Pass as cursor to get the next page; null when there is no next page.

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.
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).
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/patients/search" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "alex example",
  "date_of_birth": "1985-04-12"
}'

Example response: 200

JSON

{
  "data": [
    {
      "id": "pat_01JM000000E00800000000004K",
      "object": "patient",
      "first_name": "Alex",
      "last_name": "Example",
      "date_of_birth": "1985-04-12",
      "office_id": "off_01JM000000E008000000000003",
      "primary_insurance": {
        "id": "pyr_01JM000000E008000000000004",
        "payer_id": "00000",
        "name": "Example Dental Plan"
      },
      "member_id": "CH-ACTIVE-FULL",
      "coverage": {
        "check_id": "elg_01JM000000E00800000000000G",
        "checked_at": "2026-09-24T20:55:00.430000+00:00",
        "outcome": "answered",
        "status": "active",
        "label": "Active",
        "verified": true
      },
      "open_claims": 0,
      "open_charges": {
        "total": "205.20",
        "claims": "0.00",
        "patient_owes": "205.20"
      },
      "created_at": "2026-03-10T15:30:00.430000+00:00"
    }
  ],
  "next_cursor": null
}

A body with nothing to look for: 422

JSON

{
  "error": "INVALID_REQUEST",
  "message": "The request is not valid.",
  "errors": [
    {
      "field": "name",
      "code": "required",
      "message": "Give a name, a date of birth or a member ID to search for."
    }
  ],
  "request_id": "req_01JM000000E008000000000010"
}