Lookalikes & CRM Audiences v.2
Lookalike Audience
Lookalike Audience can be created based on the existing CRM Audience.
Use similarity percentage to set how similar newly created audience should be to the parent audience.
GET /audiences/v1/crm_audiences
{
"summary": {
"total_count": 1,
"crm_count": 1,
"lookalike_count": 0,
"timestamp": "2022-10-19T16:53:24.766987"
},
"result": [
{
"audience_id": "MfDgLzoYZy5u",
"status": "PROCESSING_SUCCEEDED",
"audience_type": "crm_audience",
"name": "Have no colour preferences buying a car",
"time_created": "2022-10-19T16:53:10.210022",
"device_count": 25132,
"profile_count": null
}
]
}Get list of existing audiences
In the example request has returned a list that contains one audience.
Each audience fields: name, audience_id and device_count
The device_count for CRM audience we want to use as a parent for lookalikes must greater than 999.
Get the audience_id and move to the next step
POST /v2/lookalike
{
"origin_crm_audience_id": "MfDgLzoYZy5u",
"similarity_percentage": 70
}Response:
{
"id": "AQKqgovlgf2W",
"origin_crm_audience_id": "MfDgLzoYZy5u",
"origin_pixel_audience_id": null,
…
"status": "PROCESSING_IN_PROGRESS"
}Create lookalike audience
The request body consists of fields:
origin_crm_audience_id - contains parent CRM audience_id
similarity_percentage - an integer between 10 and 90
Use the value of the “id” field to get the status of the newly created audience.
GET /v2/lookalike/<lookalike_audience_id>
{
"id": "AQKqgovlgf2W",
"origin_crm_audience_id": "MfDgLzoYZy5u",
"origin_pixel_audience_id": null,
"similarity_percentage": 70,
"device_count": null,
"status": "PROCESSING_IN_PROGRESS",
}Check Audiences status
Use this endpoint to check audience status.
The most important fields are device_count and status.
The max time when those fields can be updated is 24 hours since the audience was created.
DELETE /v2/lookalike/<lookalike_audience_id>
{
"success": true
}Delete Lookalike Audience
Use audience id in this method if you need to delete it.
Successful response we can see in the example.
CRM Audiences
Upload data with one time salt
POST /v1/crm_audiences/<audience_id>uploads?salt_source=upload
Response:
{
"upload_id": "Pw9cH3yMvyVPAPIa",
"salt": "5t2MDy7bdnRMs9WMKjWjFZoyLVwcCmni"
}Create a New Upload
The upload_id must be provided in the next endpoint
CSV file content example:
email,phone
zinedine.zintonic@gmail.com,+358502222333
tapio.branvinn@hotmail.com,+358501234567
romeo.freesoul@hotmail.com,+358502222339
,+358502227493
max.power@gmail.com,
Prepare your data
If file contains more than 10000 rows split it into several files.
Script:
from hashlib import sha256
import pandas as pd
def main(csv_input, json_out, salt=""):
df = pd.read_csv(csv_input, header="infer", sep=",", dtype=str)
for column in df.columns:
df[column] = df[column].map(lambda value: hash_value(value, salt))
df.to_json(json_out, orient="split", index=False)
def hash_value(value_to_hash, salt):
return str(sha256((salt + str(value_to_hash)).encode("utf-8")).hexdigest())
csv_input = "./crm.csv"
json_out = "./out.json"
salt = "5t2MDy7bdnRMs9WMKjWjFZoyLVwcCmni"
main(csv_input, json_out, salt)
Hash data
Use the script in the right side to hash your data
The crm.csv file should contain data prepared on the previous step.
The out.json will contain hashed data.
Install pandas and run the script:
pip3 install pandas && python3 script.py
POST /v2/crm_audiences/<AUDIENCE_ID>/uploads/<UPLOAD_ID>?is_last_batch=true
Sample data:
{
"columns": [
"email",
"phone"
],
"data": [
[
"600177c7ec796415286c…f47af8fdbc04a12d53cac39671ca",
"69d593112aceba52…4c1e36194042bc8cdef7ee3c8f36a620"
],
[
"a65dd70b7fe6…fd9057d1cab9chkj262941e7fa573ae05a9bd",
"d22c28f01e…t7tryh81431cf3a81d67bf1aa72654b340f0fa39"
],
[
"816da3b42b21dd…3b96a24afe77b4c6bf3341a76575018131",
"ce471b88b196f7bd4…2be7bac1984dc89224720d56c0f3de4"
]
]
}Response:
{
"message": "Uploaded successfully",
"status": "200"
}Upload Data
Use is_last_batch=false for mulpipart upload.
The last upload must have is_last_batch=true
Please carefully check the content of file you are sending. It must have same structure as in the example.
DELETE /crm_audiences/<AUDIENCE_ID>/
{
"success": true
}Delete audience
If the audience is not needed anymore, it can be deleted by using this endpoint.
Successful response we can see in the example.
Upload data with constant salt
CSV file content example:
email,phone
zinedine.zintonic@gmail.com,+358502222333
tapio.branvinn@hotmail.com,+358501234567
romeo.freesoul@hotmail.com,+358502222339
,+358502227493
max.power@gmail.com,
Prepare your data
If file contains more than 10000 rows split it into several files.
POST /v1/crm_audiences/<audience_id>uploads?salt_source=advertiser
Response:
{
"upload_id": "Pw9cH3yMvyVPAPIa"
}Create a New Upload
The upload_id must be provided in the next endpoint.
POST /v2/crm_audiences/<AUDIENCE_ID>/uploads/<UPLOAD_ID>?is_last_batch=true
Upload Data
Send the csv data. It will be hashed and stored.
Use is_last_batch=false for mulpipart upload.
The last upload must have is_last_batch=true
Please carefully check the content of file you are sending. It must have same structure as in the example.