---
title: "Get a custom field definition by its id"
method: GET
path: "/v1/customFields/{customFieldId}"
tags: ["Custom Fields"]
---

# Get a custom field definition by its id

`GET /v1/customFields/{customFieldId}`

## Request

- Base URL: `https://api.bigchange.com`
- URL: `https://api.bigchange.com/v1/customFields/{customFieldId}`
- Auth: HTTP bearer

Get a custom field definition by its id. Inactive (soft-deleted) definitions are returned with isActive: false rather than a 404. (required scope customfields:read)

## Path parameters

- `customFieldId` integer, required

## Headers

- `Customer-Id` integer, required

## Response `200`

OK

- ReadCustomFieldModel: Read custom field definition model
  - `id` integer: The unique identifier of the custom field definition
  - `name` string: The name of the custom field
  - `entityType` 'contact' | 'note' | 'job' | 'vehicle' | 'user' | 'resource' | 'financialDocument' | 'person' | 'stock' | 'Unknown': The kind of entity a custom field definition is attached to.<p>Possible values:</p><ul><li><b>contact</b>: Contact entity</li><li><b>note</b>: Contact note entity</li><li><b>job</b>: Job entity</li><li><b>vehicle</b>: Vehicle entity</li><li><b>user</b>: User entity</li><li><b>resource</b>: Resource entity</li><li><b>financialDocument</b>: Financial document entity (invoice or invoice line item)</li><li><b>person</b>: Person entity</li><li><b>stock</b>: Stock entity</li><li><b>unknown</b>: Fallback used when the underlying entity type has no corresponding API vocabulary value</li></ul>
  - `fieldType` 'text' | 'number' | 'date' | 'dateTime' | 'boolean' | 'list' | 'multiList' | 'Unknown': The data type of a custom field definition's value.<p>Possible values:</p><ul><li><b>text</b>: Free text</li><li><b>number</b>: Numeric value (integer or decimal)</li><li><b>date</b>: Date only</li><li><b>dateTime</b>: Date and time</li><li><b>boolean</b>: Boolean value</li><li><b>list</b>: Single selection from a fixed list of values</li><li><b>multiList</b>: Multiple selections from a fixed list of values</li><li><b>unknown</b>: Fallback used when the underlying field type has no corresponding API vocabulary value</li></ul>
  - `isRequired` boolean: Whether a value is expected for this custom field. This is informational - the service does not enforce it
  - `isActive` boolean: Whether this custom field definition is currently active. Inactive (soft-deleted) definitions<br/>are still returned so consumers can resolve historical values, but should not be offered for new entries
  - `displayOrder` integer: The position of this custom field relative to other custom fields on the same entity
  - `allowedValues` AllowedValueModel[], nullable: The acceptable values for this custom field, when its field type is List or MultiList; null otherwise
    - `id` integer: The position of this value within the field's allowed values, starting at 1.<br/>This is not a persisted identifier - it is derived from the order the values are stored in
    - `value` string: The allowed value

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

## Changes

- **2026-09-03** `553de7d50a1c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bigchange/apis/bigchange-dx/changes/v1/customFields/:customFieldId/get.md)

---

[API](https://skmtc.dev/bigchange/apis/bigchange-dx.md) - [All operations](https://skmtc.dev/bigchange/apis/bigchange-dx/llms.txt) - [OpenAPI document](https://skmtc.dev/bigchange/apis/bigchange-dx/revisions/b262bfdb1dd0?raw)