Retrieve a file
/files/{file_id}Returns a file's details and status. Poll it after uploading to see when the file is ready.
Selfies are visible only to people who can read attendance, and to whoever uploaded them.
Scope: files:read · Plan: Pro and Enterprise in live mode; every plan in test mode.
Send Authorization: Bearer <token> on every request. The token is one of:
| Prefix | What it is | Where it may be used |
|---|---|---|
agoo_sk_live_ | Secret key, live mode | Your servers only |
agoo_sk_test_ | Secret key, test mode | Your servers only |
agoo_pk_live_ | Publishable key, live mode | Browsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people. |
agoo_pk_test_ | Publishable key, test mode | As above, in test mode |
Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.
In: header
Scope: files:read
Path Parameters
The file's ID.
^file_[0-7][0-9a-hjkmnp-tv-z]{25}$"file_01m4z8vge0fkktt139dhkf42gw"Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/files/file_01m4z8vge0fkktt139dhkf42gw"{ "id": "file_01m4z8vge0fkktt139dhkf42gw", "kind": "selfie", "status": "ready", "content_type": "image/jpeg", "byte_size": 179114, "sha256": "9f2c4be1d0f5a3c8e7b6a5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4", "has_thumbnail": true, "created_at": "2026-10-15T07:54:00Z", "ready_at": "2026-10-15T07:54:03Z", "deleted_at": null, "upload": null}Register a file upload POST
Registers a file and returns a presigned URL to upload it to. Files never pass through the API: send the bytes with `PUT` to `upload.url`, with exactly the headers in `upload.headers`, within five minutes. Then use the file's ID where a record takes one, for example `selfie_file_id` on a clock-in. | `kind` | Content types | Up to | | ---------------- | ----------------------------------------- | ------ | | `visitor_photo` | `image/jpeg`, `image/png`, `image/webp` | 5 MB | | `id_image` | `image/jpeg`, `image/png`, `image/webp` | 10 MB | | `signature` | `image/png` | 1 MB | | `selfie` | `image/jpeg`, `image/webp` | 5 MB | | `delivery_photo` | `image/jpeg`, `image/png`, `image/webp` | 10 MB | | `document` | `application/pdf` | 20 MB | | `badge` | `application/pdf`, `image/png` | 5 MB | - The storage refuses an upload of another type or size, or after the link expires. Register the file again to get a new link. - After the upload, Agoo removes the photo's metadata (EXIF, including any GPS location), checks that the content matches its type and makes a thumbnail for photos. The file's `status` then changes from `pending` to `ready`, usually within seconds. A file whose content doesn't match its type is deleted. - A file that is never uploaded is deleted after a day. ID images, visitor photos and selfies are deleted on your organisation's retention schedule. - `selfie` needs selfie evidence switched on in your attendance settings; otherwise you get `validation_failed` at `body.kind`. **Scope:** `files:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.
Get a download link GET
Returns links to a `ready` file and its thumbnail that work for two minutes. Fetch a new link each time you show the file rather than storing one. - Opening an ID image or a selfie is recorded in the audit trail (`file.opened`). - A file that isn't ready yet, or was deleted, returns `invalid_state`. **Scope:** `files:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.