Files and uploads
Upload photos, selfies, signatures and documents straight to Agoo's private storage with short-lived links, then use the file's ID on a record.
This is a published preview. Names and fields may still change before general availability; changes will be listed in the changelog.
Files never pass through the API. You register a file, upload its bytes straight to Agoo's private storage with a link that works for five minutes, and use the file's ID where a record takes one, such as selfie_file_id on a clock-in.
Upload a file
Register it
POST/files with the kind, the content type and the exact size in bytes. You need the
files:write scope.
curl https://api.agoo.ardent.africa/v1/files \
-H "Authorization: Bearer $AGOO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "kind": "selfie", "content_type": "image/jpeg", "byte_size": 184320 }'The response is the file, with status: "pending" and an upload object: the URL, the method (PUT), the headers to send and when the link expires.
Upload the bytes
Send the file as the body of a PUT to upload.url, with exactly the headers in upload.headers:
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @selfie.jpgThe storage refuses an upload of another type or size, or after the link expires. Register the file again for a new link.
Wait for it to be ready
Agoo checks that the content matches its type, removes the photo's metadata (EXIF, including any GPS location, camera details and dates) and makes a thumbnail for photos. The file's status changes to ready, usually within seconds; GET/files/{file_id} shows it. A file whose content doesn't match its type is deleted, and its status stays pending until it's cleared after a day.
You can use the file's ID on a record as soon as you've registered it; you don't have to wait for ready.
What each kind accepts
kind | Content types | Up to | Thumbnail |
|---|---|---|---|
visitor_photo | image/jpeg, image/png, image/webp | 5 MB | Yes |
id_image | image/jpeg, image/png, image/webp | 10 MB | No |
signature | image/png | 1 MB | No |
selfie | image/jpeg, image/webp | 5 MB | Yes |
delivery_photo | image/jpeg, image/png, image/webp | 10 MB | Yes |
document | application/pdf | 20 MB | No |
badge | application/pdf, image/png | 5 MB | No |
Show a file
GET/files/{file_id}/download returns links to the file and its thumbnail that work
for two minutes. Fetch a new link each time you show the file; don't store links. You need files:read.
- Selfies are visible only to keys and people who can read attendance (
attendance:read), and to whoever uploaded them. - Opening an ID image or a selfie is recorded in your audit trail as
file.opened.
How long files are kept
- ID images are deleted on your organisation's schedule: 24 hours by default.
- Visitor photos follow your visitor photo retention (90 days by default) and selfies your selfie retention (90 days by default, adjustable from 1 day to 10 years, or kept until deleted).
- Uploads that never complete are deleted after a day.
- Erasing a visitor deletes their photos and signatures.
- A legal hold (Enterprise) pauses all of this for what it covers.
A deleted file keeps its ID and shows status: "deleted", so records that point at it stay intact.