List custom field definitions for the calling organization.
This powers any app's "select an existing custom field" menu and the pull side of the bi-directional sync.
Query params:
- field_type : restrict to one canonical type.
- since : ISO 8601; return only rows with updated_at >= since
(incremental pull for reconcile).
- include_deleted: when truthy, also return soft-deleted tombstones so
deletions propagate to consuming apps' mirrors.
URL
User APIhttps://platform.mattering.io/api/user/v1/custom-fields/definitions/
Service tierhttps://platform.mattering.io/api/internal/custom-fields/definitions/
Soft-delete a custom field definition by ``public_id``.
The row is tombstoned (is_deleted=True) rather than removed, and updated_at is bumped so the deletion propagates to consuming apps on their next pull. Body: {"public_id": "abc123def456"}.
URL
User APIhttps://platform.mattering.io/api/user/v1/custom-fields/definitions/delete/
Service tierhttps://platform.mattering.io/api/internal/custom-fields/definitions/delete/
Body keys (JSON)
Key
Required
Default
key
optional or conditional
none
public_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Idempotent create-or-update of a custom field definition.
Match precedence: 1. public_id (if provided and found for this org) returns update. 2. otherwise (organization_id, name) returns update existing or create.
Last-write-wins: when client_updated_at is supplied and the stored row is strictly newer, the row is left unchanged and returned as-is (the platform version won). A newer client edit also resurrects a soft-deleted definition.
Returns {ok, created, applied, definition}. applied is False when LWW kept the platform version.
URL
User APIhttps://platform.mattering.io/api/user/v1/custom-fields/definitions/upsert/
Service tierhttps://platform.mattering.io/api/internal/custom-fields/definitions/upsert/
Body keys (JSON)
Key
Required
Default
client_updated_at
optional or conditional
none
default_value
optional or conditional
none
description
optional or conditional
none
field_type
optional or conditional
none
is_required
optional or conditional
false
key
optional or conditional
none
label
optional or conditional
none
name
optional or conditional
none
options
optional or conditional
[]
public_id
optional or conditional
none
source_app
optional or conditional
none
type
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Soft-delete a preset by ``public_id``; the tombstone propagates on pull.
URL
User APIhttps://platform.mattering.io/api/user/v1/custom-fields/presets/delete/
Service tierhttps://platform.mattering.io/api/internal/custom-fields/presets/delete/
Body keys (JSON)
Key
Required
Default
public_id
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200bare JSON object (no envelope)
{
"ok": true,
"deleted": true
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Idempotent create-or-update of a preset (match on ``public_id``, then name).
Body: ``{name, description, source_app, field_ids: [...], public_id?, client_updated_at?, created_by_email?}. Returns {ok, created, applied, preset}; applied`` is False when LWW kept the platform version.
URL
User APIhttps://platform.mattering.io/api/user/v1/custom-fields/presets/upsert/
Service tierhttps://platform.mattering.io/api/internal/custom-fields/presets/upsert/
Body keys (JSON)
Key
Required
Default
client_updated_at
optional or conditional
none
created_by_email
optional or conditional
none
description
optional or conditional
none
field_ids
optional or conditional
none
name
optional or conditional
none
public_id
optional or conditional
none
source_app
optional or conditional
none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Where every definition in the org is used, merged across the apps.
?public_id= narrows to one definition; ?refresh=1 bypasses the five-minute cache. Apps that did not answer are listed in apps as unavailable / unconfigured so callers show "usage unknown".
URL
User APIhttps://platform.mattering.io/api/user/v1/custom-fields/usage/
Service tierhttps://platform.mattering.io/api/internal/custom-fields/usage/
We use strictly necessary cookies to run this site. With your permission we also use analytics cookies
(Google Analytics and our own visit tracking) to see which pages work. Read the
Cookie notice.