> ## Documentation Index
> Fetch the complete documentation index at: https://developer.findity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Policies

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**

<table>
  <colgroup>
    <col width="153" />

    <col width="563" />
  </colgroup>

  <thead>
    <tr>
      <th>**Concept**</th>
      <th>**Description**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Policy document**</td>
      <td>A PDF file describing the organization's expense rules. An organization holds one policy document.</td>
    </tr>

    <tr>
      <td>`organizationId`</td>
      <td>The internal id of the organization the policy belongs to.</td>
    </tr>

    <tr>
      <td>`documentId`</td>
      <td>The id of the policy document. Returned by the list endpoint and used on all per-document operations.</td>
    </tr>

    <tr>
      <td>`policyUrl`</td>
      <td>Pre-signed URL to the organization's policy document, returned on the organization payload. Null when no policy is configured.</td>
    </tr>

    <tr>
      <td>`name`</td>
      <td>Display name shown to users (e.g. "Expense policy 2026"). Null until you set it with `PUT`.</td>
    </tr>

    <tr>
      <td>`fileName`</td>
      <td>Original file name (e.g. `policy.pdf`).</td>
    </tr>
  </tbody>
</table>

## **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.

```text theme={"system"}
https://stage-api.findity.com/api/v1/admin
```

<table>
  <colgroup>
    <col width="240" />

    <col width="86" />

    <col width="391" />
  </colgroup>

  <thead>
    <tr>
      <th>**Operation**</th>
      <th>**Method**</th>
      <th>**Endpoint**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Upload a policy document</td>
      <td>`POST`</td>
      <td>`/organizations/{organizationId}/policies/documents`</td>
    </tr>

    <tr>
      <td>List policy documents</td>
      <td>`GET`</td>
      <td>`/organizations/{organizationId}/policies/documents`</td>
    </tr>

    <tr>
      <td>Download a policy document</td>
      <td>`GET`</td>
      <td>`/organizations/{organizationId}/policies/documents/{documentId}`</td>
    </tr>

    <tr>
      <td>Update a policy document</td>
      <td>`PUT`</td>
      <td>`/organizations/{organizationId}/policies/documents/{documentId}`</td>
    </tr>

    <tr>
      <td>Delete a policy document</td>
      <td>`DELETE`</td>
      <td>`/organizations/{organizationId}/policies/documents/{documentId}`</td>
    </tr>
  </tbody>
</table>

### **Required headers**

<table>
  <colgroup>
    <col width="136" />

    <col width="573" />
  </colgroup>

  <thead>
    <tr>
      <th>**Header**</th>
      <th>**Value**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`Authorization`</td>
      <td>`Bearer {access_token}`</td>
    </tr>

    <tr>
      <td>`Content-Type`</td>
      <td>`application/json` on the `PUT`. The upload is multipart form data; cURL sets that header when you use `-F`</td>
    </tr>
  </tbody>
</table>

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`

<table>
  <colgroup>
    <col width="103" />

    <col width="65" />

    <col width="95" />

    <col width="443" />
  </colgroup>

  <thead>
    <tr>
      <th>**Form field**</th>
      <th>**Type**</th>
      <th>**Required**</th>
      <th>**Description**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`file`</td>
      <td>file</td>
      <td>Required</td>
      <td>The policy PDF. Its file name becomes the document's `fileName`.</td>
    </tr>
  </tbody>
</table>

```text theme={"system"}
curl -X POST \
```

`  "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`)

```text theme={"system"}
{
```

`  "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**

<table>
  <colgroup>
    <col width="108" />

    <col width="69" />

    <col width="82" />

    <col width="450" />
  </colgroup>

  <thead>
    <tr>
      <th>**Parameter**</th>
      <th>**Type**</th>
      <th>**Default**</th>
      <th>**Description**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`sort`</td>
      <td>string</td>
      <td>`date`</td>
      <td>Property to sort by. Allowed values: `fileName`, `name`, `date`, `uploadedBy`. An unsupported value is ignored.</td>
    </tr>

    <tr>
      <td>`sortOrder`</td>
      <td>string</td>
      <td>`desc`</td>
      <td>Sort direction: `asc` or `desc`.</td>
    </tr>
  </tbody>
</table>

```text theme={"system"}
curl -X GET \
```

`  "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`)

```text theme={"system"}
{
```

`  "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}`

```text theme={"system"}
curl -X GET \
```

`  "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`)

```text theme={"system"}
{
```

`  "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**

| **Field** | **Type** | **Required** | **Description** |
| - | - | - | - |
| `fileName` | string | Required | File name (e.g. `policy.pdf`). Shown alongside the download link. |
| `name` | string | Optional | Display name shown to users (e.g. "Expense policy 2026"). Send it on every update: a request without `name` clears the existing display name. |

```text theme={"system"}
curl -X PUT \
```

`  "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`)

```text theme={"system"}
{
```

`  "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}`

```text theme={"system"}
curl -X DELETE \
```

`  "https://stage-api.findity.com/api/v1/admin/organizations/8a5c8bee9e3a4a24019e3ae1732b008e/policies/documents/22adfe2a080040e3892ffb89c21ec445" \`

`  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"`

**Example response** (status `200 OK`)

```text theme={"system"}
{
```

`  "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.

```text theme={"system"}
{
```

`  "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:

```text theme={"system"}
{ "result": "error", "code": "<machine-readable code>", "description": "<human-readable message>" }
```

| **Status** | `code` | **Description** |
| -: | - | - |
| `400` | `MISSING_POLICIES_LICENSE` | The organization has no active policies license. |
| `400` | — | The upload failed validation because the organization already has a policy document. The description is `request caused validation error`. Delete the existing document first. |
| `400` | `INVALID_JSON_BODY` | The `PUT` body can't be parsed as JSON. |
| `400` | — | The `PUT` body is missing `fileName`. The description is `request caused validation error`. |
| `401` | — | Access token is missing, expired, or invalid. Refresh the token and retry. |
| `404` | `ORGANIZATION_NOT_FOUND` | The organization doesn't exist, you have no admin access to it, or you passed an `externalSourceId` instead of the internal id. Confirm `{organizationId}`. |
| `404` | `POLICY_DOCUMENT_NOT_FOUND` | The policy document isn't found in this organization. Confirm `{documentId}`. |
| `429` | — | Rate limit exceeded. Apply exponential backoff before retrying. |
| `500` | — | Server error. Safe to retry with backoff; if the error persists, contact support with the response body. |

## **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.
