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.
Endpoints
Section titled “Endpoints”| 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.
The definition
Section titled “The definition”{ 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.
Define one
Section titled “Define one”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.
Validation on write
Section titled “Validation on write”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.
Filter and sort by it
Section titled “Filter and sort by it”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.
Archive or delete
Section titled “Archive or delete”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.