- 2 Minutes to read
User and Audience Data
- 2 Minutes to read
User data can be represented and uploaded in near real-time (~5 minutes) to suit your use case, preferences, and backend implementations.
Format
The DataX Real-Time API provides the following format:
“datax-audience”: A “one-stop-shop” format to upload segments, attributes, and scores using the same JSON format via a single Payload POST on the /audience resource.
Note
Support of attribute uploads will be coming soon.
Metadata
User Data resource collectors define an extension over the Base DataX Online Metadata structure.
JSON Structure
Request body:
{
(Base DataX Online Metadata)
"Schema" : [
"GPSAID",
"IXID",
"IDFA",
"SEGMENTS"
],
"Data" : [
[
"GPSAID1",
"IXID1",
"IDFA1",
"exp=1376244671&seg_id=1234&ts=1376244670;seg_id=5678;seg_id=101112
],
[
"",
"",
"IDFA2",
"seg_id=999;seg_id=12321;seg_id=8787"
]
]
}
Response body:
{
"totalRows": 8,
"processedRows": 6,
"invalidRows": 2,
"exampleInvalidRows": [
"[DXID3, IXID3]",
"[DXID1, IXID1, IDFA1]"
]
}
Response headers
content-type: application/json;charset=utf-8 date: Wed, 31 Dec 2019 19:28:51 GMT transfer-encoding: chunked
Important points above payload
Providers can define their own schema to use for audience data ingestion.
Overall within payload there are NO JSON objects in order to make it as close as possible to a schema-less design.
By defining a “schema” a user specifies how every row in the key “data” of the JSON should be processed.
Possible URN values in the schema are:
“IDFA”
“GPSAID”
“AXID”
“IXID”
“EMAIL”
“PXID”
“SEGMENT_ID”
SEGMENT_ID should always be the last value in the schema list.
Any number of semi-colon separated segment ids can be sent in a row for an user.
12345;01112;459393
If an expiration date needs to be passed (Optional) with a segment id, follow the format as below:
Start with expiration date prefixing it with “&exp=”, so date will be &exp=<UNIX epoch>
Then before the actual segment id prefix it with “&seg_id=”, so it becomes &seg_id=123456
exp=1376244671&seg_id=1234
Finally there will be the timestamp with “&ts=” (Optional).
So overall segment id with expiration will look like: exp=1376244670&seg_id=123456&ts=1376244670
The comma-separated values in each row of the key “data” will be read in the same order as the schema is defined and every row must have the same number of comma separated values.
Supported Values; null, “null” or “ ”)
This schema format gives users the flexibility to send multiple urn types as well segments with or without expiration in the same request.
POST/audience
POST /online/audience
HOST https://dataxonline.yahoo.com/
-H “Authorization: bearer: <obtained token>”
-H “Content-Type: application/json”
{"schema":["IXID","IDFA","GPADVID","SEGMENTS"],"data":[["","IXID1","","exp=1576346458&seg_id=1234&ts=1376244670;6789;1010"],["","IXID2","IDFA2","seg_id=14444;8777;exp=15763464583&seg_id=2322"],["IXID3","IDFA3","GPADVID3","exp=1576346458&seg_id=4555;3333;9919"]]}
Error Responses
Error Code | Error Message | Description |
DXOL5xx | UNABLE_TO_PROCESS_REQUEST | Server was not available during the processing time. |
DXOL429 | Exceeded rate limit, calls are not permitted at this time, try again later. | Hourly rate limit has been reached. Please wait and try again at the top of the hour. |
DXOL4xx | INVALID_SCHEMA | Missing SEGMENTS from schema. |
DXOL4xx | DUPLICATE_URN_TYPE | Duplicate URN type in schema. |
DXOL4xx | TOO_MANY_DATA_ROWS | More than 10k rows have been identified in this payload. |
DXOL4xx | INVALID_ACCESS_TOKEN | Oauth 2.0 access token has expired. Please generate a new token. |