Creating a New Customer Audience
Data Portal uses audiences to group together certain customers who meet a specific criteria. Criteria can range from age to assets to recent activity with Online Banking.
To create an audience with Apiture’s APIs, you must first know the criteria options available for the audience. You may find it useful to view the Data Portal interface to quickly see all of the criteria available, or read our Audience Criteria documentation (hosted within a password protected portal).
Developer Portal and API Access
Before using Apiture’s APIs, you must first register an application on Apiture’s Developer Portal. For additional information on the Developer Portal, see our documentation at Getting Started – Apiture Developers
Filters vs Criteria Terminology
Within the API, criteria is called a filter. Beyond the change in name, these concepts are identical whether you are using criteria on the Data Portal website or filters with the API. The term “filter” will be used throughout the rest of this document as it is discussing the API.
Filter Object and Parameters
Filters can be accessed via the serviceAnalyticFilters
API.
Each filter has a unique information that describes the filter, and how the filter can be used.
{
"filterType": {
"id": "215eaed841368ce154d5",
"name": "customerType"
},
"operator": "equals",
"values": [
"retail"
],
"ordinal": 0,
"includeMissingValues": false
}
When creating an audience, the following fields are important:
id
: The unique identifier of the filter. This will be used by the API to select the fitler.operators
: Some filters can be used in multiple ways. For example, a numeric-based filter for age could match an age `equal` to a specific number, `greaterThan` a certain number, ` lessThanOrEqualTo’ a certain number, or other combinations. `Operators` will list the available options.values
: Values are the information being compared by the chosenoperator
. Each filter takes different types of input based on thedataType
. For example, if you were searching for customers in a certain state, the value would be an array of states as strings:['MN', ‘WI’, ‘SD’, ‘ND']
.NOTE: This is an array of string for all values, including integers.
To retrieve a list of all operators, perform a GET
operation on listAnalyticFilterTypes
GET /service/analyticFilterTypes
You will receive an array of items
containing filters (as shown in the example above).
If you wish to retrieve one specific filter, perform a GET operation on getAnalyticFilterType
including the id
at the end of the path.
GET /service/analyticFilterTypes/{analyticFilterTypeId}
Primitive vs Composite Filters
Often, audiences are formed using more than one filter. Individual filters can be grouped together using one of two methods. These methods use logical operators to determine which customers should be included in the audience.
Primitive Filters
A primitive filter is best used when a filter is used by itself and/or does not depend on the result of any other filter.
For example, if you want an audience with customers of a certain age AND who live in Minnesota, a primary filter can be used.
You may declare a logical operator for your primitive filters. In the example above, the logical operator would be AND. If instead you wished for customers in either Minnesota or Wisconsin, you could use the OR operator.
Composite Filters
Some filters must be combined in more complex ways.
Composite filters allow you to group primitive filters together. It is a close equivalent to writing parentheses around part of a logical or mathematical operation.
For example, an audience should have customers over the age of 25 who either have a high credit utilization rate or have a liability rate higher than their asset value.
As a logical operation, this may be written as:
Age > 25 AND ( utilization rate > 25 OR liability rate > assets )
In the example above, the OR clause within the parenthesis belongs in a composite filter.
Combining Filters
Primitive Filters can be used by themselves, or be nested within composite filters. As many filters can be included as necessary; there is not a maximum number of filters.
Ordinals
Ordinals are used to visually order the filters on the Data Portal website. When creating an audience via an API, ordinals are not required. However, if this audience will later be edited using the website, setting the ordinal may make it appear in a more logical order.
The lowest ordinal will display higher on the Data Portal website.
Ordinals are dependent on what they are nested inside. In this simplified example below, multiple ordinal 0 and 1 are present. This is allowed because they are in separate filters: Two primitive filters and a composite filter:
"primitiveFilters": [ //Two primative filters
{
"filterType": {...},
"ordinal": 0, //First ordinal 0
},
{
"filterType": {...},
"ordinal": 1, //First ordinal 1
}
],
"compositeFilters": [
{
"ordinal": 2, //First ordinal 2, for the position of the composite filter
"primitiveFilters": [
{
"filterType": {...},
"ordinal": 0, //Second ordinal 0, within the composite filter
},
{
"filterType": {...},
"ordinal": 1,//Second ordinal 1, within the composite filter
}
]
}
Enrollment State
When creating an audience, there is both an enrollmentState
property and the option of creating an ENROLLMENT_STATE
filter. There are differences in how these two values are set. The filter ENROLLMENT_STATE
can take multiple values in an array while the property enrollmentState
can only be set to a single string value.
enrollmentState property value | ENROLLMENT_STATE filter values |
---|---|
“customer” | [“retail”, “commercial”, “unenrolled]” |
“enrolled” | [“retail”, “commercial”] or [“retail”] or [“commercial”] |
“unenrolled” | [“unenrolled”] |
“applicant” | [“applicant”] |
Creating an Audience
Audiences are creating using the `Service Customer Audiences` API.
Creating an audience via API has four requirements:
name
: a string containing the chosen name for this audience.customerType
: The type of customer. Options are described in our API documentation.enrollmentState
: The enrollment status of the customer. Options are described in our API documentation.Filters are not required; however, it is highly recommended to include an
ENROLLMENT_STATE
filter that pairs with theenrollmentState
property. See notes on the enrollment state filter above.
To create an audience, POST
with a complete request body to customerAudiences
. An example request body is shown below.
POST /service/customerAudiences
{
"name": "Example Audience",
"customerType": "all",
"enrollmentState": "enrolled",
"filters": {
"operator": "or",
"primitiveFilters": [
{
"filterType": {
"id": "215eaed841368ce154d5",
"name": "customerType"
},
"operator": "equals",
"values": [
"retail"
],
"ordinal": 0,
"includeMissingValues": false
},
{
"filterType": {
"id": "6b3927745edec398ad74",
"name": "customerAge"
},
"operator": "between",
"values": [
"35",
"49"
],
"ordinal": 1,
"includeMissingValues": false
}
],
"compositeFilters": [
{
"operator": "and",
"ordinal": 2,
"primitiveFilters": [
{
"filterType": {
"name": "customerRegion",
"id": "01888d58e2424bf1c676"
},
"operator": "in",
"values": [
"NC",
"SC",
"GA",
"FL"
],
"ordinal": 0,
"includeMissingValues": false
},
{
"filterType": {
"name": "accountBalance",
"id": "023cd8af6a9d46eec506"
},
"operator": "greaterThan",
"values": [
"250000.00"
],
"ordinal": 1,
"includeMissingValues": false
}
]
}
]
}
}
Using a Template
If you wish to use an audience template to provide your filters, you may GET
the template from the API. Once fetched, copy the filters or other desired information into the POST
to customerAudiences
to create an audience.
To get a list of audience templates, perform a GET operation on customerAudienceTemplates
GET /service/customerAudienceTemplates
This will return a list of templates. Each template’s filters are formatted similarly to what is needed for the create request.
How can we help?
Get support for your issues.