Filtering Contacts to Search

In the search call, API users can include the following parameters to filter the contacts to search for:

Filtering Criteria Query Details
Contact Database Include the Database ID for the database from which to search for the contacts. This parameter is required.
Contact Lists, Job Lists and Event Lists Include one or multiple List IDs for the list/lists from which to search for the contacts.
Filter Include one or multiple filters to filter the data set on. Each filter contains a FieldName, a Value and an Operator.

Filtering Parameter

Adding a filter parameter to the JSON body of the request. The filter parameter is a list of filters and each filter is made up of the following:

  • FieldName – required if a filter has been added to the body - string – the name of the field to filter on. When filtering on a custom field – the correct field name must be provided, not the custom display name.
  • Values – required if a filter has been added to the body - list of strings – a list of values to filter the data on – adding multiple values creates an or condition i.e. value1 or value2.
  • Operator – string – default value is equals – the type of operator for your filter, values can be:
    • Equals
    • Contains
    • NotEquals
    • NotContains

Example: Adding one filter – if we wanted to filter the data on firstName contains Joe – our request would look like this:

{

"ContactDbId": 55,

"Filter": [

{

"FieldName": "FirstName",

"Value": ["Joe"],

"Operator": "Contains"

}],

"PageSize": 10,

"PageNumber": 1,

"VisibleFields": ["FirstName", "LastName", "Email", "School"]

}

Example: It is also possible to filter a field on multiple values – this can be achieved by adding another value to the Value list. In the example below we want to filter on the firstName Joe or Jenny to retrieve contacts that contain either values.

{

"ContactDbId": 55,

"Filter": [

{

"FieldName": "FirstName",

"Value": ["Joe", "Jenny"],

"Operator": "Contains"

}],

"PageSize": 10,

"PageNumber": 1,

"VisibleFields": ["FirstName", "LastName", "Email", "School"]

}

Example: It is also possible to filter the data on multiple fields – this can be achieved by adding another filter to the Filter list. In the example below we want to filter the data on FirstName equals Joe and LastName equals Bloggs.

{

"ContactDbId": 55,

"Filter": [

{

"FieldName": "FirstName",

"Value": ["Joe"],

"Operator": "Equals"

},

{

"FieldName": "LastName",

"Value": ["Bloggs"],

"Operator": "Equals"

}],

"PageSize": 10,

"PageNumber": 1,

"VisibleFields": ["FirstName", "LastName", "Email", "School"]

}

List IDs

Example: Filter by ListIds by adding the ListId parameter to the JSON body of the request:

{

"PageNumber": 1,

"PageSize": 200,

"ContactDBId": 55,

"ListIds": [1367841],

"VisibleFields": [

"Contactid",

"firstName",

"lastName",

"addedOn",

"addedBy",

"updatedOn",

"updatedBy",

"jobTitle",

"company",

"email",

"otherEmail",

]

}

Example: Multiple Lists can also be searched:

{

"PageNumber": 1,

"PageSize": 200,

"ContactDBId": 55,

"ListIds": [1367841, 5682345],

"VisibleFields": [

"Contactid",

"firstName",

"lastName",

"addedOn",

"addedBy",

"updatedOn",

"updatedBy",

"jobTitle",

"company",

"email",

"otherEmail",

]

}