Menu
GET custom-fields/definitions/ User APIService tier

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/

Query parameters

NameDefault
field_typenone
include_deletednone
qnone
searchnone
sincenone

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "definitions": [
    "..."
  ],
  "total": 0
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
401unauthorized

Example

curl -X GET "https://platform.mattering.io/api/user/v1/custom-fields/definitions/?field_type=...&include_deleted=...&q=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: custom_fields/views.py (views.definitions_list)

POST custom-fields/definitions/delete/ User APIService tier

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)

KeyRequiredDefault
keyoptional or conditionalnone
public_idoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "ok": "...",
  "results": [
    {
      "index": "...",
      "public_id": "...",
      "name": "...",
      "result": "...",
      "detail": "..."
    }
  ],
  "counts": {}
}

200 bare JSON object (no envelope)

{
  "ok": true,
  "deleted": true,
  "result": "deleted",
  "public_id": "...",
  "name": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid JSON body message
400not_found
400public_id is required message
400public_ids is empty message
400too_many_items
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/custom-fields/definitions/delete/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "...",
  "public_id": "..."
}'

Source: custom_fields/views.py (views.definitions_delete)

POST custom-fields/definitions/upsert/ User APIService tier

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.

Body::

{
        "name": "Client Website URL",
        "field_type": "WEBSITE",
        "description": "...",
        "options": [],
        "default_value": "",
        "is_required": false,
        "source_app": "productivity",
        "public_id": "abc123def456",      # optional, for stable re-sync
        "client_updated_at": "2026-06-17T10:00:00Z"  # optional, enables LWW
    }

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)

KeyRequiredDefault
client_updated_atoptional or conditionalnone
default_valueoptional or conditionalnone
descriptionoptional or conditionalnone
field_typeoptional or conditionalnone
is_requiredoptional or conditionalfalse
keyoptional or conditionalnone
labeloptional or conditionalnone
nameoptional or conditionalnone
optionsoptional or conditional[]
public_idoptional or conditionalnone
source_appoptional or conditionalnone
typeoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "ok": true,
  "created": true,
  "applied": "...",
  "definition": "..."
}

200 bare JSON object (no envelope)

{
  "ok": true,
  "results": [
    {
      "index": "...",
      "public_id": "...",
      "name": "...",
      "result": "created",
      "detail": "",
      "definition": "..."
    }
  ],
  "counts": {}
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400definitions is empty message
400invalid JSON body message
400too_many_items
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/custom-fields/definitions/upsert/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client_updated_at": "...",
  "default_value": "...",
  "description": "...",
  "field_type": "...",
  "is_required": false,
  "key": "...",
  "label": "...",
  "name": "..."
}'

Source: custom_fields/views.py (views.definitions_upsert)

GET custom-fields/presets/ User APIService tier

List presets for the calling organization (``since``, ``include_deleted``).

URL

  • User APIhttps://platform.mattering.io/api/user/v1/custom-fields/presets/
  • Service tierhttps://platform.mattering.io/api/internal/custom-fields/presets/

Query parameters

NameDefault
include_deletednone
sincenone

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "presets": [
    "..."
  ],
  "total": 0
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
401unauthorized

Example

curl -X GET "https://platform.mattering.io/api/user/v1/custom-fields/presets/?include_deleted=...&since=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: custom_fields/views.py (views.presets_list)

POST custom-fields/presets/delete/ User APIService tier

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)

KeyRequiredDefault
public_idoptional or conditionalnone

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

200 bare 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).

Errors

StatusCode
400invalid JSON body message
400public_id is required message
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/custom-fields/presets/delete/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "public_id": "..."
}'

Source: custom_fields/views.py (views.presets_delete)

POST custom-fields/presets/upsert/ User APIService tier

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)

KeyRequiredDefault
client_updated_atoptional or conditionalnone
created_by_emailoptional or conditionalnone
descriptionoptional or conditionalnone
field_idsoptional or conditionalnone
nameoptional or conditionalnone
public_idoptional or conditionalnone
source_appoptional or conditionalnone

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

200 bare JSON object (no envelope)

{
  "ok": true,
  "created": true,
  "applied": false,
  "preset": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400field_ids must be a list message
400invalid JSON body message
400name is required message
401unauthorized

Example

curl -X POST "https://platform.mattering.io/api/user/v1/custom-fields/presets/upsert/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client_updated_at": "...",
  "created_by_email": "...",
  "description": "...",
  "field_ids": "...",
  "name": "...",
  "public_id": "...",
  "source_app": "..."
}'

Source: custom_fields/views.py (views.presets_upsert)

GET custom-fields/usage/ User APIService tier

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/

Query parameters

NameDefault
public_idnone
refreshnone

Responses

200 bare JSON object (no envelope)

{
  "ok": true,
  "public_id": "...",
  "usage": "...",
  "apps": "...",
  "cached_at": "..."
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
401unauthorized

Example

curl -X GET "https://platform.mattering.io/api/user/v1/custom-fields/usage/?public_id=...&refresh=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: custom_fields/views.py (views.usage_aggregate)

All Platform resources
Start Free Explore our Products