Button Field

A button field renders a clickable button on a record. Unlike every other field type, it stores no value — clicking it fires a CUSTOM_FIELD_BUTTON_CLICKED event that your automations can listen for. Use it to give people a one-click way to kick off a workflow (send an invoice, sync to a CRM, notify a channel) from inside a record.

Button fields are CustomField objects with type: BUTTON. Records are Record objects, and workspaces are Workspace objects in the API.

Overview

BUTTON is a value of the CustomFieldType enum. A button field carries presentation config (buttonType, buttonConfirmText, buttonColor) and, optionally, the enableBulkAction flag that lets it be clicked across many records at once. None of these affect the API contract — the click itself always executes immediately.

Create

Custom fields are scoped to a workspace by the blue-workspace-id header — there is no projectId input field. Pass type: BUTTON and a name:

mutation CreateButtonField {
  createCustomField(input: { name: "Send Invoice", type: BUTTON }) {
    id
    name
    type
  }
}

Add the optional confirmation and styling config. buttonType and buttonConfirmText are UI hints for clients that want to show a confirmation dialog; buttonColor is a hex string for the button’s color:

mutation CreateConfirmingButton {
  createCustomField(
    input: {
      name: "Delete All Attachments"
      type: BUTTON
      description: "Permanently removes every attachment on this record"
      buttonType: "hardConfirmation"
      buttonConfirmText: "DELETE"
      buttonColor: "#E5484D"
      enableBulkAction: true
    }
  ) {
    id
    name
    type
    buttonType
    buttonConfirmText
    buttonColor
  }
}

CreateCustomFieldInput (button fields)

CreateCustomFieldInput carries config for every field type; only the parameters above apply to buttons. See Create a Custom Field for the full input.

Set a value

Buttons have no value to set. “Setting” a button means clicking it. Call setRecordCustomField with just the todoId and customFieldId — clicking fires the CUSTOM_FIELD_BUTTON_CLICKED automation trigger for that record. The mutation returns Boolean!:

mutation ClickButton {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123" })
}

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

Click across many records

When the field was created with enableBulkAction: true, use bulkClickButton to click it on every record matching a filter or an explicit list of IDs. It returns a BulkOperationResult with how many records were processed:

mutation BulkClickButton {
  bulkClickButton(input: { customFieldId: "field_123", todoIds: ["todo_123", "todo_456"] }) {
    success
    count
  }
}

{ "data": { "bulkClickButton": { "success": true, "count": 2 } } }

Provide either todoIds, a filter, or both — at least one is required. Bulk clicks are capped at 1,000 records per call.

BulkClickButtonInput

Read a value

A button field never stores data. When you read it on a record, CustomField.value is null and there are no selected options, numbers, or text to read back. Clicks are recorded in the record’s action history, not as a field value.

query ReadButton {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], todoListIds: ["list_123"] }) {
      items {
        id
        customFields {
          name
          type
          value
        }
      }
    }
  }
}

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "customFields": [{ "name": "Send Invoice", "type": "BUTTON", "value": null }]
          }
        ]
      }
    }
  }
}

Notes

• No stored value. Each click emits an event and records an action in the record’s history; it never modifies a field value. Don’t expect value, selectedOption, or text to be populated.
• Automation linkage is behavior, not schema. The CUSTOM_FIELD_BUTTON_CLICKED trigger and the button_clicked action are wired up in the automation engine — they aren’t fields you set on the button itself. Build the automation that listens for the click with Create an automation.
• Bulk requires opt-in. bulkClickButton rejects a field that wasn’t created (or edited) with enableBulkAction: true, and rejects any field whose type isn’t BUTTON.

Errors

Related

• Create a Custom Field
• Set Custom Field Values
• Custom Fields Overview
• Create an automation