How To Use Filters

Use filters to limit the records included in a Data Export API job. Add filters to
the filters array in the request body for POST /data/export/v1/job.

All filters in a request are combined with AND. A record must satisfy every filter
to be included in the export.

Find Available Fields

Available fields can vary by entity type and tenant configuration. Before creating
an export job, retrieve the fields available to your tenant:

GET /data/export/v1/fields?entityType=Account

The response provides each field's name, label, and dataType. Use the returned
name exactly in both the fields and filters arrays. Repeat the request with
Person, Activity, or Opportunity to discover fields for another entity type.

Filter Structure

Each filter contains:

field: A field name returned by the Fields endpoint.
operator: The comparison to apply.
values: An array containing the comparison value or values. Omit this property
for Exists and Does Not Exist.

{
  "field": "{Account}.billingState",
  "operator": "Equals",
  "values": ["CA"]
}

Supported Operators

Use the following canonical operator names. Operator names are matched
case-insensitively, but using the canonical spelling keeps requests consistent and
portable.

Operator	Values	Behavior
`Equals`	One	Equal to the value
`Does Not Equal`	One	Not equal to the value
`In`	One or more	Equal to any value in the array
`Not In`	One or more	Not equal to any value in the array
`Contains`	One	Contains the value
`Does Not Contain`	One	Does not contain the value
`Begins With`	One	Begins with the value
`Does Not Begin With`	One	Does not begin with the value
`Ends With`	One	Ends with the value
`Does Not End With`	One	Does not end with the value
`Greater Than`	One	Greater than the value
`Greater Than or Equal To`	One	Greater than or equal to the value
`Less Than`	One	Less than the value
`Less Than or Equal To`	One	Less than or equal to the value
`Between`	Two	Between the two values, inclusive
`Exists`	None	Has a value
`Does Not Exist`	None	Does not have a value

The operators available for a field depend on its dataType. For example, text
fields support operators such as Contains, while numeric and date-time fields
support comparison operators.

Filter by Multiple Criteria

The following filters select California accounts in the technology industry with
more than 50 employees:

[
  {
    "field": "{Account}.billingState",
    "operator": "Equals",
    "values": ["CA"]
  },
  {
    "field": "{Account}.industry",
    "operator": "Equals",
    "values": ["Technology"]
  },
  {
    "field": "{Account}.numberOfEmployees",
    "operator": "Greater Than",
    "values": ["50"]
  }
]

Filter Activity Exports by Date

For an Activity export, specify the activity date range with the top-level
fromDate and toDate properties. Do not add {Activity}.activityDate to the
filters array.

Both dates are required for Activity exports. The range is inclusive and cannot
exceed 90 days. Use YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ format.

{
  "jobName": "January website activities",
  "entityType": "Activity",
  "fields": [
    "{Activity}.activityDate",
    "{Activity}.activityType",
    "{Activity}.details",
    "{Person}.email"
  ],
  "fromDate": "2024-01-01",
  "toDate": "2024-01-31",
  "filters": [
    {
      "field": "{Person}.email",
      "operator": "Ends With",
      "values": ["@example.com"]
    }
  ],
  "format": "CSV"
}

Complete Account Export Example

The following request includes the required jobName and entityType properties
and uses fields available in the Account export schema:

{
  "jobName": "California technology accounts",
  "entityType": "Account",
  "fields": [
    "{Account}.name",
    "{Account}.industry",
    "{Account}.billingState",
    "{Account}.numberOfEmployees"
  ],
  "filters": [
    {
      "field": "{Account}.billingState",
      "operator": "Equals",
      "values": ["CA"]
    },
    {
      "field": "{Account}.industry",
      "operator": "Equals",
      "values": ["Technology"]
    },
    {
      "field": "{Account}.numberOfEmployees",
      "operator": "Greater Than",
      "values": ["50"]
    }
  ],
  "format": "CSV"
}

Always confirm field availability with the Fields endpoint before submitting a job.