> **Source:** https://knowledge.leegality.com/document-execution/api/upload-media
> **Site:** Leegality Knowledge Base — https://knowledge.leegality.com
> **About:** Leegality is a document execution platform covering eSigning, stamps, NeSL, workflows, and REST API integration.
> **Navigation:** Every article on this site has a plain-text version at `<article-url>.txt` (this format). To get an index of all articles with their `.txt` links, read: https://knowledge.leegality.com/llms.txt
> **AI Guide:** For instructions on how to navigate this knowledge base as an AI agent, read: https://knowledge.leegality.com/ai-readable.txt

---
# POST /v4/media/upload — Upload media

:::info[Sandbox endpoint]

**Authentication:** `X-Auth-Token` header required on every request.

## Request URL

```
POST https://app1.leegality.com/api/v4/media/upload
```

**Environments:**
- Production: `https://app1.leegality.com/api/v4/media/upload`
- Sandbox: `https://sandbox.leegality.com/api/v4/media/upload`

---

## Request Body

**Content-Type:** `application/json`

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `fileName` | string | Yes | Name of the file you will upload, including its extension. | `loan-agreement.pdf` |
| `mediaType` | string | Yes | The type of file being uploaded — what it will be used as in the pack.  **Possible values:** - `SUB_DOCUMENT` - `STAMP_UPLOAD` - `REFERENCE_ATTACHMENTS` - `FACE_MATCH_REFERENCE` - `TEMPLATE_FILE_TYPE_FIELD` - `CUSTOM_FIELD_UPLOAD` Allowed: `SUB_DOCUMENT`, `STAMP_UPLOAD`, `REFERENCE_ATTACHMENTS`, `FACE_MATCH_REFERENCE`, `TEMPLATE_FILE_TYPE_FIELD`, `CUSTOM_FIELD_UPLOAD`. | `SUB_DOCUMENT` |

### Sample Request

```json
{
  "fileName": "loan-agreement.pdf",
  "mediaType": "SUB_DOCUMENT"
}
```

---

## Responses

### 200 — Pre-signed upload URL generated. Upload your file to `data.presignedUrl` within 15 minutes, then use `data.mediaId` when creating a pack.

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Result code. `SUCCESS` when the pre-signed URL was generated. | `SUCCESS` |
| `message` | string | No | Human-readable status message. | `Pre-signed URL generated` |
| `data` | MediaUploadResponse | No | See **MediaUploadResponse** below. | — |

#### MediaUploadResponse

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `mediaId` | string | No | Unique ID for the file. Use this value in any `file` field when creating a pack. | `550e8400-e29b-41d4-a716-446655440000` |
| `presignedUrl` | string | No | Pre-signed URL to upload your file to. Valid for **15 minutes**. | `https://uploads.leegality.com/document-infrastructure/media/` |
| `expiresAt` | string | No | When the pre-signed upload URL expires (15 minutes after it is generated). | `2026-08-21T10:45:00Z` |
| `mediaRetentionExpiresAt` | string | No | How long the `mediaId` stays valid (1 day). You can use this `mediaId` when creating a pack until this time. | `2026-08-22T10:30:00Z` |

### Sample Response (200)

```json
{
  "code": "SUCCESS",
  "message": "Pre-signed URL generated",
  "data": {
    "mediaId": "550e8400-e29b-41d4-a716-446655440000",
    "presignedUrl": "https://uploads.leegality.com/document-infrastructure/media/550e8400-e29b-41d4-a716-446655440000?X-Amz-Signature=…",
    "expiresAt": "2026-08-21T10:45:00Z",
    "mediaRetentionExpiresAt": "2026-08-22T10:30:00Z"
  }
}
```