User and Audience Data

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.