Lookup Custom Field

Lookup custom fields automatically pull data from records referenced by Reference fields, displaying information from linked records without manual copying. They update automatically when referenced data changes.

Basic Example

Create a lookup field to display tags from referenced records:

mutation CreateLookupField {
  createCustomField(input: {
    name: "Related Todo Tags"
    type: LOOKUP
    lookupOption: {
      referenceId: "reference_field_id"
      lookupType: TODO_TAG
    }
    description: "Tags from related todos"
  }) {
    id
    name
    type
    lookupOption
  }
}

Advanced Example

Create a lookup field to extract custom field values from referenced records:

mutation CreateCustomFieldLookup {
  createCustomField(input: {
    name: "Referenced Budget Values"
    type: LOOKUP
    lookupOption: {
      referenceId: "project_reference_field_id"
      lookupId: "budget_custom_field_id"
      lookupType: TODO_CUSTOM_FIELD
    }
    description: "Budget values from referenced todos"
  }) {
    id
    name
    type
    lookupOption
  }
}

Input Parameters

CreateCustomFieldInput

Lookup Configuration

CustomFieldLookupOptionInput

Lookup Types

CustomFieldLookupType Values

Response Fields

CustomField Response (for lookup fields)

CustomFieldLookupOption Structure

How Lookups Work

1. Data Extraction: Lookups extract specific data from all records linked through a reference field
2. Automatic Updates: When referenced records change, lookup values update automatically
3. Read-Only: Lookup fields cannot be edited directly - they always reflect current referenced data
4. No Calculations: Lookups extract and display data as-is without aggregations or calculations

TODO_CUSTOM_FIELD Lookups

When using TODO_CUSTOM_FIELD type, you must specify which custom field to extract using the lookupId parameter:

mutation CreateCustomFieldValueLookup {
  createCustomField(input: {
    name: "Project Status Values"
    type: LOOKUP
    lookupOption: {
      referenceId: "linked_projects_reference_field"
      lookupId: "status_custom_field_id"
      lookupType: TODO_CUSTOM_FIELD
    }
  }) {
    id
  }
}

This extracts the values of the specified custom field from all referenced records.

Querying Lookup Data

query GetLookupValues {
  todo(id: "todo_123") {
    customFields {
      id
      customField {
        name
        type
        customFieldLookupOption {
          lookupType
          lookupResult
          reference {
            id
            name
          }
          lookup {
            id
            name
            type
          }
        }
      }
    }
  }
}

Example Lookup Results

Tag Lookup Result

{
  "lookupResult": [
    {
      "id": "tag_123",
      "title": "urgent",
      "color": "#ff0000"
    },
    {
      "id": "tag_456",
      "title": "development",
      "color": "#00ff00"
    }
  ]
}

Assignee Lookup Result

{
  "lookupResult": [
    {
      "id": "user_123",
      "name": "John Doe",
      "email": "[email protected]"
    }
  ]
}

Custom Field Lookup Result

Results vary based on the custom field type being looked up. For example, a currency field lookup might return:

{
  "lookupResult": [
    {
      "value": 1000,
      "currency": "USD"
    },
    {
      "value": 2500,
      "currency": "EUR"
    }
  ]
}

Required Permissions

Important: Users must have view permissions on both the current project and the referenced project to see lookup results.

Error Responses

Invalid Reference Field

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

Circular Lookup Detected

{
  "errors": [{
    "message": "Circular lookup detected",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Missing Lookup ID for TODO_CUSTOM_FIELD

{
  "errors": [{
    "message": "lookupId is required when lookupType is TODO_CUSTOM_FIELD",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

Best Practices

1. Clear Naming: Use descriptive names that indicate what data is being looked up
2. Appropriate Types: Choose the lookup type that matches your data needs
3. Performance: Lookups process all referenced records, so be mindful of reference fields with many links
4. Permissions: Ensure users have access to referenced projects for lookups to work

Common Use Cases

Cross-Project Visibility

Display tags, assignees, or statuses from related projects without manual synchronization.

Dependency Tracking

Show due dates or completion status of tasks that current work depends on.

Resource Overview

Display all team members assigned to referenced tasks for resource planning.

Status Aggregation

Collect all unique statuses from related tasks to see project health at a glance.

Limitations

• Lookup fields are read-only and cannot be edited directly
• No aggregation functions (SUM, COUNT, AVG) - lookups only extract data
• No filtering options - all referenced records are included
• Circular lookup chains are prevented to avoid infinite loops
• Results reflect current data and update automatically

Related Resources

• Reference Fields - Create links to records for lookup sources
• Custom Field Values - Set values on editable custom fields
• List Custom Fields - Query all custom fields in a project