Create a Custom Field

Use the createCustomField mutation to add a structured data field to a workspace. Custom fields are CustomField objects scoped to a single workspace (a Project in the API). The new field is created at the end of the workspace’s field list and becomes available on every record (Todo) immediately.

The field’s behavior is driven by its type (a CustomFieldType enum value). Each type reads a different subset of the input — for example a CURRENCY field uses currency/min/max, a REFERENCE field uses referenceProjectId, and a LOOKUP field uses lookupOption. See Field Types below for the per-type configuration.

The target workspace comes from the blue-workspace-id request header, not from the input — there is no projectId field on CreateCustomFieldInput.

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: a single-line text field. Only name and type are required.

mutation CreateTextField {
  createCustomField(input: { name: "Customer Name", type: TEXT_SINGLE }) {
    id
    uid
    name
    type
    position
  }
}

Parameters

CreateCustomFieldInput

* Schema-optional, but the resolver requires it for the listed type and returns BAD_USER_INPUT if omitted. See Errors.

SELECT_SINGLE and SELECT_MULTI take no inline options — create the field first, then add options with createCustomFieldOptions.

Response

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "uid": "cf_8h2k9d",
      "name": "Customer Name",
      "type": "TEXT_SINGLE",
      "position": 16384
    }
  }
}

Returns

createCustomField returns the created CustomField. Commonly selected fields:

Field Types

CustomFieldType has 26 values. Most types are created with just name + type; the table notes the extra input each type reads.

Each type has a dedicated page with set/read examples — see Related.

Full examples

Number field with bounds

mutation CreateQuantityField {
  createCustomField(input: { name: "Quantity", type: NUMBER, min: 1, max: 999 }) {
    id
    name
    min
    max
  }
}

Currency field

mutation CreateBudgetField {
  createCustomField(input: { name: "Budget", type: CURRENCY, currency: "EUR", min: 0 }) {
    id
    name
    currency
  }
}

Date field flagged as the due date

mutation CreateDeadlineField {
  createCustomField(input: { name: "Deadline", type: DATE, isDueDate: true }) {
    id
    name
    isDueDate
  }
}

Reference field

Links records to records in another workspace, restricted with referenceFilter (a TodoFilterInput).

mutation CreateDependenciesField {
  createCustomField(
    input: {
      name: "Dependencies"
      type: REFERENCE
      referenceProjectId: "project_123"
      referenceMultiple: true
      referenceFilter: { todoListIds: ["list_123"], showCompleted: false }
    }
  ) {
    id
    name
    referenceMultiple
    referenceProject {
      id
      name
    }
  }
}

Lookup field

Pulls a value from records linked by a REFERENCE field. Point referenceId at the REFERENCE field’s ID and lookupType at what to read; for TODO_CUSTOM_FIELD, also set lookupId to the source field’s ID.

mutation CreateLookupField {
  createCustomField(
    input: {
      name: "Customer Email"
      type: LOOKUP
      lookupOption: {
        referenceId: "field_123"
        lookupId: "field_456"
        lookupType: TODO_CUSTOM_FIELD
      }
    }
  ) {
    id
    name
    customFieldLookupOption {
      lookupType
      reference {
        id
        name
      }
      lookup {
        id
        name
      }
    }
  }
}

Rollup field

Aggregates a field across the records reached through a REFERENCE or REFERENCED_BY field. Rollup fields require a Pro subscription.

mutation CreateTotalField {
  createCustomField(
    input: {
      name: "Total Order Value"
      type: ROLLUP
      rollupOption: {
        sourceType: REFERENCE_FIELD
        sourceFieldId: "field_123"
        aggregateFieldId: "field_456"
        aggregationFunction: SUM
      }
    }
  ) {
    id
    name
    customFieldRollupOption {
      sourceType
      aggregationFunction
    }
  }
}

Assignee field

A custom assignee field, optionally limited to a set of users, roles, or access levels.

