Custom fields

List custom field definitions

Returns the custom field DEFINITIONS of the account: which identifier each one has, which type it admits and, if it is a dropdown, which values it accepts.

GET

/api/v1/custom-fields

curl https://app.filmo.io/api/v1/custom-fields \
  --header "Authorization: Bearer $FILMO_API_KEY"

Node.jsfetch('https://app.filmo.io/api/v1/custom-fields', { headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY' } })Pythonimport requests requests.get( "https://app.filmo.io/api/v1/custom-fields", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY" } )

{
  "data": [
    {
      "id": "custom_field_definition_9f3a2b",
      "name": "Example custom field definition",
      "dataType": "text",
      "description": "Example text.",
      "options": [
        "Example options"
      ],
      "applyAt": [
        "order"
      ],
      "showOn": [
        "quote"
      ],
      "isActive": true,
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/addon_required",
  "title": "Add-on required",
  "status": 402,
  "code": "addon_required",
  "detail": "Your plan does not include the add-on this operation requires",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredAddon": "custom-fields"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "custom-fields:read"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

It lets you identify a custom field and the values it accepts. v1 only reads custom fields: no create or update body takes them, so they are set in the Filmo application. It does not return the value assigned to any entity: values travel inside each resource.

Authorizations

Bearer API key with the scope below. custom-fields:read

Query parameters

applyAtstring

Filter by the entity the field applies to: returns only the definitions usable on that resource type.

Available options: order, item, space, contact, project, kit, orderTemplate, repairTicket, serializedItem, vehicle, staff, service, purchaseOrder, incident, opportunity, document, all

Response

application/json

Successful response.

Response schema: CustomFieldDefinitionDto

Envelope: CustomFieldDefinitionItems. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset

dataobject[]

Show child attributes

data.idstring

Unique identifier of the definition. It is the one used when writing a value.

data.namestring

Display name of the field.

data.dataTypestring

Data type the field accepts.

Available options: text, multitext, dropdown, checkbox, radio, date, contact, item, space, staff_member, vehicle

data.descriptionstring | null

Field description; null if it has none.

data.optionsstring[]

Allowed values when the field is a dropdown. Empty for the other types.

data.applyAtstring[]

Entities the field can be used on.

data.showOnstring[]

Documents the field is printed on.

Available options: quote, proforma, invoice, contract, packing_slip, purchase_order, repair_ticket, all

data.isActiveboolean

true if the definition is active and can be used.

data.createdAtstring<date-time> | null

Creation date in ISO 8601 UTC; null if not recorded.

data.updatedAtstring<date-time> | null

Last modification date in ISO 8601 UTC; null if not recorded.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
402	`addon_required`	The account plan does not include the add-on this operation needs; `requiredAddon` names it.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Platform
Custom field definition
DEFINITION of a custom field of the account: its identifier, the type it admits and the values it accepts.

Was this page helpful?

Request examples

Authorizations

Query parameters

Response

Errors

Deprecation

Related

Related pages

Custom field definition