--- title: "List person records" method: POST path: "/v2/objects/people/records/query" tags: ["People"] --- # List person records `POST /v2/objects/people/records/query` Lists person records, with the option to filter and sort results. Required scopes: `record_permission:read`, `object_configuration:read`. ## Request body - object - `filter` object — An object used to filter results to a subset of records. See the [full guide to filtering and sorting here](/rest-api/how-to/filtering-and-sorting). - `sorts` union[] — An object used to sort results. See the [full guide to filtering and sorting here](/rest-api/how-to/filtering-and-sorting). - union - object — Sort by attribute - `direction` 'asc' | 'desc', required — The direction to sort the results by. - `attribute` string, required — A slug or ID to identify the attribute to sort by. - `field` string — Which field on the value to sort by e.g. "last_name" on a name value. - object — Sort by path - `direction` 'asc' | 'desc', required — The direction to sort the results by. - `path` array[], required — You may use the `path` property to traverse record reference attributes and parent records on list entries. `path` accepts an array of tuples where the first element of each tuple is the slug or ID of a list/object, and the second element is the slug or ID of an attribute on that list/object. The first element of the first tuple must correspond to the list or object that you are querying. For example, if you wanted to sort by the name of the parent record (a company) on a list with the slug "sales", you would pass the value `[['sales', 'parent_record'], ['companies', 'name']]`. - union[] - union - … - `field` string — Which field on the value to sort by e.g. "last_name" on a name value. - `limit` number — The maximum number of results to return. Defaults to 500. See the [full guide to pagination here](/rest-api/how-to/pagination). - `offset` number — The number of results to skip over before returning. Defaults to 0. See the [full guide to pagination here](/rest-api/how-to/pagination). ## Response `200` Success - object — Success - `data` object[], required - `id` object, required - `workspace_id` string, uuid, required — A UUID identifying the workspace this record belongs to. - `object_id` string, uuid, required — A UUID identifying the object this record belongs to. - `record_id` string, uuid, required — A UUID identifying this record. - `created_at` string, required — When this record was created. - `web_url` string, uri, required — A URL that links directly to the record page in the Attio web application. - `values` object, required — An object with `attribute_slug` keys, and an array of value objects as the values. Attributes slugs (for example `email_addresses` or `name`) can be used, including custom attribute slugs. - `email_addresses` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `original_email_address` string, required - `email_address` string, required - `email_domain` string, required - `email_root_domain` string, required - `email_local_specifier` string, required - `attribute_type` 'email-address', required — The attribute type of the value. - `name` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `first_name` string, required — The first name. - `last_name` string, required — The last name. - `full_name` string, required — The full name. - `attribute_type` 'personal-name', required — The attribute type of the value. - `description` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `avatar_url` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `job_title` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `phone_numbers` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `original_phone_number` string, required — The raw, original phone number, as inputted. - `country_code` 'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CW' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GG' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IM' | 'IL' | 'IT' | 'JM' | 'JP' | 'JE' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MK' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'ME' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'AN' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'BL' | 'SH' | 'KN' | 'LC' | 'MF' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'SS' | 'RS' | 'SC' | 'SL' | 'SG' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW', required — The ISO 3166-1 alpha-2 country code representing the country that this phone number belongs to. - `phone_number` string, required - `attribute_type` 'phone-number', required — The attribute type of the value. - `linkedin` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `twitter` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `facebook` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `instagram` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `angellist` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` string, required — A raw text field. Values are limited to 10MB. - `attribute_type` 'text', required — The attribute type of the value. - `primary_location` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `line_1` string, nullable, required — The first line of the address. Note that this value is not currently represented in the UI but will be persisted and readable through API calls. - `line_2` string, nullable, required — The second line of the address. Note that this value is not currently represented in the UI but will be persisted and readable through API calls. - `line_3` string, nullable, required — The third line of the address. Note that this value is not currently represented in the UI but will be persisted and readable through API calls. - `line_4` string, nullable, required — The fourth line of the address. Note that this value is not currently represented in the UI but will be persisted and readable through API calls. - `locality` string, nullable, required — The town, neighborhood or area the location is in. - `region` string, nullable, required — The state, county, province or region that the location is in. - `postcode` string, nullable, required — The postcode or zip code for the location. Note that this value is not currently represented in the UI but will be persisted and readable through API calls.} - `country_code` 'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CW' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GG' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IM' | 'IL' | 'IT' | 'JM' | 'JP' | 'JE' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KR' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MK' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'ME' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'AN' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'BL' | 'SH' | 'KN' | 'LC' | 'MF' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'SS' | 'RS' | 'SC' | 'SL' | 'SG' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW', nullable, required — The ISO 3166-1 alpha-2 country code for the country this location is in. - `latitude` string, nullable, required — The latitude of the location. Validated by the regular expression `/^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?)$/`. Note that this value is not currently represented in the UI but will be persisted and readable through API calls.} - `longitude` string, nullable, required — The longitude of the location. Validated by the regular expression `/^[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$/` - `attribute_type` 'location', required — The attribute type of the value. - `twitter_follower_count` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `value` number, required — Numbers are persisted as 64 bit floats. - `attribute_type` 'number', required — The attribute type of the value. - `company` object[] - `active_from` string, date-time, required — The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. - `active_until` string, date-time, nullable, required — The point in time at which this value was deactivated. If `null`, the value is active. - `created_by_actor` object, required — The actor that created this value. - `id` string, nullable — An ID to identify the actor. - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors). - `target_object` string, required — A slug identifying the object that the referenced record belongs to. - `target_record_id` string, uuid, required — A UUID to identify the referenced record. - `attribute_type` 'record-reference', required — The attribute type of the value. ## Other responses - `400` — Bad Request - `404` — Not Found --- [API](https://skmtc.net/attio/apis/attio-standard-objects.md) · [All operations](https://skmtc.net/attio/apis/attio-standard-objects/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/attio/attio-standard-objects/versions/d6d3cac7a275/schema)