Unique ID Field

A Unique ID field assigns each record a sequential number — the basis for ticket numbers, order IDs, invoice numbers, or any per-workspace counter. It maps to the UNIQUE_ID value of the CustomFieldType enum.

Records are Record objects and workspaces are Workspace objects in the API. A Unique ID field runs in one of two modes: sequence mode (useSequenceUniqueId: true) auto-numbers records in creation order, or manual mode (the default) behaves like a text field you fill in yourself.

Overview

In sequence mode, Blue maintains a counter per field and assigns the next integer to each record. The raw counter value is stored as an integer; the prefix and sequenceDigits you configure are applied at display time in the app, so the API returns the bare sequence number (42), not the formatted string (TASK-042). Assignment runs asynchronously in a background worker that holds a row lock while it numbers records, so concurrent record creation never produces duplicates or gaps from races.

Create

Create a sequence-mode field with the createCustomField mutation. The field is scoped to the workspace in the blue-workspace-id header — there is no projectId argument.

mutation CreateUniqueIdField {
  createCustomField(input: { name: "Ticket Number", type: UNIQUE_ID, useSequenceUniqueId: true }) {
    id
    name
    type
    useSequenceUniqueId
  }
}

To format the displayed value, add a prefix and zero-pad with sequenceDigits, and optionally start the counter at a specific number with sequenceStartingNumber:

mutation CreateFormattedUniqueIdField {
  createCustomField(
    input: {
      name: "Order ID"
      type: UNIQUE_ID
      description: "Auto-generated order identifier"
      useSequenceUniqueId: true
      prefix: "ORD-"
      sequenceDigits: 4
      sequenceStartingNumber: 1000
    }
  ) {
    id
    name
    type
    useSequenceUniqueId
    prefix
    sequenceDigits
    sequenceStartingNumber
  }
}

CreateCustomFieldInput (UNIQUE_ID)

Response

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Order ID",
      "type": "UNIQUE_ID",
      "useSequenceUniqueId": true,
      "prefix": "ORD-",
      "sequenceDigits": 4,
      "sequenceStartingNumber": 1000
    }
  }
}

When the field is created in sequence mode, a background job numbers every existing record in the workspace and continues numbering new records as they are created.

Restart numbering per field value

Set sequenceScope: FIELD and sequenceScopeFieldId to restart numbering for each scope value. The scope field must be in the same workspace. Supported fields are single Reference, Referenced by, single Select, and single Assignee fields.

A Referenced by scope assigns a number only when it currently contains exactly one record. Empty or multi-record results do not identify one group and remain unnumbered.

Set a value

In sequence mode you do not set the value — Blue assigns it automatically. The four lines below apply only to manual mode (useSequenceUniqueId omitted or false), where the field behaves like a text field. Write a value with setRecordCustomField using the text parameter.

mutation SetUniqueIdValue {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", text: "CUSTOM-ID-001" }
  )
}

setRecordCustomField returns a Boolean! — there are no subfields to select. Read the value back with a separate query (see below).

{
  "data": {
    "setRecordCustomField": true
  }
}

SetRecordCustomFieldInput (UNIQUE_ID, manual mode)

Read a value

Read records and their field values with the todos query under recordQueries. TodosFilter.companyIds is required; scope further with projectIds. The query returns a TodosResult (items + pageInfo), and Record.customFields is a list of CustomField objects — there is no wrapper type.

query GetRecordsWithUniqueIds {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], projectIds: ["project_123"] }) {
      items {
        id
        title
        customFields {
          name
          type
          prefix
          sequenceDigits
          sequenceId
          text
          value
        }
      }
      pageInfo {
        totalItems
        hasNextPage
      }
    }
  }
}

On each CustomField element:

• Sequence mode: sequenceId (and value) hold the raw integer counter. prefix/sequenceDigits come back as the field’s display config — apply them yourself to render ORD-0042. text is null.
• Manual mode: text holds the value you set; sequenceId and value are null.

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "title": "Fix login issue",
            "customFields": [
              {
                "name": "Order ID",
                "type": "UNIQUE_ID",
                "prefix": "ORD-",
                "sequenceDigits": 4,
                "sequenceId": 42,
                "text": null,
                "value": 42
              }
            ]
          }
        ],
        "pageInfo": { "totalItems": 1, "hasNextPage": false }
      }
    }
  }
}

Returns (CustomField, UNIQUE_ID)

Notes

• The API returns the bare number, not the formatted string. prefix and sequenceDigits are display config; combine them client-side (`${prefix}${String(sequenceId).padStart(sequenceDigits, '0')}`) to reproduce what the app shows.
• Assignment is asynchronous. New records get a number shortly after creation, not in the same transaction. Don’t assume sequenceId is populated the instant a record is created.
• Sequences never reuse numbers. Deleting a record leaves a gap; the counter only moves forward. sequenceStartingNumber sets the first value only — once the counter advances, later edits to it don’t renumber existing records.
• Sequences are per field. Each UNIQUE_ID field keeps its own counter, scoped to its workspace.
• enableBulkAction is an optional CreateCustomFieldInput flag that exposes a field in bulk actions; UNIQUE_ID supports it.

Permissions

Creating or editing a Unique ID field requires the OWNER or ADMIN role on the workspace. Setting a manual value and reading values use standard record edit and view permissions.

Errors

Related

• Create a Custom Field
• Set Custom Field Values
• List Custom Fields
• Number Field
• Single-Line Text Field
• Custom Fields Overview