Smart Searches

Filters

Filters are specified as objects, and concatenated in an array which defines the entire query. All filter objects follow the same specification, and must have type and config attributes, along with an optional op attribute.

{
    "op": "sub or add",
    "type": "type_name",
    "config": {},
}

Below are descriptions of all implemented filters and their respective config parameters.

All people (all)

This filter just returns all the people belonging to an organization.

{
    "type": "all",
    "config": null,
}

There are no config options. The all filter always returns every person in the database.

Person data (person_data)

This filter matches the specified fields against a field directly on the person object (e.g. first name, last name or phone number.)

{
    "type": "person_data",
    "config": {
        "fields": {
            "first_name": "Clara",
            "last_name": "Zetkin"
        }
    }
}

Person tags (person_tags)

This filter maches people based on how they have been tagged.

{
    "type": "person_tags",
    "config": {
        "condition": "none",
        "tags": [1, 2, 3]
    }
}

The tags property must be a non-empty array of tag IDs. An error is thrown if the array is empty or has not been defined.

The different values for condition are:

Most active (most_active)

This filter selects the N most active people, defined as those who participate in the largest number of actions, within an optional time period.

{
    "type": "most_active",
    "config": {
        "size": 20,
        "before": "1933-06-20",
        "after": "1857-07-05",
    }
}

Campaign participation (campaign_participation)

This filter checks whether a person participated in the specified campaign (or any campaign) at all, during the optional range of dates defined by the before and after attributes.

{
    "type": "campaign_participation",
    "config": {
        "operator": "in",
        "campaign": 1,
        "activity": 2,
        "location": 3,
        "state": "booked",
        "after": "1857-07-05",
        "before": "now"
    }
}

The operators are:

If the campaign attribute is not specified, the operators instead refer to any campaign, i.e. the notin operator when used without a specified campaign will match all people who do not participate in any campaigns at all.

The same goes for the activity and location attributes.

The state attribute can be one of the following:

The before and after attributes are dates and can be specified according to a number of formats described in more detail in the Date attributes section.

Call history (call_history)

{
    "type": "call_history",
    "config": {
        "operator": "called",
        "assignment": 1,
        "minTimes": 3,
        "after": "-20d"
    }
}

The operators are:

If the assignment attribute is not specified, the search will be made against any assignment, i.e. the reached operator when used without a specified assignment will match all people who have been reached in any assignment.

The before and after attributes are dates and can be specified according to a number of formats described in more detail in the Date attributes section.

The minTimes attribute defines a minimum number of calls matching the criteria specified by assignment, before and after. This way, it’s possible to find people who have been called at least 4 times during a certain assignment, or during the last month.

Caller (caller)

{
    "type": "caller",
    "config": {
        "operator": "assigned",
        "assignment": 1
    }
}

The operators are:

Call blocked (call_blocked)

Returns people who cannot be called at this time , for any (or a specified) reason.

{
    "type": "call_blocked",
    "config": {
        "reason": "any"
    }
}

The reason attribute can have the following values:

Survey submissions (survey_submission)

The survey submission selection includes people based on whether they submitted responses to a survey.

{
    "type": "survey_submission",
    "config": {
        "operator": "submitted",
        "survey": 1,
        "after": "-20d"
    }
}

The operators are:

The survey attribute is required and defines which survey the selection should be based on. The after attribute is optional. If present, matching will be restricted to responses submitted after the defined date.

Survey responses (survey_response)

The survey response selection includes people based on a free text search of responses to survey questions.

{
    "type": "survey_response",
    "config": {
        "operator": "in",
        "survey": 2,
        "value": "foobar"
    }
}

The operators are (all operators are case insensitive):

When survey is specified, all responses in that survey will be searched. Replace the survey attribute with the question attribute, the value of which is the ID of the question, to limit the matching to a single question.

Survey options (survey_option)

The survey option selection includes people based on options they’ve selected (or not) in response to survey questions.

{
    "type": "survey_option",
    "config": {
        "operator": "all",
        "question": 2,
        "options": [1, 2]
    }
}

The operators are:

Aggregate sub-query (sub_query)

The sub-query filter allows for aggregating several queries into one, using the standard operators when concatenating their results. This is different from concatenating the filters of each individual query linearly, because with sub-queries, the add/subtract operations are first evaluated in the sub-query, and then the total sum of each sub-query are concatenated.

This allows for constructions like f0 - (f1 + f2) where the results of the query consisting of filters f1 and f2 will be subtracted from filter f0, while a flat concatenation of f0 - f1 + f2 would result in f1 being subtracted from f0 before finally adding the results of f2.

{
    "type": "sub_query",
    "config": {
        "query_id": 1
    }
}

The query referenced by query_id can in turn contain other sub-query filters, as long as there are no circular dependencies. If queryId is not defined, references a query that does not exist, or results in direct or in-direct circular dependencies, an error will be returned.

Random (random)

The random filter selects a random subset of the people in an organization. The size of the subset is defined in the config.

{
    "type": "random",
    "config": {
        "size": 0.7,
        "seed": "abc123"
    }
}

The size property defines how many people to return and must be a positive number. Integers above 1 are interpreted as a fixed size, meaning that a value of 5 will result in at most 5 persons being returned. Fractions between 0 and 1 are interpreted as a percentage of the total number of people in the organization, so a value of 0.5 will return 50% of the people.

The seed property can be used to refresh the random selection. The selection is stable in the sense that given the same seed, the same subset will always be returned, as long as the database doesn’t change.

If the seed changes, the subset will be very different. If the database changes, e.g. by adding or removing people, the random subset will at most change by the number of people added and removed.

The default seed is the empty string.

Zetkin users (user)

The user filter finds person objects based on whether they are connected to a Zetkin user.

{
    "type": "user",
    "config": {
        "is_user": true
    }
}

The only configuration attribute is is_user. Setting this to true will find people who are connected to a user. Setting it to false will find people who are not.

Date attributes

Many filters have attributes that define dates, e.g. the before and after attributes. Dates can be specified using a number of formats.

Static dates

Static dates, i.e. dates defined upon saving the query, are specified using yyyy-mm-dd notation. Using a static date means that the same date will be used for all future executions of the query.

Dynamic dates

There are two types of dynamic date definitions; the now keyword, and date offsets. Dynamic dates are evaluated when the query executes, meaning that filters which have been configured with dynamic date attributes may match different people from one day to the next.

The current date (now)

The special now keyword will be evaluated to the current date upon query execution.

Date offsets

Date offsets are similar to now (and internally rely on the same NOW() SQL function) but actually evaluate to date relative to the current date. Date offsets are defined using the syntax <op><scalar><unit> where:

Examples:

Filter concatenation

Filters are concatenated differently depending on the value of the op attribute of the next filter. The two options are add (default) or sub.

Extending (add)

The add operator means that the results of all previous filters are extended by the results of the next filter. If all previous filters result in 100 matches and the next filter alone matches 20 matches, the result will be up to 120 matches. It may result in fewer matches if there are duplicate results between the two. In SQL terms, this operation is a simple OR.

The add operator is the default which is used if no operator is defined in the filter specification.

Narrowing (sub)

The sub operator means that the results of the next filter is removed from the results of all previous filters. If all previous filters result in 100 matches and the next filter alone matches 20 matches, the aggregate result will between 80-100 matches. The exact number depends on how many of the 20 were already in the 100. In SQL terms, this operations is a AND NOT.