Create a Custom Field

Create a Custom Field

Custom fields allow you to tailor Blue to your specific business needs by adding structured data fields to your records. This endpoint creates a new custom field with configurations specific to each field type.

Basic Example

mutation CreateTextField {
  createCustomField(input: {
    name: "Customer Name"
    type: TEXT_SINGLE
    description: "Primary customer contact name"
  }) {
    id
    uid
    name
    type
    position
  }
}

Advanced Example

mutation CreateAdvancedField {
  createCustomField(input: {
    name: "Project Budget"
    type: CURRENCY
    description: "Total allocated budget for this project"
    currency: "USD"
    min: 0
    max: 1000000
  }) {
    id
    uid
    name
    type
    currency
    min
    max
    position
    createdAt
  }
}

Input Parameters

CreateCustomFieldInput

CustomFieldType Values

Field Type Configuration Examples

Number Field with Constraints

mutation CreateQuantityField {
  createCustomField(input: {
    name: "Quantity"
    type: NUMBER
    description: "Number of items"
    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
    min
  }
}

Date Field with Due Date Flag

mutation CreateDeadlineField {
  createCustomField(input: {
    name: "Project Deadline"
    type: DATE
    isDueDate: true
    description: "When this project must be completed"
  }) {
    id
    name
    isDueDate
  }
}

Reference Field

mutation CreateRelatedTasksField {
  createCustomField(input: {
    name: "Dependencies"
    type: REFERENCE
    referenceProjectId: "proj_abc123"
    referenceMultiple: true
    referenceFilter: {
      statusIds: ["status_open", "status_inprogress"]
    }
  }) {
    id
    name
    referenceProjectId
    referenceMultiple
  }
}

Lookup Field

mutation CreateLookupField {
  createCustomField(input: {
    name: "Customer Email"
    type: LOOKUP
    lookupOption: {
      referenceId: "field_customer_ref"
      lookupId: "field_email"
      lookupType: TODO_CUSTOM_FIELD
    }
  }) {
    id
    name
    customFieldLookupOption {
      referenceId
      lookupId
      lookupType
    }
  }
}

Unique ID with Sequence

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

Time Duration Field

mutation CreateTimeTrackingField {
  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: FIRST
    }
  }) {
    id
    name
  }
}

Valid Time Duration Types

• TODO_CREATED_AT - When the record was created
• TODO_CUSTOM_FIELD - When a custom field changes
• TODO_DUE_DATE - When due date is set/changed
• TODO_MARKED_AS_COMPLETE - When record is marked complete
• TODO_MOVED - When record is moved to different list
• TODO_TAG_ADDED - When a tag is added
• TODO_ASSIGNEE_ADDED - When an assignee is added

Creating Select Options

After creating a SELECT_SINGLE or SELECT_MULTI field, add options:

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

Response Fields

CustomField

Required Permissions

Creating custom fields requires project access:

Note: Custom roles may have additional restrictions on field management.

Error Responses

Invalid Field Type

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

Reference Project Not Found

{
  "errors": [{
    "message": "Reference project not found or access denied",
    "extensions": {
      "code": "PROJECT_NOT_FOUND"
    }
  }]
}

Missing Required Configuration

{
  "errors": [{
    "message": "REFERENCE fields require referenceProjectId",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Important Notes

• Field Position: Automatically calculated to appear at the end of existing fields
• Field Limits: Projects may have limits on the number of custom fields
• Immediate Availability: Created fields are immediately available for use
• Side Effects: Creating a field triggers:
  • Activity log entry
  • Real-time updates to connected users
  • Webhook notifications
  • Background jobs for FORMULA, LOOKUP, and UNIQUE_ID fields
• Special Considerations:
  • REFERENCE fields require access to the target project
  • LOOKUP fields depend on existing REFERENCE fields
  • FORMULA fields cannot reference themselves
  • UNIQUE_ID sequences process asynchronously
  • SELECT fields need options created separately
• Naming: Field names should be clear and descriptive as they appear in the UI

Related Endpoints

• List Custom Fields - View existing custom fields
• Update Custom Field - Modify field properties
• Delete Custom Field - Remove a custom field
• Create Field Options - Add options to select fields
• Set Custom Field Values - Set values on records