Manage Target Account Lists

This guide is for RollWorks customers or partners that are interested in managing their Target Account Lists (TAL) via the NextRoll Audience API. By managing your TAL via the API, you can enable cross-channel orchestration:

• Push your list of Accounts from RollWorks into a complementary platform that enables personalized experiences

• Pull a dynamic list of accounts into RollWorks to advertise to accounts that are showing high intent

Get to know Target Account Lists

Target Account Lists have a simple object structure. It’s best introduced visually:

A Target Account List (TAL) is used in Account-Based Marketing and represents your current accounts or prospects.

A Tier is an Account Group and is used to group similar Accounts.

An Item is an Account that is a prospective or current customer.

An Advertisable can have multiple Target Account Lists, with each TAL organized into multiple Account Groups. An Account can exist in multiple TALs, but only in a single Account Group per TAL. So, for example, two Account Groups in a TAL won’t have overlapping Accounts.

Retrieve all Target Account Lists

To retrieve the Target Account Lists (TAL) in your Advertisable, call to GET /audience/v1/target_accounts.

Retrieve the Accounts in a Target Account List

Target Account Lists (TAL) contain one or more Tiers (aka Account Groups), so you’ll first need to retrieve the list of Tiers. This is done by calling GET /audience/v1/target_accounts/(tal_eid)/tiers.

There are at least two Tiers in each TAL that you can query using a special Tier ID:

all

Includes all Items in the TAL, even if the Item is in another list

untiered

Contains Items that aren’t assigned to any other Tier

Once you have a Tier EID, you can retrieve the list of Items (aka Accounts) within the Tier. The list of Items can be long, so the endpoint supports pagination using the limit and offset query parameters.

GET /audience/v1/target_accounts/(tal_eid)/tiers/(ta_tier_eid)/items

Add an Account to a Target Account List

Target Account Lists (TAL) are organized into one or more Tiers (aka Account Groups), so you’ll first need to retrieve the list of Tiers. This is done by calling GET /audience/v1/target_accounts/(tal_eid)/tiers.

Once you have a Tier EID, you can add the Account by calling POST /audience/v1/target_accounts/(tal_eid)/tiers/(ta_tier_eid)/items.

The request body looks like:

{
  "items": [
    {
      "domain": "example1.com",
    },
    {
      "domain": "example2.com",
    }
  ]
}

Remove an Account from a Target Account List

Target Account Lists (TAL) are organized into one or more Tiers (aka Account Groups), so you’ll first need to retrieve the list of Tiers. This is done by calling GET /audience/v1/target_accounts/(tal_eid)/tiers.

Once you have a Tier EID, you can remove one or more Accounts by calling DELETE /audience/v1/target_accounts/(tal_eid)/tiers/(ta_tier_eid)/items

The request looks like:

{
  "domains": [
    "example1.com",
    "example2.com"
  ]
}