Segmentation Studio
date: "2023-09-05" Author: "Sinisa Jovic"
Intro Steps
The first step to create audience through API is to access the API documentation on the link: Segmentation Studio API and it looks something like this:
Header parameters
| Name | Value | Description |
|---|---|---|
Authorization required |
Bearer |
Token is retriveing called Auth API |
Content Type required |
application/json |
Create audience
Let’s create one segment with people between 37-74 years, having email consent - True, customer lifetime value between 0 and 1193, that also purchased item i_8732 in the last 180 days. When creating an audience, users can choose between static and dynamic audience. Dynamic audience is recalculating each time the user wants - with the same filters.
You can create new audience with next request:
curl -X POST "https://dev.thingsolver.com/api/latest/customer-studio/audiences" \
-H "Content-Type: application/json" \
-d '{
"audience_name": "New Segmentation Audience 1409",
"author": "Violeta",
"status": "created",
"is_dynamic": false,
"audience_type": "customers",
"recommendations_export": {
"export_type": "recommender",
"recommendations_type": "default",
"number_of_recommendations": 10
},
"filters": [
{
"filter_group": "demographics",
"filter_group_order": 0,
"next_group_connector": "AND",
"values": [
{
"filter_name": "age",
"filter_entity": "customer",
"filter_type": "BETWEEN",
"filter_order": 0,
"filter_value_connector": "AND",
"filter_values": {
"value_name": "age",
"min_value": 37,
"max_value": 74
}
},
{
"filter_name": "email_consent",
"filter_entity": "customer",
"filter_type": "IN",
"filter_order": 1,
"filter_value_connector": "AND",
"filter_values": ["True"]
}
]
},
{
"filter_group": "customer-lifetime-value",
"filter_group_order": 1,
"next_group_connector": "AND",
"values": [
{
"filter_name": "customer-lifetime-value",
"filter_entity": "customer",
"filter_type": "BETWEEN",
"filter_order": 0,
"filter_value_connector": "AND",
"filter_values": {
"value_name": "clv",
"min_value": 0,
"max_value": 1193
}
}
]
},
{
"filter_group": "product-focused-filters",
"filter_group_order": 2,
"next_group_connector": "AND",
"values": [
{
"filter_name": "purchases-180-days",
"filter_entity": "product_id",
"filter_type": "IN",
"filter_order": 0,
"filter_value_connector": "OR",
"filter_values": ["i_8732"]
}
]
}
]
}'
{
"audience_id":"audience-id-ed48b0196ab743dbbccd3b172d7ba638",
"audience_name":"New Segmentation Audience 1409",
"audience_type":"customers",
"author":"Violeta",
"status":"created",
"is_dynamic":false,
"recommendations_export":{
"export_type":"recommender",
"recommendations_type":"default",
"number_of_recommendations":10
},
"filters":[
{
"filter_group":"demographics",
"filter_group_order":0,
"next_group_connector":"AND",
"values":[
{
"filter_name":"age",
"filter_type":"BETWEEN",
"filter_entity":"customer",
"filter_value_connector":"AND",
"filter_order":0,
"filter_values":{
"value_name":"age",
"min_value":37,
"max_value":74
},
"count_before":null,
"count_now":null,
"filtered_percentage":null
},
{
"filter_name":"email_consent",
"filter_type":"IN",
"filter_entity":"customer",
"filter_value_connector":"AND",
"filter_order":1,
"filter_values":[
"True"
],
"count_before":719303,
"count_now":165496,
"filtered_percentage":"76.99"
}
]
},
{
"filter_group":"customer-lifetime-value",
"filter_group_order":1,
"next_group_connector":"AND",
"values":[
{
"filter_name":"customer-lifetime-value",
"filter_type":"BETWEEN",
"filter_entity":"customer",
"filter_value_connector":"AND",
"filter_order":0,
"filter_values":{
"value_name":"clv",
"min_value":0,
"max_value":1193
},
"count_before":165496,
"count_now":164136,
"filtered_percentage":"0.82"
}
]
},
{
"filter_group":"product-focused-filters",
"filter_group_order":2,
"next_group_connector":"AND",
"values":[
{
"filter_name":"purchases-180-days",
"filter_type":"IN",
"filter_entity":"product_id",
"filter_value_connector":"OR",
"filter_order":0,
"filter_values":[
"i_8732"
],
"count_before":164136,
"count_now":2,
"filtered_percentage":"99.99"
}
]
}
],
"is_uploaded":false,
"is_ready":null,
"audience_size":2,
"date_created":"2023-09-14T08:04:51",
"date_modified":"2023-09-14T08:05:04"
}
Update audience
You can edit audience with PUT request like this:
PUT https://dev.thingsolver.com/api/latest/customer-studio/audiences
- NOTE: You can only edit audience that has status
draft
Request and response are the same as the previous (for creating audience).
Delete audience
Audience can be deleted with simple DELETE request
Get customers lists
This method allows you to collect info about created audiences with details including: customers first, last name, address, city, customer lifetime value, segment or even recommended products.
{
"offset":0,
"limit":10,
"count":139399,
"customers":[
{
"customer_id":"cu_28794",
"first_name":"Darlene",
"last_name":"Burgess",
"phone_number":null,
"email":null,
"gender":"female",
"age":null,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":160.808,
"product_1":"i_16456",
"product_2":"itm_2301",
"product_3":"i_4820",
"product_4":"i_12339",
"product_5":"itm_14353",
"product_6":"it_2250",
"product_7":"itms_5335",
"product_8":"it_4571",
"product_9":"i_7979",
"product_10":"i_15430"
},
{
"customer_id":"cu_31845",
"first_name":"Amber",
"last_name":"Davis",
"phone_number":null,
"email":null,
"gender":"female",
"age":null,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":111.99200000000002,
"product_1":"i_2540",
"product_2":"i_14173",
"product_3":"i_76",
"product_4":"i_39",
"product_5":"i_326",
"product_6":"i_265",
"product_7":"i_16",
"product_8":"i_128",
"product_9":"i_658",
"product_10":"i_101"
},
{
"customer_id":"cu_33006",
"first_name":"Edward",
"last_name":"Barrera",
"phone_number":null,
"email":null,
"gender":"male",
"age":null,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":233.588,
"product_1":"i_803",
"product_2":"i_617",
"product_3":"i_14358",
"product_4":"i_637",
"product_5":"i_503",
"product_6":"i_1616",
"product_7":"i_464",
"product_8":"i_409",
"product_9":"i_171",
"product_10":"i_14435"
},
{
"customer_id":"cu_42425",
"first_name":"Travis",
"last_name":"Cook",
"phone_number":null,
"email":null,
"gender":"male",
"age":null,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":82.18400000000001,
"product_1":"i_1",
"product_2":"i_2540",
"product_3":"i_39",
"product_4":"i_32",
"product_5":"i_89",
"product_6":"i_5",
"product_7":"i_167",
"product_8":"i_658",
"product_9":"i_101",
"product_10":"i_90"
},
{
"customer_id":"cu_46685",
"first_name":"Kari",
"last_name":"Nelson",
"phone_number":null,
"email":null,
"gender":"female",
"age":null,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":103.984,
"product_1":"i_3135",
"product_2":"i_17223",
"product_3":"i_4659",
"product_4":"i_122",
"product_5":"i_209",
"product_6":"i_2652",
"product_7":"i_215",
"product_8":"i_658",
"product_9":"i_1241",
"product_10":"i_88"
},
{
"customer_id":"c_101160",
"first_name":"Leslie",
"last_name":"Fuentes",
"phone_number":null,
"email":null,
"gender":"mostly_female",
"age":50,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":167.99200000000002,
"product_1":"i_837",
"product_2":"i_37",
"product_3":"i_617",
"product_4":"i_409",
"product_5":"i_2654",
"product_6":"i_364",
"product_7":"i_2953",
"product_8":"i_338",
"product_9":"i_2148",
"product_10":"i_277"
},
{
"customer_id":"c_104186",
"first_name":"Jack",
"last_name":"Bowman",
"phone_number":null,
"email":null,
"gender":"male",
"age":53,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":45.592000000000006,
"product_1":"i_1",
"product_2":"i_4327",
"product_3":"i_803",
"product_4":"i_100",
"product_5":"i_902",
"product_6":"i_190",
"product_7":"i_41",
"product_8":"i_13547",
"product_9":"i_507",
"product_10":"i_630"
},
{
"customer_id":"c_11028",
"first_name":"Austin",
"last_name":"Cox",
"phone_number":null,
"email":null,
"gender":"male",
"age":43,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":79.992,
"product_1":"i_567",
"product_2":"i_17111",
"product_3":"i_15",
"product_4":"i_274",
"product_5":"i_1370",
"product_6":"i_4332",
"product_7":"i_213",
"product_8":"i_17222",
"product_9":"i_402",
"product_10":"i_6257"
},
{
"customer_id":"c_114079",
"first_name":"Wendy",
"last_name":"Jones",
"phone_number":null,
"email":null,
"gender":"female",
"age":35,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":95.984,
"product_1":"i_17223",
"product_2":"i_215",
"product_3":"i_690",
"product_4":"i_362",
"product_5":"i_17221",
"product_6":"i_540",
"product_7":"i_803",
"product_8":"i_742",
"product_9":"i_2267",
"product_10":"i_2652"
},
{
"customer_id":"c_117697",
"first_name":"Ashley",
"last_name":"Gray",
"phone_number":null,
"email":null,
"gender":"mostly_female",
"age":37,
"city":"Rebekahburgh",
"segment_id":"3",
"segment_name":"standard",
"clv_value":119.99200000000002,
"product_1":"i_61",
"product_2":"i_103",
"product_3":"i_338",
"product_4":"i_17111",
"product_5":"i_567",
"product_6":"i_56",
"product_7":"i_1160",
"product_8":"i_66",
"product_9":"i_111",
"product_10":"i_251"
}]}
Export audience
Mail validity
You only have 6 minutes to download the audience, after that link expires.
Export audience feature is similar to previous, just download customers from audience in .csv or .xlsx file. File is sent to your email address and you can download it from the link.