Field Catalog API

Base URL: https://api.delivr.ai Version: v1 Authentication: Authorization: Bearer <jwt>

The Field Catalog API returns metadata about every filterable field available in the audience builder. Use it to discover which fields exist, what values they accept, and which operators apply -- so your UI can render the right controls (dropdowns, text inputs, etc.) without hardcoding anything.

List Fields

Retrieve all fields, optionally filtered by schema type, category, or status.

GET /api/v1/field-catalog

Query Parameters

Response

{
  "total_count": 119,
  "fields": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "field_key": "seniority_level",
      "display_name": "Seniority Level",
      "description": "Standardized seniority classification",
      "category": "contact",
      "data_type": "string",
      "schema_types": ["audience"],
      "field_type": "multiselect",
      "operators": ["in", "notin"],
      "options": [
        { "value": "cxo", "label": "CXO" },
        { "value": "director", "label": "Director" },
        { "value": "manager", "label": "Manager" },
        { "value": "staff", "label": "Staff" },
        { "value": "vp", "label": "VP" }
      ],
      "status": "active",
      "sort_order": 12,
      "created_at": "2025-12-01T00:00:00Z",
      "updated_at": "2026-02-17T00:00:00Z"
    }
  ]
}

Field Object

Field Types and UI Controls

Notes

• options is omitted by default. Pass include_options=true to receive them. This matters because the full payload with all options is ~1.5 MB (mostly from job_title_normalized with 16,077 values).
• identifier fields are hidden from non-developer users. Internal users (developer flag set) see all categories.
• value is lowercase, label is display-cased. Always submit value in filter rules. Show label in the UI.

Get Categories

Returns distinct category names for active fields.

GET /api/v1/field-catalog/categories

Response

{
  "categories": ["company", "contact", "demographics", "event", "identifier", "intent"]
}

Get Single Field

Retrieve a single field by its key. Always includes options.

GET /api/v1/field-catalog/{key}

Path Parameters

Response

Returns a single field object (same shape as items in the list response, options always included).

Fields with Picklist Options

These fields have a bounded set of values the user can pick from. All other fields are free-text.

Contact

Company

Demographics

Event

Using Field Catalog in the Audience Builder

Rendering Filter Controls

1. Fetch fields once when the audience builder loads:

   GET /api/v1/field-catalog?schema_type=audience&status=active&include_options=true

2. Group by category for the sidebar/accordion (Contact, Company, Demographics, Intent).
3. Sort by sort_order within each category.
4. Render controls by field_type:
   • multiselect / select with options -- render a dropdown populated from options[].label
   • multiselect with 1000+ options (e.g. job_title_normalized) -- render a searchable typeahead
   • text -- render a free-text input
5. Show valid operators from the operators array. Map them to user-friendly labels:

Submitting Filter Rules

When the user builds a filter, use options[].value (not label) in the rule:

{
  "fieldName": "seniority_level",
  "conditionRules": {
    "operator": "in",
    "value": ["cxo", "vp", "director"]
  }
}

See Building Audience Filters for the full filter structure and examples.

Write Endpoints (Internal Only)

These endpoints require the developer flag (internal users only). Regular authenticated users get 403.