List all Custom Fields

Custom fields allow you to extend Blue’s standard record structure with additional data fields specific to your business needs. This endpoint retrieves custom fields available in your projects, with filtering by field type and pagination support.

Basic Example

query ListCustomFields {
  customFields(
    filter: { projectId: "project_123" }
    sort: position_ASC
    take: 20
  ) {
    items {
      id
      uid
      name
      type
      position
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

Advanced Example

query ListCustomFieldsAdvanced {
  customFields(
    filter: {
      projectId: "project_123"
      types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
    }
    sort: name_ASC
    skip: 20
    take: 50
  ) {
    items {
      id
      uid
      name
      type
      position
      description
      
      # Type-specific fields
      min              # For NUMBER, RATING, PERCENT
      max              # For NUMBER, RATING, PERCENT
      currency         # For CURRENCY type
      prefix           # For UNIQUE_ID type
      isDueDate        # For DATE type
      formula          # For FORMULA type
      
      # Validation settings
      editable
      metadata
      
      # For SELECT types
      customFieldOptions {
        id
        title
        color
        position
      }
    }
    pageInfo {
      totalItems
      hasNextPage
      hasPreviousPage
    }
  }
}

Input Parameters

CustomFieldFilterInput

Parameter	Type	Required	Description
`projectId`	String	No	Filter by specific project ID
`types`	[CustomFieldType!]	No	Filter by custom field types

CustomFieldSort Values

Value	Description
`name_ASC`	Sort by name ascending (A-Z)
`name_DESC`	Sort by name descending (Z-A)
`createdAt_ASC`	Sort by creation date (oldest first)
`createdAt_DESC`	Sort by creation date (newest first)
`position_ASC`	Sort by position (default)
`position_DESC`	Sort by position descending

CustomFieldType Values

Value	Description
`TEXT_SINGLE`	Single line text input
`TEXT_MULTI`	Multi-line text area
`SELECT_SINGLE`	Single selection dropdown
`SELECT_MULTI`	Multiple selection dropdown
`CHECKBOX`	Boolean checkbox field
`RATING`	Star rating (1-5 or custom range)
`PHONE`	Phone number with validation
`NUMBER`	Numeric input
`CURRENCY`	Currency amount
`PERCENT`	Percentage value
`EMAIL`	Email address with validation
`URL`	Web URL with validation
`UNIQUE_ID`	Auto-generated unique identifier
`LOCATION`	Geographic location (lat/lng)
`FILE`	File attachment
`DATE`	Date picker
`COUNTRY`	Country selector
`FORMULA`	Calculated field based on other fields
`REFERENCE`	Link to records in another project
`LOOKUP`	Pull data from referenced records
`TIME_DURATION`	Time tracking field
`BUTTON`	Actionable button field
`CURRENCY_CONVERSION`	Currency conversion field

Pagination Parameters

Parameter	Type	Required	Description
`skip`	Int	No	Number of items to skip (default: 0)
`take`	Int	No	Number of items to return (default: 20, max: 500)

Response Fields

CustomField

Field	Type	Description
`id`	String!	Unique identifier
`uid`	String!	Unique user-friendly ID
`name`	String!	Display name of the field
`type`	CustomFieldType!	Type of the custom field
`position`	Float!	Sort order position
`description`	String	Optional field description
`min`	Float	Minimum value (NUMBER, RATING, PERCENT)
`max`	Float	Maximum value (NUMBER, RATING, PERCENT)
`currency`	String	Currency code (CURRENCY type)
`prefix`	String	Prefix for UNIQUE_ID generation
`isDueDate`	Boolean	Whether DATE field represents a due date
`formula`	JSON	Formula configuration (FORMULA type)
`editable`	Boolean	Whether current user can edit this field
`metadata`	JSON	Additional field configuration
`customFieldOptions`	[CustomFieldOption!]	Available options for SELECT types

CustomFieldOption

Field	Type	Description
`id`	String!	Unique identifier
`title`	String!	Display text for the option
`color`	String!	Hex color code
`position`	Float!	Sort order position

PageInfo

Field	Type	Description
`totalItems`	Int	Total number of custom fields
`hasNextPage`	Boolean!	Whether more pages exist
`hasPreviousPage`	Boolean!	Whether previous pages exist
`endCursor`	String	Cursor for pagination (deprecated - use offset-based pagination)

Required Permissions

Custom fields are accessible based on your project role. If you have a custom role with restricted field access, only fields marked as editable for your role will be returned.

Role	Can List Custom Fields
`OWNER`	✅ Yes (all fields)
`ADMIN`	✅ Yes (all fields)
`MEMBER`	✅ Yes (based on role permissions)
`CLIENT`	✅ Yes (based on role permissions)

Error Responses

Project Not Found

{
  "errors": [{
    "message": "Project not found.",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Invalid Field Type

{
  "errors": [{
    "message": "Variable \"$filter\" got invalid value \"INVALID_TYPE\" at \"filter.types[0]\"; Value \"INVALID_TYPE\" does not exist in \"CustomFieldType\" enum.",
    "extensions": {
      "code": "GRAPHQL_VALIDATION_FAILED"
    }
  }]
}

Important Notes

Custom fields are scoped to projects - you must specify a projectId in the filter
The take parameter is capped at 500 items per request for performance
Fields are returned based on user permissions - custom roles may have restricted access
The default sort order is by position ascending, which reflects the order shown in the UI
This query supports single project filtering - for multi-project queries, use the nested CustomFieldQueries interface
Some field types (like FORMULA and REFERENCE) may include additional nested data structures
The editable field indicates whether the current user can modify values for this custom field

Create a Custom Field - Add new custom fields to a project
Update a Custom Field - Modify existing custom field properties
Delete a Custom Field - Remove a custom field from a project
Set Custom Field Value - Set values on records