Payer requests

Record a payer request

POST/api/v1/payer_requests

Records a request that came by letter or phone, about a claim (its payer) or with a payer of its own. The same payer and reference number again returns the first. 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
claim_id	string	optional	The claim the request is about.
payer_id	string	optional	The payer that asks (pyr_..., a payer ID or an alias). Default: the claim's payer.
reference_number	string	required	The payer's reference number, from its letter: at most 30 characters (letters, digits, spaces and ! " & ' ( ) + , - . / ; ? =).
requested	string	required	What the payer asks for, in its words.
due_date	string (date)	optional

Response

The payer request. Status 201.

Response fields
Name	Type	Description
id	string	An ID that starts with prq_.
object	string	Always `payer_request`.
state	string	One of: `open`, `answered`.
source	string	network (it arrived through the network) or staff (recorded by hand, from a letter).One of: `network`, `staff`.
claim_id	string or null	An ID that starts with clm_.
payer	object
payer.id	string	An ID that starts with pyr_.
payer.payer_id	string	The payer's own payer ID.
payer.name	string
reference_number	string	The payer's reference number: the answering attachment carries it.
requested	string	What the payer asks for, in its words.
due_date	string (date) or null
answering_attachment_id	string or null	An ID that starts with att_.
answered_at	string (date-time) or null
created_at	string (date-time)

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	ATTACHMENTS_UNAVAILABLE	Attachments 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/payer_requests" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "claim_id": "clm_01JM000000E00800000000002G",
  "reference_number": "LETTER-0915",
  "requested": "The perio chart for the scaling.",
  "due_date": "2026-10-15"
}'

Example response: 201

JSON

{
  "id": "prq_01JM000000E008000000000040",
  "object": "payer_request",
  "state": "open",
  "source": "staff",
  "claim_id": "clm_01JM000000E00800000000002G",
  "payer": {
    "id": "pyr_01JM000000E008000000000004",
    "payer_id": "00000",
    "name": "Example Dental Plan"
  },
  "reference_number": "LETTER-0915",
  "requested": "The perio chart for the scaling.",
  "due_date": "2026-10-15",
  "answering_attachment_id": null,
  "answered_at": null,
  "created_at": "2026-09-25T21:02:30.000000+00:00"
}