Field Catalog API

Base URL: https://api.delivr.ai
Version: v1
Authentication: Organization API key. Send X-Api-Key: <dlvr_...> and X-Api-Secret: <secret> on every request (both required). Create the key + secret in the dashboard at https://app.delivr.ai/{org_id}/settings/api-keys.

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. Your UI can then render the right controls (dropdowns, text inputs, or other control types) 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. The omission 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.
• partner_data fields come from data partners and are priced. Their field_key is <slug>__<column>, they are audience-only text fields, and each carries a partner_dataset object with the dataset's price and whether the project can use it. See Partner data.
• 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", "partner_data", "predictive"]
}

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.