Download the combined PFC taxonomy CSV from https://plaid.com/documents/pfc-taxonomy-all.csv; this file contains both v1 and v2 entries with version labels, primary category, detailed category, and description columns.
Filter the CSV for rows where the version column equals 'v2' to isolate the current taxonomy; the v2 taxonomy introduced in December 2025 adds subcategories in income, loan disbursement, loan repayment, and bank fees.
Build a lookup map keyed on the detailed field (e.g., 'FOOD_AND_DRINK_FAST_FOOD') mapping to human-readable description and primary grouping; this map will be used to enrich enriched_transactions responses.
When calling /transactions/enrich or /transactions/sync, set options.personal_finance_category_version to 'v2' to receive v2 detailed codes in the personal_finance_category.detailed response field.
Match each returned personal_finance_category.detailed value against your lookup map to display the user-facing category name and icon; use personal_finance_category_icon_url from the response for pre-built icons.
Re-download the taxonomy CSV periodically (Plaid may add categories); store the CSV version or a hash to detect changes and refresh your lookup map accordingly.
Known gotchas
The taxonomy CSV at https://plaid.com/documents/pfc-taxonomy-all.csv contains both v1 and v2 rows; failing to filter by version will mix deprecated v1 codes with v2 codes and produce incorrect mappings.
Pre-December-2025 Plaid accounts default to v1 even when you download the v2 CSV — you must also set personal_finance_category_version to 'v2' in every API request to receive v2 codes in responses.
The detailed category string (e.g., 'GENERAL_MERCHANDISE_SUPERSTORES') is the stable unique identifier for a category; the human-readable description may be updated between CSV releases, so key your map on the detailed code, not the description.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp