Upload Evidence Files

Evidence files — receipts, shipping documentation, screenshots — are uploaded through the Files API and then referenced from a counter by their file_id. Files are uploaded directly to storage with a short-lived presigned URL and are ready to attach to a counter as soon as the upload completes.

The upload flow

1. Request an upload slot

POST /api/v1/files/create reserves a file and returns a presigned upload target. purpose is dispute_evidence.

$
curl -s -X POST "https://dev-api.truemed.com/api/v1/files/create" \
>
  -H "Authorization: Bearer $TRUEMED_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "filename": "receipt.pdf",
>
    "content_type": "application/pdf",
>
    "size_bytes": 482113,
>
    "purpose": "dispute_evidence"
>
  }'

1
{
2
  "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
3
  "upload_url": "https://s3.amazonaws.com/...",
4
  "upload_fields": { "key": "...", "policy": "...", "x-amz-signature": "..." },
5
  "expires_at": "2026-06-29T18:10:00Z"
6
}

The upload_url expires 10 minutes after creation. For dispute_evidence, content_type must be one of application/pdf, image/png, image/jpeg, or image/tiff, and size_bytes must be at most 5 MiB (5,242,880 bytes). A request outside these limits is rejected before an upload slot is issued.

2. Upload the file to storage

POST the file to upload_url as multipart/form-data, including every key from upload_fields before the file part.

$
curl -s -X POST "$UPLOAD_URL" \
>
  -F "key=$KEY" \
>
  -F "policy=$POLICY" \
>
  -F "x-amz-signature=$SIGNATURE" \
>
  -F "file=@receipt.pdf"

3. Read it back (optional) and reference it

The file is ready to attach as soon as the upload completes. GET /api/v1/files/{file_id} returns its metadata and a short-lived (5-minute) presigned download_url if you need to read it back.

$
curl -s "https://dev-api.truemed.com/api/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479" \
>
  -H "Authorization: Bearer $TRUEMED_API_KEY"

Reference the file_id from a counter’s evidence_items (see Respond with Evidence).

Rules to know

• Expiry. Freshly uploaded files have a short orphan lifetime and age out if never used. Submitting a counter is what extends a referenced file’s retention to the post-resolution window — so attach-and-submit, don’t upload-and-forget.