POST
/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 |
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' |
{ "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
/api/audience-builder
This endpoint deletes the audience which has the given ID.
Name | Type | Required | Description |
---|---|---|---|
id | number | Y | The ID of the audience to delete |
curl -X DELETE \ 'https://platform.flxone.com/api/audience-builder?id=' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30' |
{ "response": { "status": "OK", "delete": true } } |
POST
/api/audience-builder/estimates
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 |
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' |
{ "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
/api/audience-builder
This endpoint gives a list of audiences and categories filtered on the basis of the parameters provided.
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" |
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' |
{ "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
/api/audience-builder/audience-job-conf
This gets the JSON (as Base64 encoded string) of an Audience which has the given ID
Name | Type | Required | Description |
---|---|---|---|
audienceId | number | Y |
curl -X GET \ 'https://platform.flxone.com/api/audience-builder/audience-job-conf?audienceId=1253' \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' |
{ "response": { "status": "OK", "job-conf": "eyJqb2J0eXBlIjoiYXVkaWVuY2VfYnVpbGRlciIsInRpdGxlIjoidGVzdDUiLCJwbGF0Zm9ybSI6ImZseG9uZSIsInF1ZXJ5IjoiU0VMRUNUIERJU1RJTkNUIGdvYy51dWlkIEZST00gZmx4b25lLmdvX2N1c3RvbWVyX2NvbHVtbmFyIGdvYyAgV0hFUkUgICgoICgoKFwiYWR2ZXJ0aXNlcl9pZFwiID0gJzEyMzQnKSkpICkpIEFORCAoYmRhdGUgPj0gJ3skZGF0ZS03fScpIEFORCAoYmRhdGUgPCAneyRkYXRlfScpIEFORCBnb2MudXVpZCBOT1QgSU4gKCcwJywnMScsJzInLCczJywnNCcsJzUnKSAiLCJvdXRwdXRzIjoiW3tcInBsYXRmb3JtXCI6XCJhcHBuZXh1c1wiLFwic2VnbWVudHNcIjpbXCIxOTQ4ODU5XCJdfV0iLCJhdWRpZW5jZV9pZCI6IjE1MyIsImVuZ2luZSI6InByZXN0byIsIm1hcF91aWRzIjpudWxsLCJqb2JfdGltZW91dF9taWxsaXNlY29uZHMiOiIzNjAwMDAwMCIsImN1c3RvbWVyX2lkIjoiMSJ9" } } |
PUT
/api/audience-builder/name
This endpoint changes the name of a segment to the provided name (with some branding) for the audience that has the given ID.
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' |
{ "response": { "status": "OK" } } |
POST
/api/audience-builder/preview-data
This endpoint gives preview data for each dimension in the parameter.
Name | Type | Required | Description |
---|---|---|---|
dimensions | string (JSON) | Y | |
filters | string (JSON) | N | |
platform | string | N | Defaults to appnexus |
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' |
{ "response": { "status": "OK", "data": { "metrics": [ [ "2", "DZA" ], [ "4", "DZA" ] ] } } } |
POST
/api/audience-builder/run
This endpoint runs the job for the given audience ID and returns the job configuration.
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) |
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' |
{ "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" } } } |
PUT
/api/audience-builder/schedule
This endpoint enables or disables the job schedule for the given audience Id based on the "enabled" value and returns the updated job configuration.
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) |
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' |
{ "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" } } } |
Requires Appnexus segment sharing to be configured
GET
/api/audience-builder/sharing
This endpoint gets the member data sharing if the sharing service is available.
none
curl -X GET \ https://platform.flxone.com/api/audience-builder/sharing \ -H 'Cache-Control: no-cache' \ -H 'X-Auth: es5a88dmlpktb5t6k9eifm6Pqjd0l70otkm1p2dv6g13h3h2thkptomb3k8dqe3ms3Xvorgr72h99uec0n92mf9hki9d23aprtsmds3' \ -H 'X-CSRF: 14f61670139eb434adf7f148bbea1a30' |
Requires Appnexus segment sharing to be configured
POST
/api/audience-builder/sharing
This endpoint adds the given segment to the already existing member data sharing if the sharing service is available for this member.
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 |
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' |
PUT
/audience-builder/regenerate-queries
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.
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 |
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' |
{ "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 ] } } |
POST
/audience-builder/segment
This endpoint is used to create segment for given integration id. Only Customers with admin rights can access this endpoint.
Name | Type | Required | Description |
---|---|---|---|
integration_id | number | Y | |
title | string | Y |
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' |
{ "response": { "status": "OK", "created": 11407460 } } |
Below is the list of requirements for Realtime Matching to be enabled and the errors that will be thrown if requirement is not met:
3. This is a list of allowed metrics:
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)”