Batch upload requests

An audience data batch file is a pipe-delimited text file that contains a collection of audience data rows. Each audience data row represents a viewer, who is tied to a unique Persistent identifier (PID), and specifies the audience segmentations and audience segments the viewer belongs to so INVIDI Pulse can target them accordingly. The audience data batch files are uploaded to and stored in your region's session store (either eu or asia).

The batch upload requests allow you to populate the session store with audience data for your viewers (add and update), remove audience data for your viewers from the session store, cancel an upload of an audience data batch file, and retrieve batch progress information and details related to any issues with the provided segmentations and segments. You can upload only one audience data batch file per audience provider per day.

This page provides examples for the following requests:

Request body

The body of the request is the audience data batch file, which can contain a maximum of 10 million rows.

To assign viewers to existing segmentations and segments, or subsequently make updates to any of the segmentations and segments, each row must contain the viewer's PID and any number of segmentationKey=segmentKey value pairs. The fields must be separated by | (pipe) delimiter. For more information on segmentationKey and segmentKey values, see Data integration structure.

PID|segmentationKey=segmentKey|segmentationKey=segmentKey|segmentationKey=segmentKey
PID|segmentationKey=segmentKey|segmentationKey=segmentKey|segmentationKey=segmentKey
PID|segmentationKey=segmentKey|segmentationKey=segmentKey|segmentationKey=segmentKey

To update segmentations and segments assigned to your viewers, you only need to pass in the rows you are updating and provide both the unchanged and changed segmentationKey=segmentKey value pairs. If a previously existing segmentationKey=segmentKey value pair for the updated row is not present, it is cleared from the session store.

To remove audience data for your viewers from the sessions store, a row must only include the PID of the viewer you want to remove.

PID|segmentationKey=segmentKey|segmentationKey=segmentKey|segmentationKey=segmentKey
PID
PID|segmentationKey=segmentKey|segmentationKey=segmentKey|segmentationKey=segmentKey
PID

You can also bulk remove audience data from the session store by uploading files that only include rows with the PID of each viewer you want to remove.

PID
PID
PID

Batch upload audience data

This endpoint is used to populate the session store with audience data for your viewers, as well as to remove audience data for your viewers from the session store. You can:
  • Assign viewers to existing segmentations and segments
  • Update segmentations and segments assigned to viewers
  • Remove audience data for viewers
Note:

In Pulse, a viewer can only be matched to a single audience segment within an audience segmentation. This is not a problem, for example, for age and gender, where a viewer can only belong to one age segment and one gender segment.

However, you might want to target a viewer based on multiple interests, but this is not supported in Pulse in case all possible interests fall under the same segmentation in your audience definitions. If you run into this scenario, contact our Customer Solutions team to find alternative ways of defining your audience segmentations and audience segments.

Pulse makes sure you are passing in a case-sensitive match to the segmentationKey and segmentKey values that exist for the audience provider you specify in this endpoint. Segmentations and segments that do not exist, or do not exactly match what is configured for the audience provider, are returned as invalidSegments (an array of invalid segmentationKey=segmentKey value pairs) and specified in the details object when you use the Get progress information for batch endpoint.

For a PID with audience data previously stored in the session store:
  • If a row contains only invalid segmentationKey=segmentKey value pairs, then the previously existing audience data for that PID is retained in the session store.
  • If a row contains both valid and invalid segmentationKey=segmentKey value pairs, the invalid ones are not ingested into session store, and the valid ones are ingested and update (replace) the previously existing audience data for that PID.

If the same PID is present in multiple rows, but with different audience data, only the data in the last entry is ingested into session store. Duplicate rows and duplicate segmentationKey=segmentKey value pairs in a single row do not result in duplicate data.

Limitations

  • You can upload only one audience data batch file per audience provider per day.
  • The audience data batch file can contain a maximum of 10 million rows.
Method POST
URL You must prefix the URL with your region, either eu for European customers or asia for Asian customers.
  • Europe: https://eu.api.videoplaza.com/v1/audience/batch
  • Asia: https://asia.api.videoplaza.com/v1/audience/batch
