Create File | Truemed

curl -X POST https://dev-api.truemed.com/api/v1/files/create \
     -H "x-truemed-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "content_type": "application/pdf",
  "filename": "receipt.pdf",
  "purpose": "dispute_evidence",
  "size_bytes": 248193
}'

{
  "expires_at": "2026-07-23T19:40:00Z",
  "file_id": "01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e",
  "upload_fields": {
    "Content-Type": "application/pdf",
    "key": "dev/dispute_evidence/9c1f2e3a-4b5c-6d7e-8f90-1a2b3c4d5e6f/2026-07-23/01920a7e-9c3f-7b21-8e4a-2f6b1d0c5a9e_receipt.pdf",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNy0yM1QxOTo0MDowMFoifQ==",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "AKIAIOSFODNN7EXAMPLE/20260723/us-east-1/s3/aws4_request",
    "x-amz-date": "20260723T193000Z",
    "x-amz-signature": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b"
  },
  "upload_url": "https://dev-dispute-evidence.s3.amazonaws.com/"
}

Creates a file record and returns a presigned upload URL plus the form fields to include in the multipart POST.

Upload the file directly to the returned URL, then reference it by file_id from other resources. The upload URL expires 10 minutes after creation, so request it as part of the same flow that performs the upload.

Each purpose enforces its own MIME allowlist and maximum file size, validated before the presigned URL is issued — a content_type or size_bytes outside the purpose’s limits is rejected with a 400.

Purpose	Allowed content types	Max file size
`dispute_evidence`	`application/pdf`, `image/png`, `image/jpeg`, `image/tiff`	5 MB

Creates a file record and returns a presigned upload URL plus the form fields to include in the multipart POST. Upload the file directly to the returned URL, then reference it by `file_id` from other resources. The upload URL expires 10 minutes after creation, so request it as part of the same flow that performs the upload. Each `purpose` enforces its own MIME allowlist and maximum file size, validated before the presigned URL is issued — a `content_type` or `size_bytes` outside the purpose's limits is rejected with a 400. | Purpose | Allowed content types | Max file size | | --- | --- | --- | | `dispute_evidence` | `application/pdf`, `image/png`, `image/jpeg`, `image/tiff` | 5 MB |

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Request

Request body for FileCreateRequest

content_typestringRequired

The file’s MIME type, e.g. application/pdf. Must be allowed for the given purpose.

filenamestringRequired<=255 characters

The original filename, e.g. receipt.pdf.

purposeenumRequired

The business domain the file is for (e.g. dispute_evidence).

size_bytesintegerRequired

The file size in bytes. Must be within the per-purpose maximum.

Response

Successful response

expires_atdatetime

When the presigned upload URL expires (10 minutes after creation).

file_idstring

The public file identifier. Reference this id from other resources.

upload_fieldsmap from strings to strings

Form fields to include in the multipart upload POST, before the file part.

upload_urlstring

Presigned URL to POST the file to (multipart/form-data).

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error