Typed custom fields

Define reusable English keys, scalar types and enum values for contacts and CSV imports.

GET /v1/people/fields lists up to 50 definitions for the authenticated workspace. POST /v1/people/fields creates a definition:

{
  "key": "department",
  "label": "Department",
  "field_type": "Enum",
  "options": ["Antioquia", "Bogotá, D.C.", "Cundinamarca"]
}

This is an abbreviated example, not the full Colombian catalog. Colombia has 32 departments plus Bogotá D.C. An institution directory should normalize those 33 subdivisions and preserve unrecognized source text for review.

Keys use English snake_case, start with a lowercase letter and have at most 64 characters. Types are Text, Number, Boolean and Enum. Enum requires 1–100 unique, exact case-sensitive strings. Other types use an empty options array. Definitions are immutable in this initial API: duplicate keys return 409. Creating a definition also returns 409 if existing contacts contain incompatible values.

Missing and null values are allowed. Undeclared keys retain the existing scalar-map contract, so adding definitions does not invalidate unrelated legacy fields. Contact POST/PATCH and database writes enforce declared types. A PATCH replaces the complete custom-fields object, so include the values you intend to retain.

CSV normalization and mapping

A CSV mapping still maps each English custom key to a header. Defined Boolean cells accept true / false; Number cells accept JSON numbers. Empty cells for declared fields become null. Text and Enum stay strings; keep institutional IDs, postal codes and phones as Text to preserve leading zeroes and formatting.

{
  "email": "email",
  "given_name": "given_name",
  "custom_fields": {
    "institution_id": "institution_id",
    "institution_name": "institution_name",
    "street_address": "street_address",
    "department": "department",
    "municipality": "municipality",
    "phones_raw": "phones_raw",
    "is_government": "is_government"
  }
}

CSV rows violating a definition are skipped and reported in the import’s invalid-row counters. Inline JSON must use actual booleans/numbers and is validated before acceptance. Worker processing checks again against current definitions. Source values are not included in public error messages.

Normalize multi-address source cells into separate contact rows before importing. Deduplicate by email, preserve original address/phone text, and do not invent a city, phone prefix or personal name. Government classification should record its evidence; an unknown or ambiguous geography should be marked for review. Save the mapping and normalization report so subsequent files use the same field names.

Use the returned import ID only after people_available: true. Imports reuse existing people without overwriting their data. Saved groups or segments can select the intended cohort; do not assume that importing contacts automatically starts a campaign.