Header Authentication header (x-o-api-key)
Content type text/csv
Content encoding (Optional) gzip: to make the upload faster
URL params -
Query params
  • (Required) providerId: audience provider ID, which can be retrieved using Audience provider requests
  • (Optional) region: to check if you are using the correct regional URL. Possible values are:
    • eu for Europe
    • asia for Asia
Body Request body
Success response

HTTP status: 202 Accepted

Header: -

Body:

{
  "batchId": "<string>",
  "status": "UPLOADED",
  "link": "/v1/audience/batch/{id}"
}

Example: Assign viewers to segmentations and segments

Request header

POST /v1/audience/provider/batch?providerId=a2b5d2a6-f901-40a9-a3c9-29defd019dde HTTP/1.1
Host: api.videoplaza.com
Content-type: text/csv
x-o-api-key="<your key>"

Request body:

012|1=a|2=a|3=b|4=c
111|1=b|2=b|3=c|4=d
222|1=b|2=a|3=a|4=d
abc|1=a|2=a|3=b|4=c
xyz|1=b|2=b|3=c|4=b

Success response

HTTP status:
  202 Accepted

Body:
{
  "batchId": "94c5c9ec-9429-4838-ba78-0d50d24e1f00",
  "status": "UPLOADED",
  "link": "/v1/audience/batch/94c5c9ec-9429-4838-ba78-0d50d24e1f00"
}

Example: Update segmentations and segments assigned to viewers

This example updates three audience data rows from the example above. The updated rows include both the unchanged and changed segmentationKey=segmentKey value pair, but they are missing some of the segmentationKey=segmentKey value pair assigned to viewers in the example above. This means that only the provided segmentationKey=segmentKey value pairs are ingested into session store, and the missing ones are cleared from the session store.

Request header

POST /v1/audience/provider/batch?providerId=a2b5d2a6-f901-40a9-a3c9-29defd019dde HTTP/1.1
Host: api.videoplaza.com
Content-type: text/csv
x-o-api-key="<your key>"

Request body:

111|1=b|2=a
abc|3=c|4=c
xyz|1=a|2=b|4=c

Success response

HTTP status:
  202 Accepted

Body:
{
  "batchId": "dc74b090-c275-4646-a37f-4d5cff09997a",
  "status": "UPLOADED",
  "link": "/v1/audience/batch/dc74b090-c275-4646-a37f-4d5cff09997a"
}

Example: Bulk remove audience data for viewers

Request header

POST /v1/audience/provider/batch?providerId=a2b5d2a6-f901-40a9-a3c9-29defd019dde HTTP/1.1
Host: api.videoplaza.com
Content-type: text/csv
x-o-api-key="<your key>"

Request body:

111
abc
xyz

Success response

HTTP status:
  202 Accepted

Body:
{
  "batchId": "9255e1bc-daee-40a5-9ca6-41328c7e5e23",
  "status": "UPLOADED",
  "link": "/v1/audience/batch/9255e1bc-daee-40a5-9ca6-41328c7e5e23"
}

Get progress information for batch

This endpoint allows you to get progress information for an audience data batch file upload and notifies you if there are any invalid segmentations and segments in your files. The audience data in the files is validated against the segmentationKey and segmentKey values that exist for the audience provider specified in the Batch upload audience data endpoint.

Segmentations and segments that do not exist, or do not exactly match what is configured for the audience provider, are returned as invalidSegments and specified in the details object, which returns the number or rows with invalid segmentationKey=segmentKey value pairs and lists them.

For a PID with audience data previously stored in the session store:
  • If a row contains only invalid segmentationKey=segmentKey value pairs, then the previously existing audience data for that PID is retained in the session store.
  • If a row contains both valid and invalid segmentationKey=segmentKey value pairs, the invalid ones are not ingested into session store, and the valid ones are ingested and update (replace) the previously existing audience data for that PID.
A batch can have the following progress statuses:
  • PROCESSING: The batch is processing
  • CANCELLED: The batch has been cancelled through Cancel batch upload endpoint
  • PROCESSING_FINISHED: Processing for the batch has finished
