Uploading a document for an existing claim

Sometimes a claim needs evidence attached to it, a photo of the damage, an invoice, anything that helps the carrier review it. This page walks through how to upload one of those documents to an existing claim. Uploading a document is a three-step process: you tell Opereit you’re about to upload a file, you upload the file itself to a link you get back, and then you tell Opereit the upload is done. For the full field-by-field breakdown, see the API reference for Initiate document upload and Confirm document upload.

Before you start

You’ll need:

An API key (see Authentication if you don’t have one yet).
The ID of an existing claim to attach the document to (you get this back when you create a claim, it looks like clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ).
The file itself, in one of the accepted formats: PDF, JPEG, PNG, or WEBP, and no bigger than 10 MB.

Step 1: Tell Opereit you’re about to upload a file

curl -X POST "https://api.opereit.ai/v1/claims/clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ/documents" \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "application/pdf",
    "file_name": "proof-of-damage.pdf"
  }'

This registers the document and hands you back a one-time upload link:

{
  "id": "doc_3Ccox6eQV1YYeg9RIo6qXCwGN4pQ",
  "claim_id": "clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ",
  "name": "proof-of-damage.pdf",
  "type": "pdf",
  "status": "PENDING_UPLOAD",
  "uploaded_by": "external",
  "created_at": "2026-09-14T10:00:00.000Z",
  "organization_id": "org_5f9c1a2b3c4d5e6f",
  "metadata": {
    "upload_url": "https://platform.opereit.ai/object/upload/sign/claim_documents/org_5f9c1a2b3c4d5e6f/clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ/doc_3Ccox6eQV1YYeg9RIo6qXCwGN4pQ.pdf?token=..."
  }
}

Two things worth knowing here:

Hang onto id. You’ll pass it back in step 3 to confirm the upload.
content_type has to be one of application/pdf, image/jpeg, image/png, or image/webp. Anything else gets rejected with a 400 before anything is registered.

Step 2: Upload the file

metadata.upload_url is a link that’s ready to accept the raw file. Upload directly to it with an HTTP PUT:

curl -X PUT "<the upload_url from step 1>" \
  -H "Content-Type: application/pdf" \
  --data-binary @proof-of-damage.pdf

Use the same Content-Type you sent in step 1. There’s nothing to parse from the response here, a successful PUT just means the upload went through.

Step 3: Confirm the upload

Once the file is uploaded, tell Opereit it’s there:

curl -X POST "https://api.opereit.ai/v1/claims/clm_3Ccox6eQUYYeg9RIo6qXCwGN3nQ/documents/complete" \
  -u "your_key_id:your_key_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc_3Ccox6eQV1YYeg9RIo6qXCwGN4pQ"]
  }'

You can confirm up to 10 documents in a single request, just list all their IDs. Opereit checks that each file was actually received, and reports back one result per document:

{
  "attached": 1,
  "documents": [
    { "id": "doc_3Ccox6eQV1YYeg9RIo6qXCwGN4pQ", "status": "confirmed" }
  ]
}

If a document didn’t make it, it shows up with "status": "failed" and a reason instead, rather than silently being left out:

{
  "attached": 1,
  "documents": [
    { "id": "doc_3Ccox6eQV1YYeg9RIo6qXCwGN4pQ", "status": "confirmed" },
    { "id": "doc_9Xa22kdVWYYeg9RIo6qXCwGN8zT", "status": "failed", "reason": "not_found_in_storage" }
  ]
}

attached is just the count of documents with "status": "confirmed", it’s there so you don’t have to count the array yourself if you don’t need the per-document detail.

There’s currently no endpoint to list the documents already attached to a claim. Keep track of the ids you get back from step 1 on your side if you need to reference them again later.

Document statuses

A document moves through exactly two states, tracked in the status field you get back in step 1:

Status	Meaning
`PENDING_UPLOAD`	Registered, but the file hasn’t been uploaded and confirmed yet. This is what you’ll always see right after step 1.
`CONFIRMED`	The file was uploaded and Opereit has verified it’s actually there. This happens once step 3 succeeds for that document.

Confirm results

The status inside each entry of documents[] in step 3’s response is a different, smaller vocabulary, it’s the outcome of that specific confirm attempt, not the document’s lifecycle state:

Status	Meaning
`confirmed`	The file was received, is a valid size, and matches an accepted content type. The document’s status is now `CONFIRMED`.
`failed`	Something went wrong, check the `reason` field for why.

Failure reasons

reason is only present when status is failed.

Reason	What it means
`document_not_found`	No document with that ID exists on this claim. Double-check the ID and that it belongs to the claim in the URL.
`not_found_in_storage`	The file was never actually uploaded to `upload_url`, or step 2 failed silently. Try step 2 again.
`invalid_size`	The uploaded file is missing a readable size, or is bigger than 10 MB.
`unsupported_content_type`	The uploaded file’s content type isn’t one of the accepted types.
`storage_check_failed`	Opereit couldn’t verify whether the file was received. Transient, safe to retry step 3.
`internal_error`	Something went wrong on Opereit’s end while confirming this document. Safe to retry step 3.

Handling errors

Both endpoints use the same error envelope as the rest of the API:

{
  "statusCode": 400,
  "statusReasonCode": "UNSUPPORTED_DOCUMENT_CONTENT_TYPE",
  "error": "Unsupported content type: text/plain. Expected pdf, jpeg, or png."
}

statusReasonCode	Status	What it means
`INVALID_REQUEST_BODY`	400	Something in the request body is missing or malformed, e.g. no `file_name`, or `document_ids` is empty or has more than 10 entries. Check `details.fieldErrors`.
`UNSUPPORTED_DOCUMENT_CONTENT_TYPE`	400	`content_type` (step 1) isn’t one of the accepted MIME types.
`CLAIM_NOT_FOUND`	404	No claim with that ID exists for your organization.
`AUTHENTICATION_REQUIRED` / `INVALID_CREDENTIALS_FORMAT` / `INVALID_CREDENTIALS_ENCODING` / `INVALID_CREDENTIALS`	401	Something’s wrong with your `Authorization` header.
`INTERNAL_ERROR`	500	Something broke on our end. Safe to retry.

A rejected content type on a document you’re actively confirming (step 3) doesn’t come back as one of these top-level errors, it shows up as "status": "failed", "reason": "unsupported_content_type" for that specific document instead, see Failure reasons above.

Getting started

Claim Management

Integrations

Uploading a document for an existing claim

Before you start

Step 1: Tell Opereit you’re about to upload a file

Step 2: Upload the file

Step 3: Confirm the upload

Document statuses

Confirm results

Failure reasons

Handling errors

​Before you start

​Step 1: Tell Opereit you’re about to upload a file

​Step 2: Upload the file

​Step 3: Confirm the upload

​Document statuses

​Confirm results

​Failure reasons

​Handling errors

Before you start

Step 1: Tell Opereit you’re about to upload a file

Step 2: Upload the file

Step 3: Confirm the upload

Document statuses

Confirm results

Failure reasons

Handling errors