API Reference
Apps DocsCommunityNeed Help?

Person (deprecated)

Learn how to read and update the deprecated person column using the platform API

❗

The person column has been deprecated and replaced by the people column. The people column supports assigning multiple users and teams. New boards use the people column by default.

If you are building a new integration, use the people column instead.

The person column stores a reference to a single monday.com user assigned to an item. It uses the item_assignees column type internally and returns values as PersonValue in the GraphQL schema.

Via the API, the person column supports read, filter, update, and clear operations. New person columns cannot be created via the API.

Column TypeImplementation TypeSupported Operations
item_assigneesPersonValue
  • Read: Yes
  • Filter: Yes
  • Create: No (deprecated)
  • Update: Yes
  • Clear: Yes

Queries

Person columns can be queried through the column_values object using an inline fragment on PersonValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on PersonValue {
        id
        person_id
        text
        value
        updated_at
      }
    }
  }
}
const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on PersonValue {
          id
          person_id
          text
          value
          updated_at
        }
      }
    }
  }
`;

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

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

Fields

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

FieldDescription
column Column!The column the value belongs to.
id ID!The column's unique identifier.
person_id IDThe ID of the assigned person. Returns null if no person is assigned.
text StringThe assigned person's name as text. Returns null if no person is assigned.
type ColumnType!The column's type (item_assignees).
updated_at DateThe date when the column value was last updated.
value JSONThe column's raw value as a JSON string. See value structure below.

Value structure

The value field returns a JSON string with this structure:

{
  "changed_at": "2026-03-20T12:00:00.000Z",
  "personsAndTeams": [
    {
      "id": 1234567,
      "kind": "person"
    }
  ]
}
KeyTypeDescription
changed_atstringISO 8601 timestamp of when the value was last changed.
personsAndTeamsarrayArray containing a single object with the assigned person's id (number) and kind (always "person").

Example response

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "person",
            "person_id": "1234567",
            "text": "Jane Smith",
            "value": "{\"changed_at\":\"2026-03-20T12:00:00.000Z\",\"personsAndTeams\":[{\"id\":1234567,\"kind\":\"person\"}]}",
            "updated_at": "2026-03-20T12:00:00Z"
          }
        ]
      }
    ]
  }
}

Filter

You can filter items by the person column using the items_page object. Filters match against user IDs.

OperatorCompare ValueDescription
any_ofAn array of user IDs (e.g., [1234567])Returns items assigned to any of the specified users.
not_any_ofAn array of user IDs (e.g., [1234567])Excludes items assigned to any of the specified users.
is_empty[]Returns items with no person assigned.
is_not_empty[]Returns items that have a person assigned.

Examples

Filter by assigned user

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "person"
            compare_value: [1234567]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on PersonValue {
            person_id
            text
          }
        }
      }
    }
  }
}

Filter by unassigned items

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

Mutations

Update value

You can update a person column using change_simple_column_value or change_multiple_column_values.

change_simple_column_value

Pass the user ID as a string.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "person"
    value: "1234567"
  ) {
    id
    name
  }
}

change_multiple_column_values

Pass a JSON object with the person's id.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"person\": {\"personsAndTeams\": [{\"id\": 1234567, \"kind\": \"person\"}]}}"
  ) {
    id
    name
  }
}
const query = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      board_id: $boardId
      item_id: $itemId
      column_values: $columnValues
    ) {
      id
      name
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    person: {
      personsAndTeams: [{ id: 1234567, kind: "person" }]
    }
  })
};

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

Set person on item creation

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

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

Clear

You can clear a person column using change_simple_column_value or change_multiple_column_values.

change_simple_column_value

Pass an empty string.

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

change_multiple_column_values

Pass null or an empty object.

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

Reading column configuration

The person column has no configurable settings. The settings field returns an empty JSON object.

🚧

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: ["person"]) {
      id
      title
      settings
    }
  }
}

Example settings response

{}

Get column type schema

You can retrieve the JSON schema for the person column's settings programmatically using the get_column_type_schema query.

query {
  get_column_type_schema(
    type: item_assignees
  )
}
{
  "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": {},
            "additionalProperties": false
          }
        }
      }
    }
  }
}

The person column has no configurable settings, so the schema contains an empty properties object.


Updated 4 months ago

Updated 4 months ago