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

ConceptDescription
Policy documentA PDF file describing the organization’s expense rules. An organization holds one policy document.
organizationIdThe internal id of the organization the policy belongs to.
documentIdThe id of the policy document. Returned by the list endpoint and used on all per-document operations.
policyUrlPre-signed URL to the organization’s policy document, returned on the organization payload. Null when no policy is configured.
nameDisplay name shown to users (e.g. “Expense policy 2026”). Null until you set it with PUT.
fileNameOriginal 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.
OperationMethodEndpoint
Upload a policy documentPOST/organizations/{organizationId}/policies/documents
List policy documentsGET/organizations/{organizationId}/policies/documents
Download a policy documentGET/organizations/{organizationId}/policies/documents/{documentId}
Update a policy documentPUT/organizations/{organizationId}/policies/documents/{documentId}
Delete a policy documentDELETE/organizations/{organizationId}/policies/documents/{documentId}

Required headers

HeaderValue
AuthorizationBearer {access_token}
Content-Typeapplication/json on the PUT. The upload is multipart form data; cURL sets that header when you use -F
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
Form fieldTypeRequiredDescription
filefileRequiredThe 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 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

ParameterTypeDefaultDescription
sortstringdateProperty to sort by. Allowed values: fileName, name, date, uploadedBy. An unsupported value is ignored.
sortOrderstringdescSort 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 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

"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 the policyUrl 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. 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:

Next steps

Provision and configure the organizations that hold your policy documents. Add, update, and remove the employees the policy applies to. Configure custom dimensions and list values on an organization. Manage the accounting numbers expenses are booked against.
Last modified on November 16, 2026