Introduction to the Customer Lists API

The Customer Lists API provides a powerful new way to leverage your external data for segmentation by syncing customer lists directly into Optimove. With this new capability, you can now upload fixed customer segments and reuse them across multiple campaigns, offering greater flexibility and efficiency for your marketing efforts.

Key Benefits

Leverage External Segments: Directly utilize customer segments from your external data sources (like a data warehouse or CDP) for highly precise and consistent targeting across all campaigns.
Improve Efficiency: Save time by maintaining and reusing fixed customer segments for multiple campaigns, eliminating the need to re-upload lists repeatedly.

Core Functionality and Use Cases

The API provides several endpoints to manage customer lists and integrate them with target groups (TGs). Here are some key use cases and how to achieve them using the API.

Note: The details of a synced list are visible in the UI within the context of the specific Target Group that utilizes it.

Use Case 1: Create a New Customer List and Target Group

This is the most common use case, where you create a new list of customers and a corresponding new TG that includes this list as one of the TG's conditions.

API Call: POST api/v2/target-group/customer-list

Body:

{
  "list-name": "string",
  "customers": ["string", "anotherstring"]
}

list-name: A unique name for your new customer list.
customers: An array of customer IDs (strings) to be included in the list.

Response:
Upon success, the API returns details about the newly created list and TG, including their IDs.

{
  "target-group-id": 12345,
  "list-id": "string",
  "list-name": "string",
  "existed-customers": 1000,
  "non-existed-customers": ["string"]
}

target-group-id: The ID of the new TG created.
list-id: The unique ID of the customer list created.
existed-customers: The number of customers from the list that exist in Optimove.
non-existed-customers: A list of customer IDs that were not found in Optimove.

Failures (Error Code 400):

List is empty
List name not unique
List contains only not valid CIDs
List limit was reached (more than 500K)

Use Case 2: Add a Customer List to an Existing Target Group

If you have an existing TG and want to add a new customer list to it, you can use the following endpoint.

API Call: PUT api/v2/target-group/customer-list

Body:

{
  "list-name": "string",
  "customers": ["string", "anotherstring"],
  "target-group-id": 12345
}

list-name: A unique name for the new list being added to the TG.
customers: An array of customer IDs to be included in the list.
target-group-id: The ID of the existing TG you want to add the list to.

Response:
A successful response returns the TG and list details.

{
  "target-group-id": 12345,
  "list-id": "string",
  "list-name": "string",
  "existed-customers": 1000,
  "non-existed-customers": ["string"]
}

Failures (Error Code 400):

List is empty
List name not unique
List contains only not valid CIDs
List limit was reached (more than 500K)
TG contains more than 10 conditions of Customer List
TG contains more than 20 conditions
TG contains complex selection\ expression
TG was not found
TG type “visitors” is not supported

Additional API Endpoints

Beyond the core use cases, the API offers other functionalities to manage your lists and TGs.

Editing Lists

You can replace a list's content:

Replace a list's content: Use PUT api/v2/target-group/customers.

Getting List Data

Retrieve all customers in a list: Use GET /target-group/customer-list/{list-id}. This supports pagination using optional skip and take parameters.
Retrieve metadata for all lists: Use GET /target-group/customer-lists/metadata.

Limitations and Constraints

Keep the following limitations in mind when using the API:

List Size: A single list can contain up to 500,000 customers.
Lists in a TG: A single TG can contain up to 10 customer lists.
Total Conditions: A single TG is limited to 20 conditions in total.
Optimal Requests: Requests up to 100,000 are the most optimal. Requests above this will take longer.