Method GET
URL You must prefix the URL with your region, either eu for European customers or asia for Asian customers.
  • Europe: https://eu.api.videoplaza.com/v1/audience/batch/{id}
  • Asia: https://asia.api.videoplaza.com/v1/audience/batch/{id}
Header Authentication header (x-o-api-key)
Content type application/json
URL params (Required) ID of the batch
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "batchId": "<string>",
  "status": "PROCESSING|CANCELLED|PROCESSING_FINISHED",
  "progressPercentage": integer,
  "details": {
    "rowsWithInvalidSegments": integer,
    "invalidSegments": [
      "<segmentationKey=segmentKey>",
      "<segmentationKey=segmentKey>"
    ]
  },
  "link": "/v1/audience/batch/{id}"
}

invalidSegments is an array of invalid segmentationKey=segmentKey value pairs, and these are listed only if the value of rowsWithInvalidSegments is larger than zero.

Example: No invalid segments

Request header

GET /v1/audience/batch/7c4b6bb1-5c7a-4f55-83ab-7eb7ba1001f0 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response

HTTP status:
  200 (OK)

Body:
{
  "batchId": "7c4b6bb1-5c7a-4f55-83ab-7eb7ba1001f0",
  "status": "PROCESSING_FINISHED",
  "progressPercentage": 100,
  "details": {
    "rowsWithInvalidSegments": 0
  },
  "link": "/v1/audience/batch/7c4b6bb1-5c7a-4f55-83ab-7eb7ba1001f0"
}

Example: Invalid segments

Request header

GET /v1/audience/batch/94c5c9ec-9429-4838-ba78-0d50d24e1f00 HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response

HTTP status:
  200 (OK)

Body:
{
  "batchId": "94c5c9ec-9429-4838-ba78-0d50d24e1f00",
  "status": "PROCESSING_FINISHED",
  "progressPercentage": 100,
  "details": {
    "rowsWithInvalidSegments": 5,
    "invalidSegments": [
      "1=a",
      "2=a",
      "1=b",
      "2=b",
      "3=a",
      "3=b",
      "3=c",
      "4=b",
      "4=c",
      "4=d"
    ]
  },
  "link": "/v1/audience/batch/94c5c9ec-9429-4838-ba78-0d50d24e1f00"
}

Cancel batch upload

This endpoint allows you to cancel an audience data batch file upload. You can only cancel batches that are in status UPLOADED or PROCESSING, meaning their progressPercentage is less than 100.

If you try to cancel a batch that has already been a 100% processed, Pulse returns 400 Bad Request with the following response body:

{
  "errors": [
    {
      "message": "Unable to cancel batch: 94c5c9ec-9429-4838-ba78-0d50d24e1f00, already 100% processed"
    }
  ]
}
Method POST
URL You must prefix the URL with your region, either eu for European customers or asia for Asian customers.
  • Europe: https://eu.api.videoplaza.com/v1/audience/batch/{id}/cancel
  • Asia: https://asia.api.videoplaza.com/v1/audience/batch/{id}/cancel
Header Authentication header (x-o-api-key)
Content type application/json
URL params (Required) ID of the batch
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "batchId": "<string>",
  "status": "CANCELLED",
  "progressPercentage": integer,
  "details": {
    "rowsWithInvalidSegments": integer,
    "invalidSegments": [
      "<segmentationKey=segmentKey>",
      "<segmentationKey=segmentKey>"
    ]
  },
  "link": "/v1/audience/batch/{id}"
}

invalidSegments is an array of invalid segmentationKey=segmentKey value pairs, and these are listed only if the value of rowsWithInvalidSegments is larger than zero.

Example

Request header

POST /v1/audience/batch/8978549c-d433-4786-be1f-464cca582908/cancel HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response

HTTP status:
  200 (OK)

Body:
{
  "batchId": "8978549c-d433-4786-be1f-464cca582908",
  "status": "CANCELLED",
  "progressPercentage": 10,
  "details": {
    "rowsWithInvalidSegments": 0,
  },
  "link": "/v1/audience/batch/8978549c-d433-4786-be1f-464cca582908"
}