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
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.
Required headers
The
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
cURL
200 OK)
JSON
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.
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
cURL
200 OK)
JSON
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}
cURL
--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)
JSON
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
cURL
200 OK)
JSON
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}
cURL
200 OK)
JSON
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.
JSON
- 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.
Error handling
Errors return a JSON envelope:JSON
Next steps
Organizations
Provision and configure the organizations that hold your policy documents.
Users
Add, update, and remove the employees the policy applies to.
Dimensions
Configure custom dimensions and list values on an organization.
Charts of accounts
Manage the accounting numbers expenses are booked against.

