---
title: "Upload"
description: "Store PDF, DOCX, or PNG files in SignatureAPI and reference them as document sources in envelopes."
canonical: "https://signatureapi.com/docs/api/resources/uploads/object"
source: "https://signatureapi.com/docs/api/resources/uploads/object.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Upload

Store PDF, DOCX, or PNG files in SignatureAPI and reference them as document sources in envelopes.

_Last verified against API version 1.18.0._

An upload is a file stored in SignatureAPI. You can use an upload as the source file for a document in an envelope. Uploads are the simplest way to supply document files when you do not want to host them yourself.

After uploading a file, pass the returned `url` value as the `url` property of a [document](https://signatureapi.com/docs/api/resources/documents/object).

The following file formats are supported:

| Format | Media Type                                                                |
| ------ | ------------------------------------------------------------------------- |
| PDF    | `application/pdf`                                                         |
| DOCX   | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| PNG    | `image/png`                                                               |

## Retention

Uploads have one of two retention types, indicated by the `retention` property:

| Retention | Description                                                                                                                                                                                                                                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Temporary | Created through the API. Automatically deleted 24 hours after creation. Use this for one-time document sends.                                                                                                                                                                                         |
| Permanent | Stored indefinitely and reusable across multiple envelopes. Identified by a unique `key`. Created by [storing an upload](https://signatureapi.com/docs/api/resources/uploads/store) through the API or uploading through the [Library](https://dashboard.signatureapi.com/library) in your dashboard. |

**An API upload is temporary until you store it. A temporary upload, a permanent upload or a Library file can each be a document's url.**

Parts:

- **Your PDF or DOCX**: A file on your server, at most 4.5 MB.
- **Temporary upload**: Deleted 24 hours after creation. Its url works as a document url until then.
- **Permanent upload**: Has a unique key and never expires. Library files are permanent uploads too.
- **Envelope document**: Set the document's url to the upload's url.

Connections:

- Your PDF or DOCX to Temporary upload: Create Upload
- Temporary upload to Permanent upload: Store Upload
- Permanent upload to Envelope document: url

To see the pages, placeholders and template fields SignatureAPI finds in an uploaded PDF or DOCX, call [Retrieve upload structure](https://signatureapi.com/docs/api/resources/uploads/structure).

> **Info:** The Upload resource replaces the [File resource](https://signatureapi.com/docs/api/resources/files/object). The File resource is soft-deprecated but remains available for backward compatibility.

## Attributes

#### `id` (string, required)

The unique identifier of the upload.

#### `retention` (enum, required)

The retention type of the upload.

| Value       | Description                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `temporary` | The file is automatically deleted 24 hours after creation.                                                                                                   |
| `permanent` | The file is stored indefinitely. Created by [storing an upload](https://signatureapi.com/docs/api/resources/uploads/store) or through the dashboard library. |

#### `key` (string)

A unique identifier for the upload within your account. Present only on permanent uploads (`retention` is `permanent`).

Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters.

#### `url` (string, required)

The internal URL used to reference this upload in other API calls, such as `document.url`.

You cannot use this URL to download the file directly.

#### `format` (enum, required)

The file format of the upload.

| Value  | Description                                                                              |
| ------ | ---------------------------------------------------------------------------------------- |
| `pdf`  | A PDF file (`application/pdf`).                                                          |
| `docx` | A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`). |
| `png`  | A PNG image (`image/png`).                                                               |

#### `sha_256` (string, required)

The SHA-256 hash of the uploaded file, in hexadecimal format.

#### `size` (integer, required)

The size of the uploaded file in bytes. Maximum file size: 4.5 MB.

#### `created_at` (string, required)

The date and time when the upload was created, in ISO 8601 format.

#### `expires_at` (string)

The date and time when the upload will be automatically deleted, in ISO 8601 format. Present only on temporary uploads (`retention` is `temporary`). The expiration is 24 hours after creation.

### Example: Temporary upload

Response 200 OK:

```json
{
  "id": "upl_3JJz6t1o8A5YjX5VpnX27Z",
  "retention": "temporary",
  "url": "https://api.signatureapi.com/v1/uploads/upl_3JJz6t1o8A5YjX5VpnX27Z",
  "sha_256": "4f1c8a7e92b3d05a6e8c1f4b7d2a9053c6e8b1d4f7a20935c8e1b4d7a0f36c92",
  "size": 102400,
  "format": "pdf",
  "created_at": "2026-11-02T14:00:00.000Z",
  "expires_at": "2026-11-03T14:00:00.000Z"
}
```

### Example: Permanent upload

Response 200 OK:

```json
{
  "id": "upl_1sAAaVfabdt0esVjmSTmLA",
  "retention": "permanent",
  "key": "offer-letter-template",
  "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
  "sha_256": "a8d3f06b19c2e4750d6b8a1f3c9e27d45b0a6f8e1c3d92b7405e6a8f1d3c7b09",
  "size": 234567,
  "format": "docx",
  "created_at": "2026-11-02T14:00:00.000Z"
}
```
