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)
- `isArchived`: if true, the field has been decommissioned
- `isSplittable`: if true, a payable can have multiple values for this field
- `availableForEntities`: payable types concerned (`["expense","request","payment","subscription"]`)

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

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

Returns the list of valid values: `{ id, value, isArchived }`.

## Pitfall: includeArchived defaults to false, but still returns archived fields

On this account, `get_analytical_fields()` with no parameter returns **21 fields, 16 of which have `isArchived: true`**, despite `includeArchived` defaulting to false. The documented behavior ("archived fields are excluded by default") does not match the actual implementation.

→ Always filter client-side on `isArchived: false` 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)

→ The "Analytic codes" field and `get_expense_categories` expose **the same reference data**. 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>",
    "dateRange": { "startDate": "2026-01-01", "endDate": "2026-06-30" },
    "groupBy": ["analyticalCode"],
    "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"