Custom analytical fields and their values

# Custom analytical fields and their values

## Context

Analytical fields are custom dimensions defined by each company (e.g. project, BU, event code) — distinct from Spendesk's native cost centers. They let you tag payables with custom values.

These values are used as a filter in `spendesk_analyze_spend(analyticalCodes=[id])`.

## 2-step workflow

### Step 1 — List the analytical fields

```json
{
  "tool": "get_analytical_fields",
  "params": {
    "companyId": "<companyId>"
  }
}
```

For each field, note:
- `id`: identifier to pass to `get_analytical_field_values(fieldId)`
- `name`: field label (e.g. "Analytic codes", "Projects", "Clients")
- `type`: `"list"` (enumerated values) or `"boolean"` (checkbox)
- `archivedAt`: `null` if the field is active, otherwise the archive date (field decommissioned)
- `isSplittable`: if true, a payable can have multiple values for this field

### Step 2 — Get the values of a field

```json
{
  "tool": "get_analytical_field_values",
  "params": {
    "companyId": "<companyId>",
    "fieldId": "<field id>"
  }
}
```

Returns the field's values: `{ id, value, isDefault, archivedAt, createdAt, updatedAt }` — active and archived (`archivedAt` = null means active), cursor-paginated.

## Pitfall: archived fields are always returned (no server-side filter)

On this account, `get_analytical_fields()` with no parameter returns **21 fields, 16 of which have `isArchived: true`**, despite `includeArchived` defaulting to false. This is the documented behaviour: active and archived fields are both returned, there is no `includeArchived` parameter; the state is read from `archivedAt`.

→ Always filter client-side on `archivedAt: null` to get only the active fields.

On this account: 5 active fields out of 21:

| ID | Name | Type | Splittable |
|----|-----|------|-----------|
| `S1zHTdxe-` | Analytic codes | list | ✅ yes |
| `kdpholncfz8sdw` | Analytic codes 2021 | list | no |
| `ol-yyb9yal5frj` | B. Start Date (invoice) | list | no |
| `k9__lhhu9gki64` | C. End Date (invoice) | list | no |
| `e3ty_iz-69hgq9` | D. Schedule | list | no |

## Critical discovery: analytical values = expense categories

The IDs of the values returned by `get_analytical_field_values(fieldId="S1zHTdxe-")` are **identical** to the IDs returned by `get_expense_categories`.

Example:
- `get_expense_categories` → "ABM": `id = r96xprmx87jiso`
- `get_analytical_field_values("S1zHTdxe-")` → "ABM": `id = r96xprmx87jiso` (same)

→ Warning: `get_analytical_fields` now excludes the expense categories field, and `get_analytical_field_values` errors on that field (use `get_expense_categories`). Do not assume expense category IDs work in `filters.analyticalCodes`: use the IDs returned by `get_analytical_field_values`. The IDs from `get_expense_categories` can be used directly in `spendesk_analyze_spend(analyticalCodes=[...])` without going through `get_analytical_field_values`.

## Use in spendesk_analyze_spend

```json
{
  "tool": "spendesk_analyze_spend",
  "params": {
    "companyId": "<companyId>",
    "fromDate": "2026-01-01",
    "toDate": "2026-06-30",
    "groupBy": ["analyticalCode"],
    "filters": { "analyticalCodes": ["r96xprmx87jiso", "lq0vse74ak0q_n"] }
  }
}
```

The IDs to pass = the value IDs returned by `get_analytical_field_values`.

## `boolean` fields — no values to fetch

Fields of `type: "boolean"` (e.g. "Approved", "Hardware") have no listable values. They cannot be used as a filter in `spendesk_analyze_spend`. `get_analytical_field_values` would return an empty array for these fields.

## Example user prompts

- "What analytical codes are available to filter spend?"
- "Give me all the values for the 'Analytic codes' analytical field"
- "Analyze spend by analytical code for H1 2026"