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.

Custom fields in imports

An import (POST /v1/imports) has no mapping parameter: a CSV file’s header names its columns. A column named by a field’s key, or fields.<key>, fills that field; names are compared trimmed and in lowercase, with spaces, hyphens and dots read as underscores, so Institution ID fills institution_id. Columns that name no attribute and no field are ignored. A header for these fields might be:

email,given_name,institution_id,institution_name,street_address,department,municipality,phones_raw,is_government

Each cell is read as its field’s type: a Number cell accepts an integer or a decimal, a Boolean cell true/false, yes/no or 1/0, and an Enum cell one of the options, matched ignoring ASCII case and stored in the option’s own spelling. An empty cell is absent: an import fills and overwrites values, it never clears one. Keep institutional IDs, postal codes and phones as Text to preserve leading zeroes and formatting.

In a JSON import, each person’s fields holds values of their fields’ JSON types (numbers and booleans, not strings), and a key that names no field is a problem of that row. Either way, a row with a value its field refuses is reported as invalid, with its row, the field (fields.<key>) and the problem, in the import’s errors and its full error report; the other rows are imported.

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. Keep the header and the normalization report so later files use the same field names.

An import merges into the people that exist already: the values a row gives overwrite theirs, and what it leaves empty stays. It is not an audience of its own: pass group_id to collect the imported people in a group, and enroll the group. Importing contacts never starts a campaign.