The people column assigns one or more users or teams to an item. Each entry in the column is a PeopleEntity with an id and a kind (person, team, or agent).

Via the API, the people column supports read, filter, update, and clear operations.

Column Type	Implementation Type	Supported Operations
`people`	`PeopleValue`	Read: Yes Filter: Yes Update: Yes Clear: Yes

Queries

People columns can be queried through the column_values field on items using an inline fragment on PeopleValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on PeopleValue {
        id
        text
        persons_and_teams {
          id
          kind
        }
        value
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on PeopleValue {
          id
          text
          persons_and_teams {
            id
            kind
          }
          value
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890, 9876543210] };

const response = await mondayApiClient.request(query, variables);

Fields

You can use the following fields to specify what information your PeopleValue implementation will return.

Field	Description
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
is_leaf `Boolean!`	Whether the item has no subitems. Returns `false` for parent items with subitems.
persons_and_teams `[PeopleEntity!]`	The assigned people or teams. Each entity has an `id` and `kind` (`person`, `team`, or `agent`).
text `String`	The column's value as text (comma-separated names). Returns `""` if the column has an empty value.
type `ColumnType!`	The column's type (`people`).
updated_at `Date`	The column's last updated date.
value `JSON`	The column's JSON-formatted raw value. Contains `personsAndTeams` array and `changed_at` timestamp.

PeopleEntity

Each entry in the persons_and_teams array is a PeopleEntity object.

Field	Type	Description
id	`ID!`	The unique identifier of the person or team.
kind	`Kind`	The type of entity: `person` or `team`.

Example response

{
  "data": {
    "items": [
      {
        "name": "Design homepage",
        "column_values": [
          {
            "id": "people",
            "text": "Daniel Hai, Roy Mann",
            "persons_and_teams": [
              {
                "id": "48202303",
                "kind": "person"
              },
              {
                "id": "331",
                "kind": "person"
              }
            ],
            "value": "{\"changed_at\":\"2026-03-21T09:03:56.017Z\",\"personsAndTeams\":[{\"id\":48202303,\"kind\":\"person\"},{\"id\":331,\"kind\":\"person\"}]}",
            "updated_at": "2026-03-21T09:03:56+00:00"
          }
        ]
      }
    ]
  }
}

Filter

You can filter items by people values using the items_page object. The people column supports the following operators:

Operator	Compare Value	Description
`any_of`	`["person-123456"]` or `["assigned_to_me"]` or `["person-0"]`	Returns items assigned to any of the specified people. Use `"person-USERID"` format for user IDs, `"assigned_to_me"` for the API caller, or `"person-0"` for blank values.
`not_any_of`	`["person-123456"]` or `["assigned_to_me"]` or `["person-0"]`	Excludes items assigned to any of the specified people.
`is_empty`	`[]`	Returns items with no people assigned.
`is_not_empty`	`[]`	Returns items that have at least one person or team assigned.
`contains_text`	A partial or full name string (e.g., `"Daniel"`)	Returns items where an assigned person's name contains the specified text.
`not_contains_text`	A partial or full name string	Excludes items where an assigned person's name contains the specified text.
`contains_terms`	One or more keywords (e.g., `"Daniel Hai"`)	Matches names by keyword(s) in any order.
`starts_with`	A string prefix (e.g., `"Dan"`)	Returns items where an assigned person's name starts with the specified text.
`ends_with`	A string suffix (e.g., `"Mann"`)	Returns items where an assigned person's name ends with the specified text.

📘
The any_of and not_any_of operators require the "person-USERID" format for user IDs. For example, use "person-48202303", not "48202303".

Examples

Filter by specific person

This example returns items assigned to a specific user.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["person-48202303"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on PeopleValue {
            text
            persons_and_teams {
              id
              kind
            }
          }
        }
      }
    }
  }
}

Filter by current API user

This example returns items assigned to the user making the API call.

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

Filter by name text

This example returns items where an assigned person's name contains "Daniel".

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

Filter by empty people column

This example returns items with no people assigned.

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

Mutations

Update value

You can update a people column value using change_simple_column_value or change_multiple_column_values. You can send values as simple strings or JSON objects, depending on the mutation you choose.

🚧
Updating a people column replaces all currently assigned people. To add a person without removing existing ones, first read the current value, then send the full list including the new person.

`change_simple_column_value`

Pass a comma-separated list of user IDs as a string in value.

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

`change_multiple_column_values`

Send people and/or team IDs as a JSON object with a personsAndTeams array. Each entry requires an id (integer) and kind ("person" or "team").

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

Set on item creation

You can assign people when creating an item by passing the people column value in the column_values argument.

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"people\": {\"personsAndTeams\": [{\"id\": 48202303, \"kind\": \"person\"}]}}"
  ) {
    id
    name
  }
}

Clear

You can clear a people column using change_simple_column_value or change_multiple_column_values.

`change_simple_column_value`

Pass an empty string in value.

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

`change_multiple_column_values`

Pass null in column_values.

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

Reading column configuration

To understand a people column's settings, you can query its settings field.

🚧
The settings_str field is deprecated as of API version 2025-10. Use the typed settings object instead, which returns structured JSON rather than a JSON-encoded string.

query {
  boards(ids: 1234567890) {
    columns(ids: ["people"]) {
      id
      title
      settings
    }
  }
}

`settings` response structure

The settings field returns a typed JSON object. For people columns, the settings object is typically empty ({}) when using default configuration.

When settings are customized, the response contains these keys:

Key	Type	Description
`hide_footer`	`boolean`	Whether to hide the footer in the column cell.
`max_people_allowed`	`string`	Maximum number of people allowed (`"0"` means unlimited).

Example `settings` response

{}

📘
People columns use an empty settings object by default. The max_people_allowed and hide_footer settings only appear when explicitly configured.

Get column type schema

You can retrieve the JSON schema for the people column's settings programmatically using the get_column_type_schema query. This returns the structure, validation rules, and available properties for the column's configuration.

query {
  get_column_type_schema(
    type: people
  )
}

{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {
              "hide_footer": {
                "type": "boolean",
                "description": "Whether to hide the footer"
              },
              "max_people_allowed": {
                "type": "string",
                "description": "Maximum number of people allowed (0 means unlimited)"
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

The response includes property names, types, constraints (such as max lengths and allowed values), and descriptions for each setting. You can use this to validate column settings, dynamically generate UIs, or give context to AI agents. Learn more about the schema response format.

Queries

Fields

PeopleEntity

Example response

Filter

Examples

Filter by specific person

Filter by current API user

Filter by name text

Filter by empty people column

Mutations

Update value

change_simple_column_value

change_multiple_column_values

Set on item creation

Clear

change_simple_column_value

change_multiple_column_values

Reading column configuration

settings response structure

Example settings response

Get column type schema

`change_simple_column_value`

`change_multiple_column_values`

`change_simple_column_value`

`change_multiple_column_values`

`settings` response structure

Example `settings` response