Skip to main content
Upload, list, download, rename, and remove the expense policy document on a Findity organization. This guide walks through managing the policy document attached to a customer organization. You’ll upload the document, list it, download it, update its display name and file name, and delete it when it is no longer in use. The policy is surfaced back to end users through the 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 its documentId, (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.
Because the active policy appears on the organization payload, keeping the metadata accurate (a clear name, the right fileName) is what your users will see when they open the policy from the expense app.

Prerequisites

  1. Complete Authentication and obtain an admin-scoped access token.
  2. Create or identify the customer organization (see Admin API — Organizations) and have its organizationId ready. The policy endpoints take the organization’s internal id (32-character hex). Your externalSourceId isn’t accepted in its place.
  3. The organization needs an active policies license. Without one, list, download, and update requests return 400 MISSING_POLICIES_LICENSE.
  4. 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 named file. 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
Example response (status 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.
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 the documentId 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
Example response (status 200 OK)
JSON
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}
cURL
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)
JSON
Returned when the documentId doesn’t match the organization’s policy document.

Step 4 — Update a policy document

Change the display name 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
Example response (status 200 OK)
JSON
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}
cURL
Example response (status 200 OK)
JSON
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 the policyUrl field. Get a single organization (GET /organizations/{organizationId}) to read it. List items don’t include it.
JSON
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. policyUrl is null on 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 use PUT 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.
Last modified on November 16, 2026