> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Create File

POST https://dev-api.truemed.com/api/v1/files/create
Content-Type: application/json

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 |

Reference: https://developers.truemed.com/api-reference/files/create-file

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Body (application/json)

This endpoint expects a FileCreateRequest.

- `content_type` (string, required) — The file's MIME type, e.g. application/pdf. Must be allowed for the given purpose.
- `filename` (string, required) — The original filename, e.g. receipt.pdf.
- `purpose` (enum, required) — The business domain the file is for (e.g. dispute_evidence).
  - Allowed values: `dispute_evidence`
- `size_bytes` (integer, required) — The file size in bytes. Must be within the per-purpose maximum.

## Response

### 200

Successful response

- `expires_at` (datetime, required) — When the presigned upload URL expires (10 minutes after creation).
- `file_id` (string, required) — The public file identifier. Reference this id from other resources.
- `upload_fields` (map from string to string, required) — Form fields to include in the multipart upload POST, before the file part.
- `upload_url` (string, required) — Presigned URL to POST the file to (multipart/form-data).

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Examples

**Request**

```json
{
  "content_type": "application/pdf",
  "filename": "receipt.pdf",
  "purpose": "dispute_evidence",
  "size_bytes": 248193
}
```

**Response**

```json
{
  "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/"
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/api/v1/files/create"

payload = {
    "content_type": "application/pdf",
    "filename": "receipt.pdf",
    "purpose": "dispute_evidence",
    "size_bytes": 248193
}
headers = {
    "x-truemed-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/files/create';
const options = {
  method: 'POST',
  headers: {'x-truemed-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"content_type":"application/pdf","filename":"receipt.pdf","purpose":"dispute_evidence","size_bytes":248193}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```