---
title: "Retrieve a file"
description: "One file's metadata (the bytes are never served back). `GET /api/v1/files/{id}`"
url: https://www.unitpost.com/docs/platform/get-files-id
section: "Platform API reference"
updated: 2026-11-11
---
# Retrieve a file

`GET /api/v1/files/{id}`

One file's metadata (the bytes are never served back). For an upload session this checks whether the bytes arrived and pass the purpose's checks: `ready`, `failed` (`failure_reason`), or still `awaiting_upload`. Requires the `sms:manage` or `templates:write` or `branding:write` capability.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | string | yes | — |
| `id` | string | yes | — |
| `purpose` | enum | yes | What the file is for: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB). One of: `sms_opt_in_evidence`, `sms_document`, `image`. |
| `status` | enum | yes | `ready`: checked and usable by `file_id`. `awaiting_upload`: an upload session whose bytes haven't been PUT yet (reading the file checks again). `failed`: the uploaded bytes were refused (`failure_reason` says why). One of: `awaiting_upload`, `ready`, `failed`. |
| `filename` | string | yes | — |
| `content_type` | string | yes | The type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared. |
| `size_bytes` | integer | yes | — |
| `sha256` | string \| null | yes | The hex SHA-256 of the bytes once `ready`. |
| `failure_reason` | string \| null | yes | — |
| `upload` | object \| null | yes | An upload session's PUT, in the create response only (null otherwise). |
| `created_at` | string | yes | — |
| `expires_at` | string | yes | The file is deleted at this time, 24 hours after it was created, whether or not it was used. An operation that used it keeps its own copy. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The file. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | File not found, expired, or of a purpose this credential can't use. |
| 422 | A query key (this operation takes none). |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/files/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "file",
  "id": "id_123",
  "purpose": "sms_opt_in_evidence",
  "status": "awaiting_upload",
  "filename": "string",
  "content_type": "string",
  "size_bytes": 1,
  "sha256": "string",
  "failure_reason": "string",
  "upload": {
    "url": "https://example.com",
    "method": "PUT",
    "headers": {},
    "expires_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z"
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/platform/get-files-id
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json