Skip to main content
Manage the expense categories of an organization through the Findity Admin API. This guide shows you how to list, read, create, update, and delete an organization’s expense categories, and how a category is mapped to accounts and salary types.

Overview

An expense category is the label an expense is filed under, such as Hotel, Mileage or Domestic per diem. Each category also carries the rules that apply to expenses in it: default tax percent, the accounting and salary accounts used on export, and the kind of expense it creates. The category lifecycle is:
  1. Read the categories an organization already has — list them, or fetch one by its id.
  2. Create categories your customer needs on top of the ones the organization started with.
  3. Keep them in sync — update names, tax settings and account mappings, and delete categories that are no longer used.
Every call works on one organization.

Prerequisites

  1. Complete Authentication and obtain an admin-scoped access token.

Key concepts

API endpoints

All endpoints use the Admin API base URL. Examples in this guide use the stage host — switch to the production host (api.findity.com) only when you’re ready to go live.

Required headers

Step 1 — List expense categories

Retrieve the categories of an organization. The response is wrapped in a {meta, data} envelope. GET /organizations/{organizationId}/expenseservice/categories

Query parameters

cURL
Example response (status 200 OK)
JSON
meta.total is the total number of categories in the organization; meta.count is the number of items returned in this response.
An organization gets its categories from the template it was created from. An organization created from a template that has no categories returns { "meta": { "total": 0, "count": 0 }, "data": [] }.

Response fields

Every endpoint that returns a category uses the same fields. Fields that have no value are left out of the response, so a per diem category such as Domestic has no defaultTaxPercent and no accountingNumberId.

Step 2 — Get a single category

Retrieve one category by its id. The response is the category itself, without the {meta, data} envelope. GET /organizations/{organizationId}/expenseservice/categories/{categoryId}
cURL
Example response (status 200 OK)
JSON
An unknown categoryId returns 404 CATEGORY_NOT_FOUND.

Step 3 — Create a category

Add a category to the organization. Returns 201 Created with the new category, including its id. POST /organizations/{organizationId}/expenseservice/categories

Request body fields

Don’t send id when you create a category: Findity generates it, and a request with an id is rejected with 400 INVALID_ID.
cURL
Example response (status 201 Created)
JSON
A request that is missing name, classType or categoryTemplateId, or that has an unsupported classType, returns 400 without a code.

Step 4 — Update a category

Change a category. Only the fields you send are changed. The request body must include the category’s id, and it must match the categoryId in the URL — otherwise the call returns 400 INVALID_ID. The category’s type can’t be changed: a classType in an update is ignored. PUT /organizations/{organizationId}/expenseservice/categories/{categoryId} The body takes the same optional fields as in Step 3.
cURL
Example response (status 200 OK)
JSON
To map the category to an account, send the id of the account as accountingNumberId. The response then carries the account in accountingNumber, and accountingNumbers lists it.

Step 5 — Delete a category

Remove a category from the organization. Returns 204 No Content with an empty response body on success. DELETE /organizations/{organizationId}/expenseservice/categories/{categoryId}
A category that expenses already use can’t be deleted. The call returns 400 CATEGORY_IN_USE.
cURL
Example response (status 204 No Content) The response body is empty. After the deletion the category no longer appears in the list, and GET on it returns 404 CATEGORY_NOT_FOUND.

Common integration patterns

Find the categories of one type. The list has no filter. Read the full list and keep the items whose categoryType (or verificationClassType) matches, for example every SubsistenceAllowanceCategory to find the per diem categories. Map categories to accounts. Keep the chart of accounts and the categories in line after an accounting change:
  1. GET /organizations/{organizationId}/accounts to read the account ids.
  2. GET /organizations/{organizationId}/expenseservice/categories?max=1000 and check each category’s accountingNumberId. Per diem and mileage categories have none.
  3. PUT the categories whose mapping must change, with the new accountingNumberId.
To send many of these calls in one request, see Bulk requests. Add a category of an existing type. Read the list, pick a category of the type you want (for example OtherExpenseCategory), and use its categoryTemplateId in POST with the matching classType.

Error handling

Errors return a JSON envelope:
JSON
The requestId value is useful to include when reporting a problem to Findity support. Some 400 errors have no code.
Last modified on November 13, 2026