Payer requests

Answer a payer request

POST/api/v1/payer_requests/{id}/answer

Answers with a solicited attachment that carries the payer's reference number: the one named, else the request's open one (make it with POST /attachments, kind solicited, and upload its documents first), else a new one with the narrative given (for a request about no claim, with office_id and the patient, subscriber and service_dates, which the network's record needs). It is sent through the network (as an answer about the claim's earlier attachment when it has one) and closed, and the request is answered. Nothing is added to the claim file. An answered request returns its answer. 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 payer request ID (prq_...).

Body

Body
Name	Type	Required	Description
attachment_id	string	optional	The solicited attachment that answers it (made with payer_request_id, with its documents uploaded). Default: the request's open solicited attachment, or a new one.
office_id	string	optional	The office of a new attachment, for a request about no claim.
narrative	string	optional	The answer in words, kept on the attachment.
patient	object	optional	The patient, for an attachment made for no claim (required then; one made for a claim takes the claim's).
patient.first_name	string	required
patient.last_name	string	required
patient.date_of_birth	string (date)	required
subscriber	object	optional	The insured, for an attachment made for no claim (required then).
subscriber.first_name	string	required
subscriber.last_name	string	required
subscriber.member_id	string	required
subscriber.relationship	string	required	The patient's relationship to the insured.One of: `self`, `spouse`, `child`, `other`.
service_dates	object	optional	The dates of service the documents are about, for an attachment made for no claim (required then).
service_dates.from	string (date)	required
service_dates.to	string (date)	required

Response

The request, answered, and the attachment that answers it. Status 200.

Response fields
Name	Type	Description
object	string	Always `payer_request_answer`.
payer_request	object
payer_request.id	string	An ID that starts with prq_.
payer_request.object	string	Always `payer_request`.
payer_request.state	string	One of: `open`, `answered`.
payer_request.source	string	network (it arrived through the network) or staff (recorded by hand, from a letter).One of: `network`, `staff`.
payer_request.claim_id	string or null	An ID that starts with clm_.
payer_request.payer	object
payer_request.payer.id	string	An ID that starts with pyr_.
payer_request.payer.payer_id	string	The payer's own payer ID.
payer_request.payer.name	string
payer_request.reference_number	string	The payer's reference number: the answering attachment carries it.
payer_request.requested	string	What the payer asks for, in its words.
payer_request.due_date	string (date) or null
payer_request.answering_attachment_id	string or null	An ID that starts with att_.
payer_request.answered_at	string (date-time) or null
payer_request.created_at	string (date-time)
attachment	object
attachment.id	string	An ID that starts with att_.
attachment.object	string	Always `attachment`.
attachment.state	string	open while documents can be added; closed once sent, with its number. Nothing changes after closing.One of: `open`, `closed`.
attachment.kind	string	unsolicited (sent with a claim); solicited (answering a payer request: never on a claim file).One of: `unsolicited`, `solicited`.
attachment.claim_id	string or null	The claim it was made for, if any. Which claims carry it is the claim's attachments field.
attachment.office_id	string	An ID that starts with off_.
attachment.payer	object
attachment.payer.id	string	An ID that starts with pyr_.
attachment.payer.payer_id	string	The payer's own payer ID.
attachment.payer.name	string
attachment.payer_request_id	string or null	An ID that starts with prq_.
attachment.payer_reference	value	The payer's reference number, for a solicited attachment.
attachment.narrative	string	What the documents show, in words: at most 2000 characters.
attachment.documents	array of object
attachment.documents[].id	string	An ID that starts with doc_.
attachment.documents[].object	string	Always `attachment_document`.
attachment.documents[].document_type	string	The document type code (GET /attachments/document_types).
attachment.documents[].medium	string	film (an X-ray or a photo: has an image date and an orientation) or paper.One of: `film`, `paper`.
attachment.documents[].image_date	string (date) or null
attachment.documents[].orientation	string or null	One of: `left`, `right`.
attachment.documents[].file_name	string	The name the file was sent with, for display: the last part of it, without control characters. The stored file is named by the document ID.
attachment.documents[].converted_from	string or null	png when the upload was a PNG, converted to the JPEG that is stored and sent; null when it was a JPEG.One of: `png`.
attachment.documents[].size	integer	The size in bytes of the image as stored and sent: the upload rewritten without its metadata (a PNG converted to a JPEG first).At least -9007199254740991.
attachment.documents[].md5	string	The MD5 of the stored image (the JPEG), lower-case hex.
attachment.documents[].sent_to_network	boolean	True once the document has been sent to the attachment network (closing sends it).
attachment.documents[].created_at	string (date-time)
attachment.attachment_number	value	The number the attachment network gave when it closed; null while open.
attachment.claim_file	object or null	How a claim carrying it refers to it; null while open.
attachment.claim_file.pwk	string	What the claim file carries in PWK06 (loop 2300).
attachment.claim_file.nte	string	The note the claim file carries for it (NTE, loop 2300).
attachment.request_id	string or null	The API request that made it; null for one made in the dashboard.
attachment.created_at	string (date-time)
attachment.updated_at	string (date-time)
attachment.closed_at	string (date-time) or null

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	ATTACHMENTS_UNAVAILABLE	Attachments are not available in live mode yet. Use a test key.
502	ATTACHMENTS_NETWORK_ERROR	The attachment network did not finish. The attachment is still open and nothing was lost: close it again.
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/payer_requests/prq_01JM000000E008000000000040/answer" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "narrative": "The crack is visible on the bitewing sent with the claim."
}'

Example response: 200

JSON

{
  "object": "payer_request_answer",
  "payer_request": {
    "id": "prq_01JM000000E008000000000040",
    "object": "payer_request",
    "state": "answered",
    "source": "network",
    "claim_id": "clm_01JM000000E00800000000002G",
    "payer": {
      "id": "pyr_01JM000000E008000000000004",
      "payer_id": "00000",
      "name": "Example Dental Plan"
    },
    "reference_number": "PRQ000001042",
    "requested": "A narrative of the treatment and a current periapical X-ray of the tooth treated.",
    "due_date": "2026-10-25",
    "answering_attachment_id": "att_01JM000000E008000000000041",
    "answered_at": "2026-09-26T15:00:05.000000+00:00",
    "created_at": "2026-09-25T21:02:30.000000+00:00"
  },
  "attachment": {
    "id": "att_01JM000000E008000000000041",
    "object": "attachment",
    "state": "closed",
    "kind": "solicited",
    "claim_id": "clm_01JM000000E00800000000002G",
    "office_id": "off_01JM000000E008000000000003",
    "payer": {
      "id": "pyr_01JM000000E008000000000004",
      "payer_id": "00000",
      "name": "Example Dental Plan"
    },
    "payer_request_id": "prq_01JM000000E008000000000040",
    "payer_reference": "PRQ000001042",
    "narrative": "The crack is visible on the bitewing sent with the claim.",
    "documents": [],
    "attachment_number": "100001043",
    "claim_file": {
      "pwk": "NEA100001043",
      "nte": "NEA#100001043"
    },
    "request_id": "req_01JM000000E00800000000003K",
    "created_at": "2026-09-26T15:00:00.000000+00:00",
    "updated_at": "2026-09-26T15:00:05.000000+00:00",
    "closed_at": "2026-09-26T15:00:05.000000+00:00"
  }
}