Attachments
Close an attachment
POST/api/v1/attachments/{id}/close
Sends the attachment to the attachment network and closes it: it needs a document or a narrative, its office is registered with the network first when it is not, and its payer must take attachments. The answer has its number and, in claim_file, what a claim carrying it writes in PWK and NTE: put it on the claim with the claim's attachments field. Nothing changes after closing. Closing a closed attachment returns it as it is. If the network does not finish (502), nothing is lost: close it again and it continues. A close already running answers 409. Needs an Idempotency-Key header and a key with the submit permission. Send an empty JSON object as the body.
Needs a key with submit permission.
Request
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
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | required | An attachment ID (att_...). |
Response
The attachment, closed. Status 200.
| Name | Type | Description |
|---|---|---|
| id | string | An ID that starts with att_. |
| object | string | Always `attachment`. |
| state | string | open while documents can be added; closed once sent, with its number. Nothing changes after closing.One of: `open`, `closed`. |
| kind | string | unsolicited (sent with a claim); solicited (answering a payer request: never on a claim file).One of: `unsolicited`, `solicited`. |
| claim_id | string or null | The claim it was made for, if any. Which claims carry it is the claim's attachments field. |
| office_id | string | An ID that starts with off_. |
| payer | object | |
| payer.id | string | An ID that starts with pyr_. |
| payer.payer_id | string | The payer's own payer ID. |
| payer.name | string | |
| payer_request_id | string or null | An ID that starts with prq_. |
| payer_reference | value | The payer's reference number, for a solicited attachment. |
| narrative | string | What the documents show, in words: at most 2000 characters. |
| documents | array of object | |
| documents[].id | string | An ID that starts with doc_. |
| documents[].object | string | Always `attachment_document`. |
| documents[].document_type | string | The document type code (GET /attachments/document_types). |
| documents[].medium | string | film (an X-ray or a photo: has an image date and an orientation) or paper.One of: `film`, `paper`. |
| documents[].image_date | string (date) or null | |
| documents[].orientation | string or null | One of: `left`, `right`. |
| 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. |
| 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`. |
| 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. |
| documents[].md5 | string | The MD5 of the stored image (the JPEG), lower-case hex. |
| documents[].sent_to_network | boolean | True once the document has been sent to the attachment network (closing sends it). |
| documents[].created_at | string (date-time) | |
| attachment_number | value | The number the attachment network gave when it closed; null while open. |
| claim_file | object or null | How a claim carrying it refers to it; null while open. |
| claim_file.pwk | string | What the claim file carries in PWK06 (loop 2300). |
| claim_file.nte | string | The note the claim file carries for it (NTE, loop 2300). |
| request_id | string or null | The API request that made it; null for one made in the dashboard. |
| created_at | string (date-time) | |
| updated_at | string (date-time) | |
| closed_at | string (date-time) or null |
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
curl -X POST "https://sandbox.myclaimhouse.com/api/v1/attachments/att_01JM000000E00800000000003G/close" \
-H "Authorization: Bearer $CLAIMHOUSE_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{}'Example response: 200
{
"id": "att_01JM000000E00800000000003G",
"object": "attachment",
"state": "closed",
"kind": "unsolicited",
"claim_id": "clm_01JM000000E00800000000002G",
"office_id": "off_01JM000000E008000000000003",
"payer": {
"id": "pyr_01JM000000E008000000000004",
"payer_id": "00000",
"name": "Example Dental Plan"
},
"payer_request_id": null,
"payer_reference": null,
"narrative": "Fractured distal cusp on tooth 3, shown on the bitewing.",
"documents": [
{
"id": "doc_01JM000000E00800000000003H",
"object": "attachment_document",
"document_type": "bitewing_xray",
"medium": "film",
"image_date": "2026-09-24",
"orientation": "right",
"file_name": "bitewing-right.jpg",
"converted_from": null,
"size": 184211,
"md5": "3f2a9c1e5b7d4f60a8c2e1d3b5f7a9c0",
"sent_to_network": true,
"created_at": "2026-09-24T20:57:20.000000+00:00"
},
{
"id": "doc_01JM000000E00800000000003J",
"object": "attachment_document",
"document_type": "narrative",
"medium": "paper",
"image_date": null,
"orientation": null,
"file_name": "narrative.png",
"converted_from": "png",
"size": 92480,
"md5": "7d1e3c5a9b2f4d6e8a0c1b3d5f7e9a2b",
"sent_to_network": true,
"created_at": "2026-09-24T20:57:20.000000+00:00"
}
],
"attachment_number": "100001042",
"claim_file": {
"pwk": "NEA100001042",
"nte": "NEA#100001042"
},
"request_id": "req_01JM000000E00800000000003K",
"created_at": "2026-09-24T20:57:00.000000+00:00",
"updated_at": "2026-09-24T20:58:10.000000+00:00",
"closed_at": "2026-09-24T20:58:10.000000+00:00"
}