Set Custom Field Values

Set Custom Field Values

Custom fields extend Blue’s standard record structure with business-specific data. This endpoint allows you to set or update values for any custom field on a record. Each field type requires specific parameters to ensure data integrity and proper validation.

Basic Example

mutation SetTextFieldValue {
  setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_xyz789"
    text: "Project specification document"
  })
}

Advanced Example

mutation SetMultipleFieldTypes {
  # Set a date range field
  dateField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_date_001"
    startDate: "2024-01-15T09:00:00Z"
    endDate: "2024-01-31T17:00:00Z"
    timezone: "America/New_York"
  })
  
  # Set a multi-select field
  selectField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_select_002"
    customFieldOptionIds: ["option_high", "option_urgent", "option_client"]
  })
  
  # Set a location field
  locationField: setTodoCustomField(input: {
    todoId: "todo_abc123"
    customFieldId: "field_location_003"
    latitude: 40.7128
    longitude: -74.0060
  })
}

Input Parameters

SetTodoCustomFieldInput

Field Type Examples

Text Fields

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_description"
    text: "Detailed project requirements and specifications"
  })
}

Number Fields

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_budget"
    number: 15000.50
  })
}

Select Fields

# Single Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_priority"
    customFieldOptionId: "option_high"
  })
}

# Multi Select
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_tags"
    customFieldOptionIds: ["option_frontend", "option_urgent", "option_v2"]
  })
}

Date Fields

# Single Date
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_deadline"
    startDate: "2024-12-31T23:59:59Z"
  })
}

# Date Range
mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_project_timeline"
    startDate: "2024-01-01T00:00:00Z"
    endDate: "2024-03-31T23:59:59Z"
    timezone: "UTC"
  })
}

Location Fields

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_office_location"
    latitude: 37.7749
    longitude: -122.4194
  })
}

Currency Fields

mutation {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_invoice_amount"
    number: 5000
    currency: "USD"
  })
}

File Fields

File fields use separate mutations:

# Add a file
mutation {
  createTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

# Remove a file
mutation {
  deleteTodoCustomFieldFile(input: {
    todoId: "todo_123"
    customFieldId: "field_attachments"
    fileUid: "file_upload_789"
  })
}

Setting Values During Record Creation

You can set custom field values when creating a new record:

mutation {
  createTodo(input: {
    todoListId: "list_project_123"
    title: "New Feature Development"
    customFields: [
      {
        customFieldId: "field_priority"
        value: "high"
      },
      {
        customFieldId: "field_estimate"
        value: "8"
      }
    ]
  }) {
    id
    customFields {
      customField {
        name
      }
      value
    }
  }
}

Response Fields

The mutation returns a boolean indicating success:

Required Permissions

Users must have permission to edit both the record and the specific custom field:

For users with custom project roles, the system performs a two-tier check:

1. First, it verifies the user has project-level access
2. Then, it checks if the specific field is marked as editable in their custom role configuration

This means a user might have general project access but still be restricted from editing certain fields based on their custom role.

Error Responses

Custom Field Not Found

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Unauthorized Access

{
  "errors": [{
    "message": "You are not authorized.",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Invalid Field Value

{
  "errors": [{
    "message": "Invalid value for field type NUMBER",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Important Notes

• Upsert Behavior: The mutation creates a new field value if none exists, or updates the existing value
• Type Safety: Only provide parameters that match the field type (e.g., don’t send text for a NUMBER field)
• Side Effects: Setting values triggers:
  • Formula field recalculations
  • Automation rules
  • Webhook notifications
  • Activity log entries
  • Chart updates
• Special Behaviors:
  • CURRENCY fields automatically handle conversion calculations
  • REFERENCE fields update bi-directional relationships
  • FORMULA fields are read-only and cannot be set directly (they’re calculated automatically)
  • LOOKUP fields are read-only and cannot be set directly (they pull data from referenced records)
  • BUTTON fields trigger automation events when “clicked”
• Validation: The API validates that:
  • The record exists in the project
  • The custom field exists in the same project
  • The user has edit permissions
  • The value matches the field type requirements

Value Format Reference

Related Endpoints

• List Custom Fields - Get available custom fields
• Create Custom Field - Add new custom fields
• Get Record Details - Retrieve records with custom field values
• Bulk Update Records - Update multiple records at once