Attachments

POST/api/v1/attachments/{id}/documents

Adds an image to an open attachment, as multipart/form-data: the JPEG or PNG in the field "file", and its document type (and, for an X-ray or a photo, its date and orientation). A PNG is converted to a JPEG at upload (transparency on white; its header is checked before it is decoded. A PNG may have sides of at most 20,000 pixels and at most 20 megapixels in all (160 MB once decoded), or 4 megapixels if it is interlaced, and may not be animated. One PNG is converted at a time per server, and one that waits too long is answered 429 TOO_MANY_REQUESTS), and the document says converted_from: "png". PDF and every other format are refused (export a PDF page as an image first). The image is checked and rewritten before it is stored: metadata (EXIF with its GPS and device data, the EXIF orientation flag, thumbnails, XMP, color profiles, PNG text), comments and anything after the image are removed, so rotate a photo before uploading it. The size and MD5 are those of the stored JPEG. An attachment holds at most 127 documents and 15 MB of images in all. The same image uploaded again (a retry, or the same file chosen twice) is answered with the document the attachment has already: an attachment never holds one image twice. The body may be up to 15 MB and 64 KiB for the form's own parts; one declared larger is refused before it is read, one streamed without a length is read up to that and refused. At most 2 uploads of one key are taken at once, and each server instance processes at most 6 that have arrived: another is answered 429 TOO_MANY_REQUESTS (send it again when one has finished). A body that stops arriving for 15 seconds is answered 408 REQUEST_TIMEOUT. Needs an Idempotency-Key header and a key with the submit permission.

Needs a key with submit permission.

Request

Headers

Path parameters

Body

Response

The attachment, with the document. Status 201.

Errors

Example

Example request

curl -X POST "https://sandbox.myclaimhouse.com/api/v1/attachments/att_01JM000000E00800000000003G/documents" \
  -H "Authorization: Bearer $CLAIMHOUSE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F '[email protected];type=image/jpeg' \
  -F 'document_type=bitewing_xray' \
  -F 'image_date=2026-09-24' \
  -F 'orientation=right'

Example response: 201

{
  "id": "att_01JM000000E00800000000003G",
  "object": "attachment",
  "state": "open",
  "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": false,
      "created_at": "2026-09-24T20:57:20.000000+00:00"
    }
  ],
  "attachment_number": null,
  "claim_file": null,
  "request_id": "req_01JM000000E00800000000003K",
  "created_at": "2026-09-24T20:57:00.000000+00:00",
  "updated_at": "2026-09-24T20:57:00.000000+00:00",
  "closed_at": null
}