Audience Builder
Create a new audience
Method
POST
Path
/api/audience-builder
Usage
This endpoint creates a new Audience with the given rules and filters
Parameters
Name | Type | Required | Description |
---|---|---|---|
advertiser_id | number | N | ID of the advertiser to use with the new audience |
category | number | N | ID of the category to assign to the new audience |
data_provider_ids | number list | N | List of IDs for data providers with which a contract has been established to be connected to the audience |
filters | string (JSON) | Y | |
integration_id | number | Y | ID of the platform to use with the new audience |
mailchimpList | string | N* | *When "userPlatform" is "mailchimp" this parameter is required |
marketoList | string | N* | *When "userPlatform" is "marketo" this parameter is required |
optimizelyProject | string | N* | *When "userPlatform" is "optimizely" this parameter is required |
rules | string (JSON) | Y | |
title | string | Y | The name of the new audience |
Example cURL
curl -X POST \ 'https://platform.flxone.com/api/audience-builder?filters=[{%22dimension%22:%22event_url%22,%22include%22:%22mapp%22}]&integration_id=63&platform=flxone&rules=[{%22id%22:%22flx_pixel_id%22,%22comparator%22:%22=%22}]&title=My%20New%20Audience' \ -H 'Cache-Control: no-cache' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK" }, "configuration": { "id": "32087", "type": "custom", "environment": "development", "realtime": "0", "customerId": "1", "categoryId": "0", "userId": "3371", "scheduleId": null, "name": "My New Audience", "configuration": { "rules": "[{"id":"flx_pixel_id","comparator":"="}]", "filters": "[{"dimension":"event_url","include":"mapp"}]", "dimensions": "", "platform": "flxone", "userPlatform": "appnexus", "googleAdvertiser": "", "googleRefreshToken": "", "createGoogleAudience": false, "audienceListId": "", "mailchimpLists": "", "optimizelyProjects": "", "marketoList": "", "integration_id": "623", "xdev": false, "xdev_prob": false, "outputs": [ { "platform_integration_id": 63, "platform": "appnexus", "segments": [ "11353260" ] } ], "map_uids": "appnexus", "query": "SELECT DISTINCT goc.uuid FROM flxone.go_customer_columnar goc WHERE (bdate >= '{$date-7}' AND bdate <= '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') AND (( (("event_url" IN ('mapp'))) )) LIMIT 5000000" }, "cost_per_thousand": null, "size": null, "size_previous": "0", "status": "N/A", "error": null, "enabled": "1", "deleted": "0", "created": "2018-02-05 22:21:43", "modified": "2018-02-05 22:21:43", "last_run": null, "last_bloomfilter_update": null } }
Delete an existing audience
Method
DELETE
Path
/api/audience-builder
Usage
This endpoint deletes the audience which has the given ID.
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | number | Y | The ID of the audience to delete |
Example cURL
curl -X DELETE \ 'https://platform.flxone.com/api/audience-builder?id=' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "delete": true } }
Calculate estimates for audience filters
Method
POST
Path
/api/audience-builder/estimates
Usage
This endpoint posts a filter and gets back the estimates for users, impression, etc. for the dimension/measure in the filter.
Parameters
Name | Type | Required | Description |
---|---|---|---|
filters | string (JSON) | N |
Example cURL
curl -X POST \ 'https://platform.flxone.com/api/audience-builder/estimates?filters=[{%22dimension%22:%22flx_geo_country%22,%22include%22:%22FRA%22}]' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "estimates": [ { "primary_dim": "device_type", "secondary_dim": "4", "agg": "count", "value": 11648 }, { "primary_dim": "device_type", "secondary_dim": "0", "agg": "count", "value": 1364608 }, { "primary_dim": "geo_country", "secondary_dim": "FRA", "agg": "count", "value": 7189280 }, { "primary_dim": "device_type", "secondary_dim": "3", "agg": "count", "value": 2255120 }, { "primary_dim": "impressions", "secondary_dim": "", "agg": "count", "value": 0 }, { "primary_dim": "device_type", "secondary_dim": "1", "agg": "count", "value": 5215728 }, { "primary_dim": "total", "secondary_dim": "", "agg": "count", "value": 9761360 }, { "primary_dim": "device_type", "secondary_dim": "2", "agg": "count", "value": 914256 }, { "primary_dim": "pixels", "secondary_dim": "", "agg": "count", "value": 2263408 }, { "primary_dim": "users", "secondary_dim": "", "agg": "approx_distinct", "value": 7189280 } ] } }
Get a list of existing audiences
Method
GET
Path
/api/audience-builder
Usage
This endpoint gives a list of audiences and categories filtered on the basis of the parameters provided.
Parameters
Name | Type | Required | Description |
---|---|---|---|
audienceType | string | N | Retrieve audiences based on the audience type such as "lookalike" or "custom" |
id | number | N | The ID of the audience to retrieve (if empty, this endpoint returns a list of audiences) |
realtime_eligible | number | N | Flag to retrieve audiences based on realtime eligibility (pass 1 to true, 0 to false) |
userPlatform | string | N | Retrieve audiences for a specific platform such as "appnexus" or "google_dbm" |
Example cURL
curl -X GET \ https://platform.flxone.com/api/audience-builder?audienceType=lookalike&realtime_eligible=0&userPlatform=appnexus \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3'
Output
{ "response": { "status": "OK", "audiences": [ { "id": "1253", "type": "lookalike", "environment": null, "realtime": "0", "customerId": "1", "categoryId": "0", "userId": null, "scheduleId": "3064", "name": "DO NOT REMOVE", "configuration": { "title": "test5", "rules": "[{\"name\":\"Advertiser\",\"id\":\"flx_advertiser_id\",\"type\":\"dimension\",\"value\":\"1234\",\"comparator\":\"=\",\"orRule\":[]}]", "filters": "[{\"dimension\":\"flx_advertiser_id\",\"include\":\"1234\",\"orFilters\":[]}]", "platform": "appnexus", "outputs": [ { "platform": "appnexus", "segments": [ "1948859" ] } ], "query": "SELECT DISTINCT goc.uuid FROM flxone.go_customer_columnar goc WHERE (( (((\"advertiser_id\" = '1234'))) )) AND (bdate >= '{$date-7}') AND (bdate < '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') " }, "cost_per_thousand": null, "size": null, "size_previous": "0", "status": "N/A", "error": null, "enabled": "1", "deleted": "0", "created": "2014-08-11 08:41:17", "modified": "2017-07-31 11:40:02", "last_run": null, "last_bloomfilter_update": "2017-07-31 11:40:02", "user": null } ], "categories": [] } }
Get the job configuration for an existing audience
Method
GET
Path
/api/audience-builder/audience-job-conf
Usage
This gets the JSON (as Base64 encoded string) of an Audience which has the given ID
Parameters
Name | Type | Required | Description |
---|---|---|---|
audienceId | number | Y |
Example cURL
curl -X GET \ 'https://platform.flxone.com/api/audience-builder/audience-job-conf?audienceId=1253' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3'
Output
{ "response": { "status": "OK", "job-conf": "eyJqb2J0eXBlIjoiYXVkaWVuY2VfYnVpbGRlciIsInRpdGxlIjoidGVzdDUiLCJwbGF0Zm9ybSI6ImZseG9uZSIsInF1ZXJ5IjoiU0VMRUNUIERJU1RJTkNUIGdvYy51dWlkIEZST00gZmx4b25lLmdvX2N1c3RvbWVyX2NvbHVtbmFyIGdvYyAgV0hFUkUgICgoICgoKFwiYWR2ZXJ0aXNlcl9pZFwiID0gJzEyMzQnKSkpICkpIEFORCAoYmRhdGUgPj0gJ3skZGF0ZS03fScpIEFORCAoYmRhdGUgPCAneyRkYXRlfScpIEFORCBnb2MudXVpZCBOT1QgSU4gKCcwJywnMScsJzInLCczJywnNCcsJzUnKSAiLCJvdXRwdXRzIjoiW3tcInBsYXRmb3JtXCI6XCJhcHBuZXh1c1wiLFwic2VnbWVudHNcIjpbXCIxOTQ4ODU5XCJdfV0iLCJhdWRpZW5jZV9pZCI6IjE1MyIsImVuZ2luZSI6InByZXN0byIsIm1hcF91aWRzIjpudWxsLCJqb2JfdGltZW91dF9taWxsaXNlY29uZHMiOiIzNjAwMDAwMCIsImN1c3RvbWVyX2lkIjoiMSJ9" } }
Update the target segment name of an existing audience
Method
PUT
Path
/api/audience-builder/name
Usage
This endpoint changes the name of a segment to the provided name (with some branding) for the audience that has the given ID.
Example cURL
curl -X PUT \ 'https://platform.flxone.com/api/audience-builder/name?id=1253&name=SOME%20NEW%20NAME' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: rt81a9dilkkunork1cosp1kb45unvl1giqhvdg4pcde4qkrfq568v1g1o60nilbok3m1kd17pcgobhhgmkp0687dpgsrp521n52uch1' \ -H 'X-CSRF: c219b88cc2c05ea28b05d9308f095c8f'
Output
{ "response": { "status": "OK" } }
Get example data for filters and dimensions
Method
POST
Path
/api/audience-builder/preview-data
Usage
This endpoint gives preview data for each dimension in the parameter.
Parameters
Name | Type | Required | Description |
---|---|---|---|
dimensions | string (JSON) | Y | |
filters | string (JSON) | N | |
platform | string | N | Defaults to appnexus |
Example cURL
curl -X POST \ 'https://platform.flxone.com/api/audience-builder/preview-data?dimensions=[%22flx_event_type%22,%22flx_geo_country%22]&filters=[{%22dimension%22:%22flx_geo_country%22,%22include%22:%22DZA%22}]&platform=flxone' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "data": { "metrics": [ [ "2", "DZA" ], [ "4", "DZA" ] ] } } }
Execute the job for an existing audience
Method
POST
Path
/api/audience-builder/run
Usage
This endpoint runs the job for the given audience ID and returns the job configuration.
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | number | N | The ID of the audience to run (omitting this parameter will not throw an error; however this will mean no action is taken) |
Example cURL
curl -X POST \ 'http://localhost:8080/api/audience-builder/run?id=1253' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "audiences": { "id": "1253", "type": "custom", "environment": null, "realtime": "0", "customerId": "1", "categoryId": "0", "userId": null, "scheduleId": "3064", "name": "DO NOT REMOVE", "configuration": { "title": "test5", "rules": "[{"name":"Advertiser","id":"flx_advertiser_id","type":"dimension","value":"1234","comparator":"=","orRule":[]}]", "filters": "[{"dimension":"flx_advertiser_id","include":"1234","orFilters":[]}]", "platform": "flxone", "outputs": [ { "platform": "appnexus", "segments": [ "1948859" ] } ], "query": "SELECT DISTINCT goc.uuid FROM flxone.go_customer_columnar goc WHERE (( ((("advertiser_id" = '1234'))) )) AND (bdate >= '{$date-7}') AND (bdate < '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') " }, "cost_per_thousand": null, "size": null, "size_previous": "0", "status": "N/A", "error": null, "enabled": "1", "deleted": "0", "created": "2014-08-11 08:41:17", "modified": "2017-07-31 11:40:02", "last_run": null, "last_bloomfilter_update": "2017-07-31 11:40:02" } } }
Manage the job schedule of an existing audience
Method
PUT
Path
/api/audience-builder/schedule
Usage
This endpoint enables or disables the job schedule for the given audience Id based on the "enabled" value and returns the updated job configuration.
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | number | N | The ID of the audience to modify (omitting this parameter will not throw an error; however this will mean no action is taken) |
enabled | number | N | Flag determining if audience's schedule should be activated or deactivated (pass 1 to enable, 0 to disable) |
Example cURL
curl -X PUT \ 'https://platform.flxone.com/api/audience-builder/schedule?id=1253&enabled=1' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "audiences": { "id": "153", "type": "custom", "environment": null, "realtime": "0", "customerId": "1", "categoryId": "0", "userId": null, "scheduleId": "3064", "name": "DO NOT REMOVE", "configuration": { "title": "test5", "rules": "[{"name":"Advertiser","id":"flx_advertiser_id","type":"dimension","value":"1234","comparator":"=","orRule":[]}]", "filters": "[{"dimension":"flx_advertiser_id","include":"1234","orFilters":[]}]", "platform": "flxone", "outputs": [ { "platform": "appnexus", "segments": [ "1948859" ] } ], "query": "SELECT DISTINCT goc.uuid FROM flxone.go_customer_columnar goc WHERE (( ((("advertiser_id" = '1234'))) )) AND (bdate >= '{$date-7}') AND (bdate < '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') " }, "cost_per_thousand": null, "size": null, "size_previous": "0", "status": "N/A", "error": null, "enabled": "1", "deleted": "0", "created": "2014-08-11 08:41:17", "modified": "2017-07-31 11:40:02", "last_run": null, "last_bloomfilter_update": "2017-07-31 11:40:02" } } }
Sharing
Requires Appnexus segment sharing to be configured
Method
GET
Path
/api/audience-builder/sharing
Usage
This endpoint gets the member data sharing if the sharing service is available.
Parameters
none
Example cURL
curl -X GET \ https://platform.flxone.com/api/audience-builder/sharing \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Sharing - Create
Requires Appnexus segment sharing to be configured
Method
POST
Path
/api/audience-builder/sharing
Usage
This endpoint adds the given segment to the already existing member data sharing if the sharing service is available for this member.
Parameters
Name | Type | Required | Description |
---|---|---|---|
buyerMemberId | number | Y | |
integration_id | number | Y | ID of the platform to use with the new audience |
segments | string (JSON) | N | JSON array of segment IDs to add |
Example cURL
curl -X POST \ 'https://platform.flxone.com/api/audience-builder/sharing?buyerMemberId=2321113&integration_id=63&segments=[423,12100,832]' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Regenerate Queries
Method
PUT
Path
/audience-builder/regenerate-queries
Usage
This endpoint checks if any of the queries where changed for given audience. If yes, then the schedule is updated with the new query. This endpoint can only be requested by customers with Admin rights.
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | number | Y | ID of the audience to rebuild |
dry-run | number | N | 1 to perform a dry run of the endpoint |
Example cURL
curl -X PUT \ 'https://platform.flxone.com/api/audience-builder/regenerate-queries?id=153&dry_run=1' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "change_count": 1069, "changes": [ { "id": "102", "customer": "50", "old": "SELECT DISTINCT goc.uuid FROM demosummit.go_customer_orc goc WHERE (bdate >= '{$date-7}' AND bdate < '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') AND (( ((("site_domain" LIKE '%football%'))) AND ((((CAST(day_of_week(date_parse(((( cast(nullif(nullif(lower("bdate"), 'null'), '0') AS varchar)))), '%Y-%m-%d')) As varchar))) IN ('6','7'))) )) ", "new": "SELECT /* audience_id=102 */ DISTINCT goc.uuid FROM demosummit.go_customer_orc goc WHERE (bdate >= '{$date-7}' AND bdate <= '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') AND (( ((("site_domain" LIKE '%football%'))) AND ((((CAST(day_of_week(date_parse(((( cast(nullif(nullif(lower("bdate"), 'null'), '0') AS varchar)))), '%Y-%m-%d')) As varchar))) IN ('6','7'))) )) LIMIT 5000000" }, { "id": "103", "customer": "50", "old": "SELECT DISTINCT goc.uuid FROM demosummit.go_customer_orc goc WHERE (bdate >= '{$date-7}' AND bdate < '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') AND (( (("interaction_type" IN (8))) AND (("interaction_value" IN (75,100))) )) ", "new": "SELECT /* audience_id=103 */ DISTINCT goc.uuid FROM demosummit.go_customer_orc goc WHERE (bdate >= '{$date-7}' AND bdate <= '{$date}') AND goc.uuid NOT IN ('0','1','2','3','4','5') AND (( (("interaction_type" IN (8))) AND (("interaction_value" IN (75,100))) )) LIMIT 5000000" }, !!! TRUNCATED !!! ], "warnings": [ false, false ] } }
Segment
Method
POST
Path
/audience-builder/segment
Usage
This endpoint is used to create segment for given integration id. Only Customers with admin rights can access this endpoint.
Parameters
Name | Type | Required | Description |
---|---|---|---|
integration_id | number | Y | |
title | string | Y |
Example cURL
curl -X POST \ 'https://platform.flxone.com/api/audience-builder/segment?integration_id=1234&title=My%20Segment' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30'
Output
{ "response": { "status": "OK", "created": 11407460 } }
Realtime Matching
Below is the list of requirements for Realtime Matching to be enabled and the errors that will be thrown if requirement is not met:
- Realtime matching is only supported for custom audiences
- All outputs must have platform that supports realtime. If proper supporting platform is not found then realtime matching won’t be enabled and one of the following errors will be thrown: “Platform not found.” , “No platform has been selected.”, “The selected platform does not support real-time matching.”
3. This is a list of allowed metrics:
- 'flx_pixel_id',
- 'event_url',
- 'site_domain',
- 'flx_external_pixel_id',
- 'flx_geo_country',
- 'event_referer_url',
- 'time_on_page',
- 'flx_time_on_site_avg',
- 'flx_day_of_week',
- 'day_of_week',
- 'flx_interaction_segment',
- 'flx_pixels_sum',
- 'daypart',
- 'daypart_minute',
- 'flx_day_in_week',
- 'flx_pixel_loads_dmp',
- 'event_type',
- 'flx_interaction_conversion',
- 'flx_impressions_sum',
- 'flx_clicks_sum',
- 'page_scroll',
- 'flx_scroll_avg',
- 'flx_ad_hover_avg',
- 'flx_contextual_data',
- 'flx_interaction_type',
- 'flx_impclicks_dmp'
4. The “recency” named rule is ignored
5. If rule does not have one of the allowed metrics then rule must have an an external attribute with name having “_ext_attr_”. Otherwise following error will be thrown: “$rule does not support real-time matching (metric)”.
6. If the External Attribute is empty or the source type of external attribute is not external_data or the extraction method of the external attribute is not json_path then following error will be thrown: “The custom data point $rule does not support real-time matching.”
7. If the rule type is “measure” and the rule does not have one of the allowed metrics then following error will be thrown: “$rule does not support real-time matching (custom-data)”
8. If the rule has a comparator then it must be one of these ['=', '!=', 'contains', '>', '>=', '<', '<=', 'before', 'after', 'half', 'end', 'doesnotcontains', 'between’]. Otherwise following error will be thrown: “$comparator comparator does not support real-time matching (comparator)”
9. If there are no aggregation object and the rule does not have one of the allowed metrics then following error will be thrown: “$rule does not support real-time matching (aggregation)”
10. Only calculations that are not attribute are invalid. If externalAttributeJson is not present and the rule does not have one of the allowed metrics and the dsa calculation does not follow the pattern flx_[0-9]_ext_attr_[0-9] for eg: “flx_84_ext_attr_10” then following error will be thrown: “$rule does not support real-time matching (calculations)”