Custom Fields

Custom fields are user-created fields used to categorize and tag persons in your organization. There are three types: text, multiselect, and number. Multiselect fields have options that can be managed through the API. On this page, we'll dive into the endpoints you can use to manage custom fields and their options programmatically.

The custom field model

The custom field model contains information about a user-created field, including its type and available options.

Properties

Name
id
Type
string
Description
Unique identifier for the custom field.
Name
name
Type
string
Description
The display name of the custom field.
Name
type
Type
string
Description
The field type. One of text, multiselect, or number.
Name
options
Type
array
Description
An array of options for multiselect fields. Each option has id, value, and optionally color.

GET/custom-fields

List all custom fields

This endpoint allows you to retrieve all custom fields in your organization. You can optionally filter by field type.

Optional attributes

Name
type
Type
string
Description
Filter by field type. One of text, multiselect, or number.

Request

GET

/custom-fields

curl -G https://rest.gatsby.events/custom-fields \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}"

Response

{
  "customFields": [
    {
      "id": "field-123",
      "name": "Title",
      "type": "text",
      "options": []
    },
    {
      "id": "field-456",
      "name": "Tags",
      "type": "multiselect",
      "options": [
        { "id": "opt-1", "value": "VIP", "color": "#FFD700" },
        { "id": "opt-2", "value": "Board Member", "color": "#4169E1" },
        { "id": "opt-3", "value": "Sponsor", "color": "#32CD32" }
      ]
    },
    {
      "id": "field-789",
      "name": "Salary",
      "type": "number",
      "options": []
    }
  ]
}

GET/custom-fields/:fieldId

Retrieve a custom field

This endpoint allows you to retrieve a single custom field by its ID, including its options.

Request

GET

/custom-fields/field-456

curl https://rest.gatsby.events/custom-fields/field-456 \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}"

Response

{
  "id": "field-456",
  "name": "Tags",
  "type": "multiselect",
  "options": [
    { "id": "opt-1", "value": "VIP", "color": "#FFD700" },
    { "id": "opt-2", "value": "Board Member", "color": "#4169E1" },
    { "id": "opt-3", "value": "Sponsor", "color": "#32CD32" }
  ]
}

POST/custom-fields

Create a custom field

This endpoint allows you to create a new custom field in your organization. Field names must be unique (case-insensitive). If a field with the same name already exists, a 409 Conflict error will be returned.

Required attributes

Name
name
Type
string
Description
The display name for the field.

Optional attributes

Name
type
Type
string
Description
The field type. One of text (default), multiselect, or number.
Name
options
Type
array
Description
Initial options for multiselect fields. Each option has a value and optional color.
Name
numberFormat
Type
object
Description
Format configuration for number fields. Has format (one of number, percent, USD, EUR, JPY, CAD, AUD, CNY, unformatted) and decimal (number of decimal places).

Request

POST

/custom-fields

curl https://rest.gatsby.events/custom-fields \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Funding Round","type":"multiselect","options":[{"value":"Seed"},{"value":"Series A"},{"value":"Series B"}]}'

Response (201)

{
  "id": "field-abc123",
  "name": "Funding Round",
  "type": "multiselect",
  "options": [
    { "id": "opt-1", "value": "Seed" },
    { "id": "opt-2", "value": "Series A" },
    { "id": "opt-3", "value": "Series B" }
  ]
}

POST/custom-fields/:fieldId/options

Create a field option

This endpoint allows you to create a new option for a multiselect custom field. The field must exist and be of type multiselect. Option values are unique per field (case-insensitive) — attempting to create a duplicate will return a 409 Conflict error.

Required attributes

Name
value
Type
string
Description
The display value for the new option. Will be trimmed and limited to 255 characters.

Request

POST

/custom-fields/:fieldId/options

curl https://rest.gatsby.events/custom-fields/{fieldId}/options \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -H "Content-Type: application/json" \
  -d '{"value":"Series C"}'

Response (201)

{
  "id": "option-abc123",
  "value": "Series C"
}