Early access
Download documents from a folder
Retrieve daily uploads across employees with expiring download links and consistent filenames.
Use GET /api/v4/document_folders/{id}/documents to list documents across
employees in one folder. Each uploaded file includes a download URL, its
original filename, and the employee ID. External document links are returned
with type: "link" and their original URL.
Set up access
Create a service account and role. In the service role's Documents tab, grant View for the required folder. Set the role's affected employees to the people whose uploads the integration needs, and assign the role to the service account.
A folder permission applies only to that role's affected employees. Another
role granting access to more employee profiles does not extend document access.
A key without access to the folder receives 403. A permitted role affecting
no employees receives an empty list. Inactive, deleted, or another tenant's
folders return 404.
Use the folder ID already configured in your integration. This endpoint does not include documents from child folders. Documents belonging to deleted employees and deleted documents are excluded.
List a day's uploads
curl --get 'https://app.peopleforce.io/api/v4/document_folders/123/documents' \
--header "X-API-KEY: $PEOPLEFORCE_API_KEY" \
--data-urlencode 'created_at[gte]=2026-09-24T00:00:00Z' \
--data-urlencode 'created_at[lt]=2026-09-25T00:00:00Z' \
--data-urlencode 'per_page=50' \
--data-urlencode 'page=1'All filters are optional. created_at filters by upload time, not a date
printed on an invoice. updated_at filters by the last change, so use it to
pick up edits since your previous sync. Each takes any of four operators:
| Operator | Matches |
|---|---|
gt | after the value |
gte | on or after the value |
lt | before the value |
lte | on or before the value |
Supply ISO 8601 timestamps with Z or a timezone offset, such as
2026-09-24T00:00:00+02:00. For daily downloads, pair gte with lt and use
the same boundary for consecutive windows, so no upload is missed or repeated.
The response contains data and metadata. Uploaded files include:
| Field | Meaning |
|---|---|
id | Document ID; use it to deduplicate imports |
employee_id | Employee who owns the document |
document_folder_id | Folder containing the document |
name | Document name in PeopleForce |
type | file or link |
created_at, updated_at | Upload and last update timestamps |
original_filename | Original uploaded filename, including its extension |
content_type, byte_size | File MIME type and size in bytes |
url | File download URL or original external link |
expires_at | Expiry of the file download URL |
External links omit original_filename, content_type, byte_size, and
expires_at. They may require authentication with the external provider.
Results are ordered by created_at, then id. The default page size is 50,
with a maximum of 100. Read metadata.page, per_page, total_pages, and
total_count, and continue until all pages have been retrieved.
Download and import
File URLs expire after one hour. Download them promptly and follow HTTP redirects. If a URL has expired, repeat the listing request to get a fresh URL. Treat these links as sensitive: anyone holding a valid link can download its file.
Your integration can name each file using the upload date, employee_id,
id, and original_filename, then upload it to your finance system. Sanitise
filenames before writing them to disk. Save a document ID as processed only
after the destination confirms the import.
Keep a checkpoint for completed date windows and retry failed documents.
Listing a window again produces fresh URLs; deduplicate using document IDs,
not URLs. If you receive 429, wait for the Retry-After interval before
retrying. A ZIP download is not required for this workflow.