How to filter contacts with Address Book API

When you have many contacts in your address book and you want to to clean up or export your contacts, you can on filter them. In this tutorial we will explain step-by-step with examples how you can do that.

Filtering contacts

When you filter on contacts, you have to set one or more filters and an operator between the filters. Each filter is presented in the following way:

{
    "fieldKey":{
        "operator":"value"
    }
}
  • The `fieldKey` identifies the key of the address book field you want to filter on.
  • The `operator` identifies how you want to match the `value`. See below for the possible `operator` values.
  • The `value` is the actual value you want to filter on.

For a `fieldKey` you can set multiple `operator` and `value` combinations. You can do this by comma separate them. See below for an example.

The `operator` can have the following values:

OperatorDescription
eqEquals. The value of the field must exactly match the specified value. This operator is available for all field types.
neNot equals. The value of the field must not match the specified value. This operator is available for all field types.
inContains. The value of the field must contain the specified value. This operator is available only for `string` field types.
ninDoes not contains. The value of the field must not contain the specified value. This operator is available only for `string` field types.
gteGreater than or equal. The value of the field must be greater than or equal to the specified value. This operator is available only for `integer`, `date` and `datetime` field types.
lteLess than or equal. The value of the field must be less than or equal to the specified value. This operator is available only for `integer`, `date` and `datetime` field types.
betweenBetween. The value of the field must be between the specified values. Two values will need to be specified. This operator is available only for `integer`, `date` and `datetime` field types.
nullNull. The value of the field empty. No value has to be specified. This operator is available for all field types.
not nullNot null. The value of the field must not be empty. No value has to be specified. This operator is available for all field types.
swStarts with. The value of the field must not contain the specified value. This operator is available only for `string` field types.
ewEnds with. The value of the field must not contain the specified value. This operator is available only for `string` field types.

Let’s give an example how to filter for contacts which have as first name `john` and last name `doe`.

$operator = 'and';
$filters = [
    'firstName' => [
        'eq' => 'john',
    ],
    'lastName' => [
        'eq' => 'doe',
    ],
];

$client->getContacts($operator, $filters);

The operator you specify is either `and` or `or`. When you set `and` as the operator it means that all contacts will be returned which match all filters. When you set `or` as operator, all contacts which match at least one operator are returned.

Note: when filtering for contacts and more than 100 contacts are found, only 100 contacts will be returned. If you want to get all found contacts, you can download contacts (link to api doc) as a CSV file or in JSON.

Wildcards

For date and datetime fields, you can use wildcards. You can replace each digits in the date or datetime value with a `*`. It will then not check for a specific digit at the place, but any digit would do. For example, when you would like to filter for contacts which have their birthday on March 14 (Pi Day 😀), you can replace the year in the value with `*`. For an example, see example 6 below.

Filter examples

Let’s give some examples of the filters.

Example 1: This will filter for contacts with first name `john` or `jane`.

// single filter multiple parameter
$operator = 'or';
$filters = [
    'firstName' => [
        'eq' => ['john', 'jane'],
    ],
];

Example 2: This will filter for contacts where the first name contains `john` and the mobile number starts with `65` or `62`.

// multiple filters and multiple parameters
$operator = 'or';
$filters = [
    'firstName' => [
        'in' => "john",
    ],
    'mobile' => [
        'sw' => ['65', '62']
    ],
];

Example 3: This will filter for contacts where the first name is not `john` or `jane` and the last name is not `doe`.

// multiple filters
$operator = 'and';
$filters = [
    'firstName' => [
        'ne' => ['john', 'jane'],
    ],
    'lastName' => [
        'ne' => 'doe'],
    ]
];

Example 4: This will filter for contacts where the customerInt field has a value >= 1 and <= 100.

// between filter
$operator = 'and';
$filters = [
    'customInt' => [
        'between' => '1,100',
    ],
];

Example 5: This will filter for contacts where the firstName is not empty.

// not null filter
$operator = 'and';
$filters = [
    'firstName' => [
        'nn' => null,
    ],
];

Example 6: This will filter for contacts on birthday with a wild card.

// wildcard
$operator = 'and';
$filters = [
    'birthday' => [
        'eq' => '****-03-14',
    ],
];