The people column represents a person(s) who is assigned items. The API allows you to read, filter, update, and clear the people column.

Read a people column

You can query the people column using the column_values object that enables you to return column-specific subfields by sending a fragment in your query. Values for the people column are of the PeopleValue type.

query {
  items (ids:[1234567890, 9876543210]) {
    column_values {
      ... on PeopleValue {
        persons_and_teams
      }
    }
  }
}

Fields

Field	Description
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
persons_and_teams `[PeopleEntity!]`	The column's people or team values.
text `String`	The column's value as text. This field will return `""` if the column has an empty value.
type `ColumnType!`	The column's type.
updated_at `Date`	The column's last updated date.
value `JSON`	The column's JSON-formatted raw value.

Filter a people column

Using the items_page object, you can easily filter a board's items by specific columns or column values. The table below contains the people column's supported operators and compare values.

Operators	Compare Values
`any_of`	The user IDs to filter by (`"person-123456"`) `"assigned_to_me"` (items assigned to the user making the API call) `"person-0"` (blank values)
`not_any_of`	The user IDs to filter by (`"person-123456"`) `"assigned_to_me"` (items assigned to the user making the API call) `"person-0"` (blank values)
`is_empty`	`[]`
`is_not_empty`	`[]`
`contains_text`	The partial or whole name to filter by (exactly as written)
`not_contains_text`	The partial or whole name to filter by (exactly as written)
`contains_terms`	The partial or whole name to filter by (in any order)
`starts_with`	The value the item starts with
`ends_with`	The value the item ends with

Examples

The following example returns all items on the specified board assigned to anyone except the user running the query.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["assigned_to_me"]
            operator: not_any_of
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Update a people column

You can update a people column using the change_simple_column_value mutation and sending a simple string in the value argument. You can also use the change_multiple_column_values mutation and pass a JSON string in the column_values argument.

Simple strings

To update a people column, send a string of user IDs separated by a comma that you want to add to the column.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "people"
    value: "123456, 654321"
  ) {
    id
  }
}

JSON

To update a people column, send an array with the people or team IDs you want to add to the column.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"people\": {\"personsAndTeams\": [{\"id\": 4616666, \"kind\": \"person\"}, {\"id\": 51166, \"kind\": \"team\"}]}}"
  ) {
    id
  }
}

Clear a people column

You have two options to clear a people column. First, you can use the change_multiple_column_values mutation and pass null, an empty string, or an empty object in the column_values argument.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"people\": null}"
  ) {
    id
  }
}

You can also use the change_simple_column_value mutation and pass an empty string in the value argument.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "people"
    value: ""
  ) {
    id
  }
}