Get contact field definitions

GET/v1/contacts/definitions

Returns the schema for all field and relationship definitions available on contacts, including both system-defined and custom fields. Useful for understanding the shape of contact data before creating or updating records. See Fields and relationships for more details.

Required scope: contacts:read

Rate limit category: Read

ReturnsExpand Collapse

ContactDefinitionsResponse = object { fieldDefinitions, objectType, relationshipDefinitions }

fieldDefinitions: map[object { description, label, typeConfiguration, 3 more } ]

Map of field keys to their definitions, including both system and custom fields.

description: string

Description of the field, or null.

label: string

Human-readable display name of the field.

typeConfiguration: map[string or number or boolean or 2 more]

Type-specific configuration (e.g. select options, currency code).

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

UnionMember2 = boolean

UnionMember3 = array of string or number or boolean or 2 more

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

UnionMember2 = boolean

UnionMember3 = array of unknown

UnionMember4 = map[unknown]

UnionMember4 = map[string or number or boolean or 2 more]

Accepts one of the following:

UnionMember0 = string

UnionMember1 = number

UnionMember2 = boolean

UnionMember3 = array of unknown

UnionMember4 = map[unknown]

valueType: "ADDRESS" or "CHECKBOX" or "CURRENCY" or 11 more

Data type of the field.

Accepts one of the following:

"ADDRESS"

"CHECKBOX"

"CURRENCY"

"DATETIME"

"EMAIL"

"FULL_NAME"

"MARKDOWN"

"MULTI_SELECT"

"NUMBER"

"SINGLE_SELECT"

"SOCIAL_HANDLE"

"TELEPHONE"

"TEXT"

"URL"

id: optional string

Unique identifier of the field definition.

readOnly: optional boolean

true for fields that are not writable via the API (e.g. AI-generated summaries). false or absent for writable fields.

objectType: string

The object type these definitions belong to (e.g. account).

relationshipDefinitions: map[object { cardinality, description, label, 2 more } ]

Map of relationship keys to their definitions.

cardinality: "HAS_ONE" or "HAS_MANY"

Whether this is a has_one or has_many relationship.

Accepts one of the following:

"HAS_ONE"

"HAS_MANY"

description: string

Description of the relationship, or null.

label: string

Human-readable display name of the relationship.

objectType: string

The type of the related object (e.g. account, contact).

id: optional string

Unique identifier of the relationship definition.

Get contact field definitions

curl https://api.lightfield.app/v1/contacts/definitions \
    -H 'Lightfield-Version: 2026-03-01' \
    -H "Authorization: Bearer $API_KEY"

{
  "fieldDefinitions": {
    "foo": {
      "description": "description",
      "label": "label",
      "typeConfiguration": {
        "foo": "string"
      },
      "valueType": "ADDRESS",
      "id": "id",
      "readOnly": true
    }
  },
  "objectType": "objectType",
  "relationshipDefinitions": {
    "foo": {
      "cardinality": "HAS_ONE",
      "description": "description",
      "label": "label",
      "objectType": "objectType",
      "id": "id"
    }
  }
}

Returns Examples

{
  "fieldDefinitions": {
    "foo": {
      "description": "description",
      "label": "label",
      "typeConfiguration": {
        "foo": "string"
      },
      "valueType": "ADDRESS",
      "id": "id",
      "readOnly": true
    }
  },
  "objectType": "objectType",
  "relationshipDefinitions": {
    "foo": {
      "cardinality": "HAS_ONE",
      "description": "description",
      "label": "label",
      "objectType": "objectType",
      "id": "id"
    }
  }
}