DataQueryRequestDTO

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/act-on/main/json-schema/act-on-data-query-request-dto-schema.json",
  "title": "DataQueryRequestDTO",
  "description": "The data query specification",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/act-on-custom-data-query-api-api-openapi.yml#/components/schemas/DataQueryRequestDTO",
  "type": "object",
  "properties": {
    "otherObject": {
      "type": "string",
      "description": "Locator of the other data source to join with."
    },
    "otherDataset": {
      "type": "string",
      "description": "Optional locator (id, name) of the other data source dataset (if Custom Object) to join with."
    },
    "selectFields": {
      "type": "array",
      "description": "List of fields to select. Must be prefixed with 'aoc.' for Act-On Contacts fields or 'co.' for custom object fields. Use 'aoc.*' or 'co.*' to select all fields from respective source.",
      "items": {
        "type": "string"
      },
      "maxItems": 2000,
      "minItems": 0
    },
    "page": {
      "type": "integer",
      "format": "int32",
      "deprecated": true,
      "description": "Page number (0-based). DEPRECATED: Use pagination object instead."
    },
    "size": {
      "type": "integer",
      "format": "int32",
      "deprecated": true,
      "description": "Number of items per page. DEPRECATED: Use pagination object instead."
    },
    "pagination": {
      "$ref": "#/$defs/PaginationDTO",
      "description": "Pagination information supporting both offset and cursor-based pagination"
    },
    "sortBy": {
      "type": "string",
      "deprecated": true,
      "description": "Sort by field. Reference Act-On Contacts fields by the prefix `aoc.` if they overlap with custom object fields. DEPRECATED: Use sortFields instead for multiple field sorting."
    },
    "sortByDirection": {
      "type": "string",
      "deprecated": true,
      "description": "Sort direction. Either `asc` or `desc`. If anything else no sorting will be applied. DEPRECATED: Use sortFields instead for multiple field sorting."
    },
    "sortFields": {
      "type": "array",
      "description": "List of fields to sort by with their directions. Takes precedence over sortBy/sortByDirection. Each field must be prefixed with 'aoc.' for Act-On Contacts fields or 'co.' for custom object fields.",
      "items": {
        "$ref": "#/$defs/SortFieldDTO"
      },
      "maxItems": 10,
      "minItems": 0
    },
    "filterExpression": {
      "type": "string",
      "description": "Filter expression."
    },
    "joinStrategy": {
      "$ref": "#/$defs/JoinStrategyDTO",
      "description": "Join strategy."
    },
    "searchTerm": {
      "type": "string",
      "description": "Search term."
    },
    "datetimeFieldsTimezone": {
      "type": "string",
      "description": "Override timezone for all DATETIME fields in the query. Must be a valid timezone identifier (e.g., 'US/Eastern', 'Europe/London', 'UTC'). If specified, this overrides both account-level and field-level timezone settings."
    }
  },
  "$defs": {
    "JoinStrategyDTO": {
      "type": "object",
      "description": "Configuration for join operations between Act-On Contacts and Custom Objects",
      "properties": {
        "useDefaults": {
          "type": "boolean",
          "description": "When set to true, other parameters are ignored and the defaults are used based on the relationship type of the custom object. Defaults to false"
        },
        "joinEnabled": {
          "type": "boolean",
          "description": "Enable or disable join with other data. Defaults to true"
        },
        "onlyMatching": {
          "type": "boolean",
          "description": "If true, only matching records will be joined. Defaults to false"
        },
        "duplicates": {
          "type": "string",
          "description": "Strategy for handling duplicates. If not provided, defaults to 'noJoinFieldsDuplicates for Custom Objects with 'one-to-one' relationship and 'noActOnContactsJoinFieldsDuplicates' for 'one-to-many' relationship",
          "enum": [
            "allow",
            "noOtherJoinFieldsDuplicates",
            "noBaseJoinFieldsDuplicates",
            "noJoinFieldsDuplicates"
          ]
        },
        "otherOrderByField": {
          "type": "string",
          "description": "Field name to order joined data by. If not provided, defaults to 'updatedDate'"
        },
        "otherSelector": {
          "type": "string",
          "description": "Selection strategy for joined data when duplicates exist. If not provided, defaults to 'last'",
          "enum": [
            "first",
            "last"
          ]
        },
        "baseOrderByField": {
          "type": "string",
          "description": "Field name to order base data by. If not provided, defaults to 'sys.createdAt'"
        },
        "baseSelector": {
          "type": "string",
          "description": "Selection strategy for the base data when duplicates exist. If not provided, defaults to 'last'",
          "enum": [
            "first",
            "last"
          ]
        }
      }
    },
    "PaginationDTO": {
      "type": "object",
      "description": "Pagination information for data query requests",
      "properties": {
        "page": {
          "type": "integer",
          "format": "int32",
          "description": "Page number (0-based) for offset-based pagination"
        },
        "size": {
          "type": "integer",
          "format": "int32",
          "description": "Number of items per page"
        },
        "nextPageToken": {
          "type": "string",
          "description": "Token for cursor-based pagination. Use null or omit for the first page."
        },
        "pageStrategy": {
          "type": "string",
          "description": "Pagination strategy to use. Defaults to OFFSET if not specified.",
          "enum": [
            "OFFSET",
            "CURSOR"
          ]
        }
      }
    },
    "SortFieldDTO": {
      "type": "object",
      "description": "Sort field configuration",
      "properties": {
        "field": {
          "type": "string",
          "description": "Field name to sort by. Must be prefixed with 'aoc.' for Act-On Contacts fields or 'co.' for custom object fields."
        },
        "direction": {
          "type": "string",
          "default": "asc",
          "description": "Sort direction",
          "enum": [
            "asc",
            "desc"
          ]
        }
      },
      "required": [
        "field"
      ]
    }
  }
}