> ## Documentation Index > Fetch the complete documentation index at: https://docs.attio.com/llms.txt > Use this file to discover all available pages before exploring further. # List deal records > Lists deal records, with the option to filter and sort results. Required scopes: `record_permission:read`, `object_configuration:read`. ## OpenAPI ````yaml https://api.attio.com/openapi/standard-objects post /v2/objects/deals/records/query openapi: 3.1.0 info: title: Attio Standard Objects version: 2.0.0 servers: - url: https://api.attio.com description: Production security: - oauth2: [] paths: /v2/objects/deals/records/query: post: tags: - Deals summary: List deal records description: |- Lists deal records, with the option to filter and sort results. Required scopes: `record_permission:read`, `object_configuration:read`. requestBody: required: true content: application/json: schema: type: object properties: filter: type: object description: >- An object used to filter results to a subset of records. See the [full guide to filtering and sorting here](/rest-api/guides/filtering-and-sorting). additionalProperties: true example: $and: - path: - - deals - associated_company - - companies - domains constraints: domain: fundstack.com sorts: type: array items: anyOf: - type: object properties: direction: type: string enum: - asc - desc description: The direction to sort the results by. attribute: type: string description: A slug or ID to identify the attribute to sort by. field: type: string description: >- Which field on the value to sort by e.g. "last_name" on a name value. required: - direction - attribute description: Sort by attribute - type: object properties: direction: type: string enum: - asc - desc description: The direction to sort the results by. path: type: array items: type: array items: anyOf: - type: string description: >- The slug or ID of the object e.g. "people". - type: string description: >- A slug or ID to identify the attribute to sort by. minItems: 2 maxItems: 2 description: >- 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']]`. field: type: string description: >- Which field on the value to sort by e.g. "last_name" on a name value. required: - direction - path description: Sort by path description: >- An object used to sort results. See the [full guide to filtering and sorting here](/rest-api/guides/filtering-and-sorting). example: - direction: asc attribute: name field: last_name limit: type: number description: >- The maximum number of results to return. Defaults to 500. See the [full guide to pagination here](/rest-api/guides/pagination). example: 500 offset: type: number description: >- The number of results to skip over before returning. Defaults to 0. See the [full guide to pagination here](/rest-api/guides/pagination). example: 0 responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: object properties: workspace_id: type: string format: uuid description: >- A UUID identifying the workspace this record belongs to. example: 14beef7a-99f7-4534-a87e-70b564330a4c object_id: type: string format: uuid description: >- A UUID identifying the object this record belongs to. example: 97052eb9-e65e-443f-a297-f2d9a4a7f795 record_id: type: string format: uuid description: A UUID identifying this record. example: bf071e1f-6035-429d-b874-d83ea64ea13b required: - workspace_id - object_id - record_id created_at: type: string description: When this record was created. example: '2022-11-21T13:22:49.061281000Z' web_url: type: string format: uri description: >- A URL that links directly to the record page in the Attio web application. example: >- https://app.attio.com/salarya/person/bf071e1f-6035-429d-b874-d83ea64ea13b values: type: object properties: name: type: array items: type: object properties: active_from: type: string format: date-time description: >- The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. example: '2023-01-01T15:00:00.000000000Z' active_until: type: - string - 'null' format: date-time description: >- The point in time at which this value was deactivated. If `null`, the value is active. example: '2023-01-01T15:00:00.000000000Z' created_by_actor: type: object description: The actor that created this value. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b value: type: string description: >- A raw text field. Values are limited to 10MB. example: >- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. attribute_type: type: string enum: - text description: The attribute type of the value. example: text required: - active_from - active_until - created_by_actor - value - attribute_type additionalProperties: false stage: type: array items: type: object properties: active_from: type: string format: date-time description: >- The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. example: '2023-01-01T15:00:00.000000000Z' active_until: type: - string - 'null' format: date-time description: >- The point in time at which this value was deactivated. If `null`, the value is active. example: '2023-01-01T15:00:00.000000000Z' created_by_actor: type: object description: The actor that created this value. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b status: $ref: '#/components/schemas/status' attribute_type: type: string enum: - status description: The attribute type of the value. example: status required: - active_from - active_until - created_by_actor - status - attribute_type additionalProperties: false owner: type: array items: type: object properties: active_from: type: string format: date-time description: >- The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. example: '2023-01-01T15:00:00.000000000Z' active_until: type: - string - 'null' format: date-time description: >- The point in time at which this value was deactivated. If `null`, the value is active. example: '2023-01-01T15:00:00.000000000Z' created_by_actor: type: object description: The actor that created this value. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b referenced_actor_type: type: string enum: - api-token - workspace-member - system - app description: >- The type of the referenced actor. [Read more information on actor types here](/docs/actors). example: workspace-member referenced_actor_id: type: - string - 'null' format: uuid description: The ID of the referenced actor. example: 50cf242c-7fa3-4cad-87d0-75b1af71c57b attribute_type: type: string enum: - actor-reference description: The attribute type of the value. example: actor-reference required: - active_from - active_until - created_by_actor - referenced_actor_type - referenced_actor_id - attribute_type additionalProperties: false value: type: array items: type: object properties: active_from: type: string format: date-time description: >- The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. example: '2023-01-01T15:00:00.000000000Z' active_until: type: - string - 'null' format: date-time description: >- The point in time at which this value was deactivated. If `null`, the value is active. example: '2023-01-01T15:00:00.000000000Z' created_by_actor: type: object description: The actor that created this value. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b currency_value: type: number description: >- A numerical representation of the currency value. A decimal with a max of 4 decimal places. example: 99 currency_code: type: - string - 'null' enum: - ARS - AUD - BRL - BGN - CAD - CLP - CNY - COP - CZK - DKK - EUR - FJD - HKD - HUF - ISK - INR - ILS - JPY - KES - KRW - MYR - MXN - NTD - NZD - NGN - NOK - XPF - PEN - PHP - PLN - GBP - RWF - SAR - SGD - ZAR - SEK - CHF - THB - AED - UYU - USD description: >- The ISO4217 currency code representing the currency that the value is stored in. example: USD attribute_type: type: string enum: - currency description: The attribute type of the value. example: currency required: - active_from - active_until - created_by_actor - currency_value - attribute_type additionalProperties: false associated_people: type: array items: type: object properties: active_from: type: string format: date-time description: >- The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. example: '2023-01-01T15:00:00.000000000Z' active_until: type: - string - 'null' format: date-time description: >- The point in time at which this value was deactivated. If `null`, the value is active. example: '2023-01-01T15:00:00.000000000Z' created_by_actor: type: object description: The actor that created this value. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b target_object: type: string description: >- A slug identifying the object that the referenced record belongs to. example: people target_record_id: type: string format: uuid description: A UUID to identify the referenced record. example: 891dcbfc-9141-415d-9b2a-2238a6cc012d attribute_type: type: string enum: - record-reference description: The attribute type of the value. example: record-reference required: - active_from - active_until - created_by_actor - target_object - target_record_id - attribute_type additionalProperties: false associated_company: type: array items: type: object properties: active_from: type: string format: date-time description: >- The point in time at which this value was made "active". `active_from` can be considered roughly analogous to `created_at`. example: '2023-01-01T15:00:00.000000000Z' active_until: type: - string - 'null' format: date-time description: >- The point in time at which this value was deactivated. If `null`, the value is active. example: '2023-01-01T15:00:00.000000000Z' created_by_actor: type: object description: The actor that created this value. properties: id: type: string description: An ID to identify the actor. nullable: true type: type: string enum: - api-token - workspace-member - system - app nullable: true description: >- The type of actor. [Read more information on actor types here](/docs/actors). example: type: workspace-member id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b target_object: type: string description: >- A slug identifying the object that the referenced record belongs to. example: people target_record_id: type: string format: uuid description: A UUID to identify the referenced record. example: 891dcbfc-9141-415d-9b2a-2238a6cc012d attribute_type: type: string enum: - record-reference description: The attribute type of the value. example: record-reference required: - active_from - active_until - created_by_actor - target_object - target_record_id - attribute_type additionalProperties: false description: >- An object with `attribute_slug` keys, and an array of value objects as the values. Attributes slugs (for example `name` or `stage`) can be used, including custom attribute slugs. example: name: - active_from: '2023-01-01T15:00:00.000000000Z' active_until: null created_by_actor: type: system id: null value: Contract with Fundstack attribute_type: text stage: - active_from: '2023-01-01T15:00:00.000000000Z' active_until: null created_by_actor: type: system id: null status: title: In Progress id: workspace_id: 14beef7a-99f7-4534-a87e-70b564330a4c object_id: 97052eb9-e65e-443f-a297-f2d9a4a7f795 attribute_id: 41252299-f8c7-4b5e-99c9-4ff8321d2f96 status_id: 11f07f01-c10f-4e05-a522-33e050bc52ee is_archived: false celebration_enabled: false target_time_in_status: null attribute_type: status owner: - active_from: '2023-01-01T15:00:00.000000000Z' active_until: null created_by_actor: type: system id: null referenced_actor_type: workspace-member referenced_actor_id: 50cf242c-7fa3-4cad-87d0-75b1af71c57b attribute_type: actor-reference value: - active_from: '2023-01-01T15:00:00.000000000Z' active_until: null created_by_actor: type: system id: null currency_value: 4200 currency_code: USD attribute_type: currency associated_people: - active_from: '2023-01-01T15:00:00.000000000Z' active_until: null created_by_actor: type: system id: null target_object: people target_record_id: bf071e1f-6035-429d-b874-d83ea64ea13b attribute_type: record-reference associated_company: - active_from: '2023-01-01T15:00:00.000000000Z' active_until: null created_by_actor: type: system id: null target_object: companies target_record_id: bf071e1f-6035-429d-b874-d83ea64ea13b attribute_type: record-reference required: - id - created_at - web_url - values required: - data description: Success '400': description: Bad Request content: application/json: schema: type: object properties: status_code: type: number enum: - 400 type: type: string enum: - invalid_request_error code: type: string enum: - filter_error message: type: string example: Error in filter. required: - status_code - type - code - message description: Bad Request '404': description: Not Found content: application/json: schema: type: object properties: status_code: type: number enum: - 404 type: type: string enum: - invalid_request_error code: type: string enum: - not_found message: type: string example: The referenced object was not found. required: - status_code - type - code - message description: Not Found security: - oauth2: - record_permission:read - object_configuration:read components: schemas: status: type: object properties: id: type: object properties: workspace_id: type: string format: uuid description: The ID of the workspace example: 14beef7a-99f7-4534-a87e-70b564330a4c object_id: type: string format: uuid description: The ID of the object example: 97052eb9-e65e-443f-a297-f2d9a4a7f795 attribute_id: type: string format: uuid description: The ID of the attribute example: 41252299-f8c7-4b5e-99c9-4ff8321d2f96 status_id: type: string format: uuid description: The ID of the status example: 11f07f01-c10f-4e05-a522-33e050bc52ee required: - workspace_id - object_id - attribute_id - status_id title: type: string description: The title of the status example: In Progress is_archived: type: boolean description: >- Whether or not to archive the status. See our [archiving guide](/docs/archiving-vs-deleting) for more information on archiving. example: false celebration_enabled: type: boolean description: >- Whether arriving at this status triggers a celebration effect in the UI example: false target_time_in_status: type: - string - 'null' description: >- Target time for a record to spend in given status expressed as a ISO-8601 duration string example: P0Y0M1DT0H0M0S required: - id - title - is_archived - celebration_enabled - target_time_in_status securitySchemes: oauth2: type: oauth2 description: This API uses OAuth 2.0 with the authorization code grant flow. flows: authorizationCode: authorizationUrl: https://app.attio.com/authorize tokenUrl: https://app.attio.com/oauth/token scopes: user_management:read: View workspace members. user_management:read-write: View workspace members. record_permission:read: View, and optionally write, records. record_permission:read-write: View, and optionally write, records. object_configuration:read: >- View, and optionally write, the configuration and attributes of objects. object_configuration:read-write: >- View, and optionally write, the configuration and attributes of objects. list_entry:read: View, and optionally write, the entries in a list. list_entry:read-write: View, and optionally write, the entries in a list. list_configuration:read: >- View, and optionally write, the configuration and attributes of lists. list_configuration:read-write: >- View, and optionally write, the configuration and attributes of lists. public_collection:read: >- View, and optionally write, both the settings and information within public collections. public_collection:read-write: >- View, and optionally write, both the settings and information within public collections. private_collection:read: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. private_collection:read-write: >- View, and optionally modify, both the settings and information of all collections within the workspace, regardless of their access settings. comment:read: View comments (and threads), and optionally write comments. comment:read-write: View comments (and threads), and optionally write comments. task:read: View, and optionally write, tasks. task:read-write: View, and optionally write, tasks. note:read: View, and optionally write, notes. note:read-write: View, and optionally write, notes. meeting:read: View, and optionally write, meetings. meeting:read-write: View, and optionally write, meetings. call_recording:read: >- View, and optionally write, call recordings, transcripts and speakers for meetings. call_recording:read-write: >- View, and optionally write, call recordings, transcripts and speakers for meetings. webhook:read: View, and optionally manage, webhooks. webhook:read-write: View, and optionally manage, webhooks. file:read: View, and upload files. file:read-write: View, and upload files. ````