Skip to content

Custom fields

customFields is a free JSON object on every organization, contact and deal. An account may define some keys per record type. Values always live in the record’s customFields; defining, changing or deleting a definition never rewrites records.

Method & path Scope Notes
GET /custom-fields records:read ?entityType=organization|contact|deal, ?status=active|archived|all (default active). Not paginated
GET /custom-fields/:id records:read One definition
POST /custom-fields fields:manage Define → 201, with meta: { existingValues, invalidValues }
PATCH /custom-fields/:id fields:manage Labels, options, description, display, status; version
DELETE /custom-fields/:id fields:manage 204. Removes the definition only; values stay

Definitions are audited (entityType: "custom_field") and accept Idempotency-Key and dryRun.

{ id, entityType, key, label: { es, en? }, type, options, description, showInList, listPosition, filterable, status, version, createdAt, updatedAt, createdBy, updatedBy }

Field Rules
entityType organization, contact or deal. Immutable
key ^[A-Za-z][A-Za-z0-9_]{0,63}$, unique per (account, entityType) among active and archived → 409 DUPLICATE. Immutable
type text, number, boolean, date, select, url, email. Immutable: delete and define again to change it
label es required (≤ 80), en optional
options Only for select, required there: 1–100 { value, label: { es, en? } }; values ≤ 100, unique, no commas (INVALID_OPTION)
description ≤ 500. Tell other agents what the field means
showInList, listPosition A column in the app’s list (default false, at the end)
filterable A control in the app’s filter panel (default true)

At most 50 active definitions per record type → 422 TOO_MANY_FIELDS. Sending a different key, type or entityType on PATCH → 422 FIELD_IMMUTABLE. multi_select is not available; use tags for multi-valued labels.

Terminal window
curl -s -X POST https://api.mety.ai/api/v1/custom-fields \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: define:obsolescenceScore" \
-d '{
"entityType": "organization", "key": "obsolescenceScore", "type": "number",
"label": { "es": "Obsolescencia web", "en": "Website obsolescence" },
"description": "0-100, higher means a worse website", "showInList": true
}'
{ "data": { "id": "…", "key": "obsolescenceScore", "type": "number", "version": 1, "…": "…" },
"meta": { "existingValues": 412, "invalidValues": 3 } }

existingValues: records (archived included) already holding a non-null value under the key. invalidValues: how many of those are not in the type’s stored form (they fail the type, or need coercion like "57"). They count as NULL in typed filters until a write rewrites them.

Only keys with an active definition are checked, on create, PATCH (including customFieldsMerge), upserts and MCP. null and a blank string always clear the value.

type Accepted Stored as
text string ≤ 2 000, or a JSON number trimmed string (46001 → "46001")
number finite number, or a numeric string ("57", "1.5") number
boolean true/false, or "true"/"false" boolean
date YYYY-MM-DD string
select one of options[].value, exactly string
url http(s)://… string
email an email address lower-cased string

A wrong value → 400 VALIDATION_FAILED with details.fields: [{ field: "customFields.<key>", reason: "CUSTOM_FIELD_TYPE" | "NOT_AN_OPTION", message, allowed? }] (in an upsert item: items[<i>].customFields.<key>). A value stored before its definition existed is left alone; the next write that changes that key must fit.

Terminal window
curl -sg "https://api.mety.ai/api/v1/organizations?filter[customFields.obsolescenceScore][gte]=50&sort=customFields.obsolescenceScore:desc" \
-H "Authorization: Bearer $METY_KEY"

Ops per type are in lists, filters and search.

PATCH { "status": "archived" } stops validation and typed filtering and hides the column; records keep their values; restoring counts toward the 50 again. DELETE removes the definition; the values stay in customFields, untyped.

Before defining, check GET /custom-fields (or describe_crm): use an existing key as it is, never a variant (provincia next to province). See the recipe.