> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlemma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload file

> Upload a document and receive a file ID for use with other endpoints.

Uploads a file to Lemma and returns a file object. You can reference the returned `id` when creating resources that accept a `file_id`, such as the [Upload EOB](/api-reference/upload-eob) endpoint.

Send the request as `multipart/form-data`. The maximum file size is 10 MB. Accepted file types depend on the `purpose` — see below.

## Request body

<ParamField body="file" type="file" required>
  The file to upload. Maximum size is 10 MB. Accepted MIME types depend on the
  `purpose` field.
</ParamField>

<ParamField body="entity_id" type="string" required>
  The ID of the entity this file belongs to.
</ParamField>

<ParamField body="purpose" type="enum" required>
  The intended use of the file. Determines which file types are accepted.

  | Purpose                   | Accepted types          |
  | ------------------------- | ----------------------- |
  | `explanation_of_benefits` | PDF (`application/pdf`) |
</ParamField>

## Response

Returns the created file object.

<ResponseField name="id" type="string">
  Unique identifier for the file.
</ResponseField>

<ResponseField name="created_at" type="string">
  [ISO 8601](/api-reference/timestamps) timestamp of when the file was uploaded.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity this file belongs to.
</ResponseField>

<ResponseField name="purpose" type="enum">
  The intended use of the file.
</ResponseField>

<ResponseField name="filename" type="string">
  The original name of the uploaded file.
</ResponseField>

<ResponseField name="content_type" type="string">
  The MIME type of the file.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "file_Xt7nRv3hBw9pKm4s",
    "created_at": "2026-03-15T14:30:00Z",
    "entity_id": "entity_k7mXp2vR9nTfBw4s",
    "purpose": "explanation_of_benefits",
    "filename": "eob-march-2026.pdf",
    "content_type": "application/pdf"
  }
  ```

  ```json 413 theme={null}
  {
    "statusCode": 413,
    "error": "Content Too Large",
    "message": "File size exceeds the maximum allowed size of 10 MB."
  }
  ```

  ```json 422 theme={null}
  {
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "Invalid file type for purpose \"explanation_of_benefits\". Accepted types: application/pdf."
  }
  ```
</ResponseExample>