mutation CreateReviewerField {
  createCustomField(
    input: {
      name: "Reviewer"
      type: ASSIGNEE
      assigneeMultiple: false
      assigneeNotifyOnAssign: true
      allowedLevels: [ADMIN, MEMBER]
    }
  ) {
    id
    name
    assigneeMultiple
    allowedLevels
  }
}

Unique ID with a sequence

mutation CreateOrderNumberField {
  createCustomField(
    input: {
      name: "Order Number"
      type: UNIQUE_ID
      prefix: "ORD-"
      useSequenceUniqueId: true
      sequenceDigits: 6
      sequenceStartingNumber: 1000
    }
  ) {
    id
    name
    prefix
  }
}

Sequence numbers are assigned by a background job, so existing records receive their IDs shortly after creation.

Time-duration field

Measures elapsed time between a start and end event. Both ends take a CustomFieldTimeDurationInput.

mutation CreateTimeToResolution {
  createCustomField(
    input: {
      name: "Time to Resolution"
      type: TIME_DURATION
      timeDurationDisplay: FULL_DATE_STRING
      timeDurationStartInput: { type: TODO_CREATED_AT, condition: FIRST }
      timeDurationEndInput: { type: TODO_MARKED_AS_COMPLETE, condition: LAST }
    }
  ) {
    id
    name
  }
}

Adding select options

SELECT_SINGLE and SELECT_MULTI fields have no choices until you add them. Create the field, then call createCustomFieldOptions with the new field’s id. It takes one CreateCustomFieldOptionsInput and returns [CustomFieldOption!].

mutation CreateSelectOptions {
  createCustomFieldOptions(
    input: {
      customFieldId: "field_123"
      customFieldOptions: [
        { title: "High", color: "#FF0000", position: 1 }
        { title: "Medium", color: "#FFA500", position: 2 }
        { title: "Low", color: "#00FF00", position: 3 }
      ]
    }
  ) {
    id
    title
    color
    position
  }
}

color and position are optional on each CustomFieldOptionInput. To add a single option, use the singular createCustomFieldOption mutation, which takes customFieldId directly in its input.

Nested input reference

TodoFilterInput

Used by referenceFilter to restrict which records a REFERENCE field can link. All fields are optional; common ones:

TodoFilterInput carries many more fields (date ranges, negation arrays, nested groups). See List Records for the full filter surface.

CustomFieldLookupOptionInput

CustomFieldLookupType values: TODO_DUE_DATE, TODO_CREATED_AT, TODO_UPDATED_AT, TODO_TAG, TODO_ASSIGNEE, TODO_DESCRIPTION, TODO_LIST, TODO_CUSTOM_FIELD. The TODO_REFERENCED_BY value is deprecated — create a REFERENCED_BY field and point a LOOKUP at it instead.

CustomFieldReferencedByOptionInput

Configures a REFERENCED_BY field. All fields are optional; omit them to surface every record that references the current one.

CustomFieldRollupOptionInput

CustomFieldTimeDurationInput

CustomFieldTimeDurationType values: TODO_CREATED_AT, TODO_CUSTOM_FIELD, TODO_DUE_DATE, TODO_MARKED_AS_COMPLETE, TODO_MOVED, TODO_TAG_ADDED, TODO_ASSIGNEE_ADDED.

CustomFieldTimeDurationCondition values: FIRST, LAST.

CustomFieldTimeDurationDisplayType values: FULL_DATE, FULL_DATE_STRING, FULL_DATE_SUBSTRING.

Errors

Permissions

Creating a custom field requires OWNER or ADMIN access to the workspace, and the workspace must be active. MEMBER, CLIENT, COMMENT_ONLY, and VIEW_ONLY roles cannot create fields. ROLLUP fields additionally require the organization to be on a Pro plan.

Related

• List custom fields — read the fields in a workspace.
• Set custom field values — write values onto records.
• Delete a custom field — remove a field.
• Reference field · Lookup field · Currency conversion field — type-specific guides.
• Authentication — request headers and tokens.