Retrieve a file

GET/api/v1/files/{id}

GET /files/{id}

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

Response · 200

{
  "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"
}

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.

Parameters1 field

Field	Type	Description
`id`required	string · path	—

Response · 200 fields12 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`purpose`required	enumsms_opt_in_evidence \| sms_document \| image	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).
`status`required	enumawaiting_upload \| ready \| failed	`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).
`filename`required	string	—
`content_type`required	string	The type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared.
`size_bytes`required	integer	—
`sha256`required	string \| null	The hex SHA-256 of the bytes once `ready`.
`failure_reason`required	string \| null	—
`upload`required	object \| null	An upload session's PUT, in the create response only (null otherwise).
`created_at`required	string	—
`expires_at`required	string	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.

200401403404422

Retrieve a file

Retrieve a file

Search docs and guides