policyUrl field on the organization.
Overview
A policy document is a PDF that describes the expense rules for an organization: what employees can claim, receipt requirements, mileage rates, per-diem limits, and so on. Each organization holds one policy document, and Findity exposes a pre-signed URL to it on the organization record so end users can read it in the app. The typical lifecycle is: (1) upload the document, (2) list it to find itsdocumentId, (3) fetch the document to review it, (4) update its display metadata, and (5) delete it when it has been superseded.
Every policy document has two parts:
- A binary file: the PDF itself, stored by Findity.
- A metadata record: the display name, file name, upload timestamp, and uploader. Returned by the list endpoint and editable via
PUT.
name, the right fileName) is what your users will see when they open the policy from the expense app.
Prerequisites
- Complete Authentication and obtain an admin-scoped access token.
- Create or identify the customer organization (see Admin API — Organizations) and have its
organizationIdready. The policy endpoints take the organization’s internal id (32-character hex). YourexternalSourceIdisn’t accepted in its place. - The organization needs an active policies license. Without one, list, download, and update requests return
400 MISSING_POLICIES_LICENSE. - Have the policy PDF ready on disk for the upload in Step 1.
Key concepts
| Concept | Description |
|---|---|
| Policy document | A PDF file describing the organization’s expense rules. An organization holds one policy document. |
organizationId | The internal id of the organization the policy belongs to. |
documentId | The id of the policy document. Returned by the list endpoint and used on all per-document operations. |
policyUrl | Pre-signed URL to the organization’s policy document, returned on the organization payload. Null when no policy is configured. |
name | Display name shown to users (e.g. “Expense policy 2026”). Null until you set it with PUT. |
fileName | Original file name (e.g. policy.pdf). |
API endpoints
All policy endpoints use the Admin API base URL. Examples in this guide use the stage environment. Switch to the production host (api.findity.com) only when you’re ready to go live.
| Operation | Method | Endpoint |
|---|---|---|
| Upload a policy document | POST | /organizations/{organizationId}/policies/documents |
| List policy documents | GET | /organizations/{organizationId}/policies/documents |
| Download a policy document | GET | /organizations/{organizationId}/policies/documents/{documentId} |
| Update a policy document | PUT | /organizations/{organizationId}/policies/documents/{documentId} |
| Delete a policy document | DELETE | /organizations/{organizationId}/policies/documents/{documentId} |
Required headers
| Header | Value |
|---|---|
Authorization | Bearer {access_token} |
Content-Type | application/json on the PUT. The upload is multipart form data; cURL sets that header when you use -F |
GET for a single document returns the file itself application/pdf), not JSON. Save the response to a file or stream it. Don’t try to parse it as JSON.
Step 1 — Upload a policy document
Upload the policy PDF as multipart form data, in a form field namedfile. The organization holds one policy document, so the upload succeeds only when none exists yet. To replace a document, delete the existing one first (Step 5).
POST /organizations/{organizationId}/policies/documents
| Form field | Type | Required | Description |
|---|---|---|---|
file | file | Required | The policy PDF. Its file name becomes the document’s fileName. |
"https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@policy.pdf;type=application/pdf"
Example response (status 200 OK)
"id": 1042,
"document": { "id": "22adfe2a080040e3892ffb89c21ec445" },
"organization": { "id": "8a5c8bee9e3a4a24019e3ae1732b008e" },
"fileName": "policy.pdf",
"uploadedById": "8a5c8bee9e3a4a24019e3ae1732b0099"
}
document.id is the documentId to use in the per-document operations. The display name isn’t set by the upload; set it with Step 4.
A request without a file form field returns 200 OK with an empty array []) and uploads nothing. Check that the response contains document.id before you continue.
Step 2 — List policy documents
Fetch the policy document attached to the organization. Use the result to find thedocumentId you need for the per-document operations, or to confirm an upload. The data array holds at most one entry, and is empty when no document has been uploaded.
GET /organizations/{organizationId}/policies/documents
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
sort | string | date | Property to sort by. Allowed values: fileName, name, date, uploadedBy. An unsupported value is ignored. |
sortOrder | string | desc | Sort direction: asc or desc. |
"https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents?sort=date&sortOrder=desc" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response (status 200 OK)
"data": [
{
"id": 1042,
"name": null,
"fileName": "policy.pdf",
"date": "2026-10-21T19:32:36Z",
"documentId": "22adfe2a080040e3892ffb89c21ec445",
"uploadedBy": "Jane Smith"
}
]
}
The documentId returned here is what you’ll pass to the GET, PUT, and DELETE endpoints below. name is null until you set a display name in Step 4.
Step 3 — Download a policy document
Fetch the file of the policy document. The response is the raw PDF (application/pdf), not a JSON envelope.
GET /organizations/{organizationId}/policies/documents/{documentId}
"https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents/22adfe2a080040e3892ffb89c21ec445" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--output policy.pdf
The --output policy.pdf flag writes the response body to a local file. Without it, cURL prints the binary to your terminal.
Not found response (status 404 Not Found)
"result": "error",
"code": "POLICY_DOCUMENT_NOT_FOUND",
"description": "Policy document not found"
}
Returned when the documentId doesn’t match the organization’s policy document.
Step 4 — Update a policy document
Change the displayname and fileName of the document. The PUT updates metadata only; it doesn’t replace the underlying file. To replace the file itself, delete the document (Step 5) and upload a new one (Step 1).
PUT /organizations/{organizationId}/policies/documents/{documentId}
Request body — fields
"https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents/22adfe2a080040e3892ffb89c21ec445" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Expense policy 2026",
"fileName": "expense-policy-2026.pdf"
}'
Example response (status 200 OK)
"id": "22adfe2a080040e3892ffb89c21ec445",
"name": "expense-policy-2026.pdf",
"created": "2026-10-21T19:32:36Z",
"description": "Expense policy 2026",
"mimeType": "application/pdf",
"isPublic": false
}
The response returns the stored document record, in which the file name is the name field and the display name you sent is the description field. Only fileName and name can be changed.
Step 5 — Delete a policy document
Remove the policy document from the organization. This deletes both the file and its metadata record.policyUrl on the organization payload becomes null until a new document is uploaded (Step 1).
DELETE /organizations/{organizationId}/policies/documents/{documentId}
"https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents/22adfe2a080040e3892ffb89c21ec445" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response (status 200 OK)
"result": "success",
"description": "policy document has been deleted"
}
Delete is immediate and irreversible. The file is removed from storage and cannot be recovered. Keep a local copy if you may need to restore the document later.
Reading the active policy from the organization payload
The organization record exposes the policy document through thepolicyUrl field. Get a single organization (GET /organizations/{organizationId}) to read it. List items don’t include it.
"id": "8a5c8bee9e3a4a24019e3ae1732b008e",
"name": "Acme Inc.",
"policyUrl": "https://stage-expense.findity.com/api/v1/expense/me/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents/22adfe2a080040e3892ffb89c21ec445?X-Findity-Expires=..."
}
Behavior:
- Pre-signed URL. The link is short-lived. Fetch a fresh organization payload when the URL expires rather than caching it long-term.
- Null when no policy exists.
policyUrlisnullon organizations without a policy document.
Common integration patterns
Publishing a new annual policy. An organization holds one policy document, so to roll out an updated policy, download and archive the current one (Step 3), delete it (Step 5), upload the new PDF (Step 1), then usePUT to set a clear name (e.g. “Expense policy 2026”).
Auditing what’s attached. Run the list endpoint periodically and check the date and uploadedBy fields to confirm the document is the one you expect, and that name is set.
Showing the policy in your own app. Read policyUrl from the organization payload and link to it. The URL is pre-signed, so fetch it fresh each time instead of storing it.

