Loading...

Contact List Setup


Contact Lists provide the means to filter, or search, contacts by a predefined set of values and conditions. For example, it is possible to filter all contacts by a contact attribute such as their age, or by what subscription they are included in. This allows you to create a custom list of contacts, perfect for targeting the most appropriate sub-set with a specific message.

Contact Lists are used when creating a new outbound campaign. As part of defining the campaign, you select the Contact List to which you want to send the message to. You can either select an already existing Contact List, or create a new one.

Contact lists are created by defining one or more filters; a filter specifies which criteria (age, zip code, etc) will be used in a search of all Contacts.


Filters

Filters require some key bits of information for them to function correctly. They need to know what information to compare against. How the comparison is to be performed, and finally the target value to use.


Format of a Filter

{
    "FilterTypeId": int,
    "OperandId"   : int,
    "Operation"   : string,
    "Value"       : string
}

A filter type identitifes which broad group of operation types to filter applies to, such as a contact attribute, subscription or raw contact value. The current list of filter types are as follows:

ID Name Examples
1 Contact Attributes User defined attributes such as age, zip code, etc.
2 Subscription Data The subscription IDs the contact is currently subscribed to.
3 TrueDialog Contact Data TrueDialog defined data such as phone number, email address, etc.

The OperandID identifies the specific data column to match against. For example, with the Filter Type ID set to 1 and the Operand ID set to 1, the operation will match the subscription ID that the contacts are subscribed to.

The operation is the actual binary operator to apply, and the value is the target value to use in the operation. The following is an example filter that would return contacts that are opted into subscription #1.

Get contacts in Subscription #1 example

 {
    "FilterTypeId": "1",
    "OperandId"   : "1",
    "Operation"   : "=",
    "Value"       : "1"
}

Filter Groups

One filter is often not enough to define a useful complete list. For example, it might be desirable to find a set of contacts who's age range falls between certian values. Filter groups provide the means to combine multiple filters together to achive this goal.

Filters are nested within a filter group to achive this system, and every contact list requires at least one root group. Finally, groups can be nested within each other providing an infinately complex set of rule capabilities.

Filter Group Format

{
    "Operator": string,
    "Groups"  : [{ /* group details */ }],
    "Filters" : [{ /* filter details */ }]
}

The operator is either "AND" or "OR", and cannot be any other value. The groups and filters are arraies of nested items. The following example shows a filter group that might filter on a set of contacts who's age falls between 26 and 35.

Filtering by age

{
    "Operator": "AND",
    "Groups"  : [],
    "Filters" : [
        {
            "FilterTypeId": "0",  // Filter on Contact Attribute ID
            "OperandId"   : "1",  // The ID of the contact attribute
            "Operation"   : ">",
            "Value"       : "25"
        },
        {
            "FilterTypeId": "0",  // Filter on Contact Attribute ID
            "OperandId"   : "1",  // The ID of the contact attribute
            "Operation"   : "<=",
            "Value"       : "35"
        }
    ]
}

In the above example, the OperandId of the filters is set to the ID value of the contact attribute definition. Note that for the contact attribute filters to work, you must first define the contact attribute defintion prior to creating the filter.


Contact List Structure

Now that the details for filters and groups are known we can present the structure for a complete contact list.

Contact List Format

{
    "Name": string,
    "RootGroup": {/* root group details */}
}

Our final example demonstrates the complexity that can be acheived with the nested filters. Here we filter for everyone between the age ages of 25 and 35 in subscription #1, or return everyone who is in subscription #2.

Complex Example

{
    "Name": "My complex contact list",
    "RootGroup":
    {
        Operator: "OR",
        "Groups": [
            {
                "Operator": "AND",
                "Groups"  : [],
                "Filters" : [
                    {
                        "FilterTypeId": "0",  // Filter on Contact Attribute ID
                        "OperandId"   : "1",  // The ID of the contact attribute
                        "Operation"   : ">",
                        "Value"       : "25"
                    },
                    {
                        "FilterTypeId": "0",  // Filter on Contact Attribute ID
                        "OperandId"   : "1",  // The ID of the contact attribute
                        "Operation"   : "<=",
                        "Value"       : "35"
                    },
                    {
                        "FilterTypeId": "1",  // Filter on Subscriptions
                        "OperandId"   : "1",  // Use the subscription ID
                        "Operation"   : "=",
                        "Value"       : "1"
                    }
                ]
            }
        ],
        "Filters": [
            {
                "FilterTypeId": "1",  // Filter on Subscriptions
                "OperandId"   : "1",  // Use the subscription ID
                "Operation"   : "=",
                "Value"       : "2"
            }
        ]
    }
}