List Custom Fields

Use the customFields query to read the custom fields defined in a workspace, optionally filtered by field type and sorted. Custom fields are CustomField objects scoped to a single workspace (a Project in the API). The result is a CustomFieldPagination page of items plus pageInfo.

The workspace is resolved from the filter.projectId argument, or — when that is omitted — from the blue-workspace-id request header. Only fields visible to the calling user’s project role are returned: if the user has a custom role with restricted field access, fields hidden from that role are excluded from items.

POST https://api.blue.app/graphql
blue-token-id: YOUR_TOKEN_ID
blue-token-secret: YOUR_TOKEN_SECRET
blue-org-id: YOUR_ORG_ID
blue-workspace-id: project_123

Company and project headers accept an ID or a slug. Header names are case-insensitive. See Authentication for the full header reference.

Request

The smallest call that works. With the blue-workspace-id header set, filter is optional; passing filter.projectId overrides the header.

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

Parameters

The customFields query takes these arguments:

CustomFieldFilterInput

CustomFieldSort

A single enum value (not a list on this query).

CustomFieldType

The type discriminates how a field stores and renders its value. Each value also drives which type-specific fields are populated on the returned CustomField (for example currency on CURRENCY, customFieldOptions on the SELECT_* types).

Response

{
  "data": {
    "customFields": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "uid": "cf_qZ1r8",
          "name": "Stage",
          "type": "SELECT_SINGLE",
          "position": 1
        },
        {
          "id": "clm4n8r2p000108l0d3k1f9aa",
          "uid": "cf_7Hb2k",
          "name": "Deal Size",
          "type": "CURRENCY",
          "position": 2
        }
      ],
      "pageInfo": {
        "totalItems": 2,
        "hasNextPage": false
      }
    }
  }
}

CustomFieldPagination

CustomField

The fields below cover the common cases. CustomField exposes many more type-specific outputs (see Field-type outputs).

Field-type outputs

When you fetch fields in the context of a specific record, these populate with that record’s value. They are otherwise null.

CustomFieldOption

Selectable options on SELECT_* and BUTTON fields. Commonly selected fields:

The type also exposes buttonType, buttonConfirmText, currencyConversionFrom, currencyConversionTo, createdAt, and updatedAt for button and currency-conversion fields.

PageInfo

Full example

Filter by type, page with skip/take, and select the options for select fields plus access flags.

query ListSelectFields {
  customFields(
    filter: { projectId: "project_123", types: [SELECT_SINGLE, SELECT_MULTI] }
    sort: name_ASC
    skip: 0
    take: 50
  ) {
    items {
      id
      uid
      name
      type
      position
      description
      viewable
      editable
      customFieldOptions {
        id
        title
        color
        position
      }
    }
    pageInfo {
      totalItems
      totalPages
      page
      hasNextPage
      hasPreviousPage
    }
  }
}

To read fields across multiple workspaces, or to search fields by name, use the nested customFieldQueries.customFields query instead. It takes a CustomFieldsFilterInput where companyIds is required and projectIds is an optional plural list, adds a search argument, accepts sort as a list ([CustomFieldSort!]), supports a distinct argument, and defaults take to 20.

query SearchCustomFields {
  customFieldQueries {
    customFields(
      filter: { companyIds: ["company_123"], projectIds: ["project_123"], search: "amount" }
      sort: [name_ASC]
      take: 20
    ) {
      items {
        id
        name
        type
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

Errors

Permissions

Any project member can list a workspace’s custom fields. Field-level visibility is enforced by the caller’s project role: a field is included only when it is visible to that role. The returned viewable and editable flags report whether the caller can see and edit each field’s values, and workspaceUserRole exposes the role used to resolve them.

Related

• Create a custom field — add a field to a workspace.
• Set custom field values — write values onto records.
• Delete a custom field — remove a field.
• Custom fields overview — the full list of field types and guides.
• Authentication — request headers and tokens.