Apiture Developers Apiture Developers

Menu

  • Explore API Banking
    • API Digital Banking
    • Embedded Banking
    • Contact Us
  • Developers
    • Quick Start Guide
    • Embedded Banking
    • Events Reference
    • Authenticated Portal
  • API Documentation
    • API Reference
Log In / Register
Apiture Developers Apiture Developers
Log In / Register
Apiture Developers

Menu

  • Explore API Banking
    • API Digital Banking
    • Embedded Banking
    • Contact Us
  • Developers
    • Quick Start Guide
    • Embedded Banking
    • Events Reference
    • Authenticated Portal
  • API Documentation
    • API Reference

API Documentation

  • folder icon closed folder iconGetting Started
  • folder icon closed folder iconConcepts
    • API Keys
    • Authorization and Authentication
    • Access Tokens
    • Resources and URI Structure
    • Resource Collections
    • Resource Sets
    • Scopes & Entitlements
    • Error Responses
    • Error Types
    • Dry Runs
    • Markdown
    • Idempotent Operations
    • Collection Pagination
    • Collection Filtering
    • Transfers
    • Business Transfers
    • Cutoff Times
    • Identity Challenges
  • folder icon closed folder iconGuides
    • Authenticate Users in your App using OpenID Connect with PKCE
    • Authenticate using OAuth 2.0 Client Credentials Flow
    • Getting a List of Accounts
    • Listing the Balances for Accounts
    • Using Pagination
    • Creating a One-Time Transfer
    • Listing Transfers
    • Retrieving Business Transfer Information
    • Completing an Identity Challenge
    • Creating a New Customer Audience
    • Importing and Exporting Audiences
  • folder icon closed folder iconAPI Reference
  • folder icon closed folder iconRelease Notes

Creating a New Customer Audience

  • folder icon closed folder iconAPI Documentation
    • Getting Started
    • Concepts
      • API Keys
      • Authorization and Authentication
      • Access Tokens
      • Resources and URI Structure
      • Resource Collections
      • Resource Sets
      • Scopes & Entitlements
      • Error Responses
      • Error Types
      • Dry Runs
      • Markdown
      • Idempotent Operations
      • Collection Pagination
      • Collection Filtering
      • Transfers
      • Business Transfers
      • Cutoff Times
      • Identity Challenges
    • Guides
      • Authenticate Users in your App using OpenID Connect with PKCE
      • Authenticate using OAuth 2.0 Client Credentials Flow
      • Getting a List of Accounts
      • Listing the Balances for Accounts
      • Using Pagination
      • Creating a One-Time Transfer
      • Listing Transfers
      • Retrieving Business Transfer Information
      • Completing an Identity Challenge
      • Creating a New Customer Audience
      • Importing and Exporting Audiences
    • API Reference
    • Release Notes
  • folder icon closed folder iconAuthenticated Portal
    • Getting Started
      • Registration
      • Profile
    • Concepts
      • Environments
      • Products
    • Managing your Applications
      • Creating Applications
      • Creating Data Direct: Real-Time Webhooks
      • Editing Applications
      • Application Owners
      • Getting Application Keys and IDs
      • Continue your Project
    • Release Notes
      • Developer Portal 1.0
      • Developer Portal 1.1
  • folder icon closed folder iconEmbedded Banking
    • Getting Started
    • Concepts
      • Overview
      • Managing User Credentials
      • Components
      • Registering your Application
      • Terminology
      • Encryption and Authentication
    • Guides
      • Component Customization
      • Customization Examples
      • Initializing Components
      • Event Handling and Data Processing
    • Release Notes
      • EB v1.0 Release Notes
      • EB v1.2.2 Release Notes
      • EB v1.3 Release Notes
      • Developer Portal 1.0 Update
  • folder icon closed folder iconEvents
    • Introduction
    • Guides
      • General Structure
      • Field Annotations
      • Customer Onboarding Data Direct: Real-Time
    • Data Delivery
      • Flat File Delivery
      • Snowflake Delivery
      • Event History API
      • Real-time / Webhooks

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 chosen operator. Each filter takes different types of input based on the dataType. 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 enrollmentStatecan 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 the enrollmentState 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.

Explore API Banking

  • API Digital Banking
  • Embedded Banking
  • Contact Us

Developers

  • Get Started Guide
  • API Reference
  • Embedded Banking

More

  • Apiture.com

Privacy Policy

© 2023 Apiture Inc.   |   All Rights Reserved