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

# Document file rules

> Filename characters, size limits, accepted types, and upload error codes for End User Onboarding

Before storing a document, the
[Upload a document for an application](https://developers.circle.com/api-reference/circle-mint/onboarding/upload-document#upload-a-document-for-an-application)
endpoint validates the filename and file bytes. A failed check returns `400`
with an `errors` array that names the failing field and error code.

For upload steps, see
[Upload documents](/end-user-onboarding/howtos/upload-documents).

## Read limits from the schema

Each file field can set its own types and size. Retrieve the application schema
(`GET /v1/onboarding/partner/applications/{applicationId}/schema`) and read
`x-fileUpload` on the target field:

```json theme={null}
"genericFileUploadBusinessRegistration": {
  "x-fileUpload": {
    "acceptedTypes": ["application/pdf", "image/jpeg", "image/png"],
    "maxSizeMb": 10
  }
}
```

If `x-fileUpload` is absent, the API uses the defaults in the following tables.

## Filename

The API strips `/` and `\` from `fileName`, then trims spaces at each end.

| Rule       | Value                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| Length     | 1 to 255 characters after path components are removed                                                        |
| Characters | Letters, numbers, spaces, hyphens (`-`), underscores (`_`), dots (`.`), commas (`,`), and parentheses (`()`) |
| Example    | `Ownership Chart (1).pdf`, `Company, LLC.pdf`                                                                |

Quotes, slashes, and other punctuation fail the character check.

## File type

The API reads magic bytes in `fileContent`. It doesn't trust the `Content-Type`
header.

Known signatures are PDF, JPEG, PNG, ZIP (Office Open XML), and OLE2 (legacy
Office). A file with no matching signature returns `unrecognized_type`.

| Source                             | Accepted types                               |
| ---------------------------------- | -------------------------------------------- |
| Field `x-fileUpload.acceptedTypes` | The types listed on that field               |
| No `x-fileUpload`                  | `application/pdf`, `image/jpeg`, `image/png` |

Office files (DOC, XLS, DOCX, XLSX) pass only when the field schema lists those
types. The default list doesn't include them.

## File size

| Source                         | Limit                   |
| ------------------------------ | ----------------------- |
| Field `x-fileUpload.maxSizeMb` | That value in megabytes |
| No `x-fileUpload`              | 10 MB                   |

A file over the limit returns `too_large`.

## Error codes

A failed check returns HTTP `400` with numeric code `181102`. The body includes
`errors` with `field` and `code`.

| `field`       | `code`               | When                                                         |
| ------------- | -------------------- | ------------------------------------------------------------ |
| `fileName`    | `required`           | `fileName` is missing or blank                               |
| `fileName`    | `too_long`           | Name is longer than 255 characters                           |
| `fileName`    | `invalid`            | Name is empty after path components are removed              |
| `fileName`    | `invalid_characters` | Name has a character outside the allowlist                   |
| `fileContent` | `required`           | `fileContent` is missing                                     |
| `fileContent` | `empty`              | File has zero bytes                                          |
| `fileContent` | `unrecognized_type`  | File bytes don't match a known type                          |
| `fileContent` | `not_accepted`       | Type isn't in the field's `x-fileUpload.acceptedTypes`       |
| `fileContent` | `too_large`          | File is larger than `x-fileUpload.maxSizeMb` (default 10 MB) |