Introduction to the Customer Lists API

The Customer Lists API allows you to sync customer lists directly into Optimove, offering greater flexibility and efficiency in managing customer data for campaigns. This feature addresses the current limitation of single-use uploads for individual campaigns by enabling you to upload and reuse fixed customer segments across multiple campaigns.

Key Benefits

Efficiency: Maintain and reuse fixed customer segments across multiple campaigns without needing to re-upload lists repeatedly.
Precision: Achieve more precise and effective customer engagement by utilizing persistent, managed customer segments.

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 lists will also be visible in the UI.

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.