Audience segment requests

Audience segments represent specific segments in the audience segmentation, for example 10-14 or 55-64 can be segments of the Age segmentation. You can have a maximum of 15 segments per segmentation. Segments cannot be deleted.

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.

The audience segment requests allow you to retrieve segment information, as well as create new and update existing segments for a segmentation.

Create a segment for a segmentation

Method POST
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation/{segmentationId}/segment
Header Authentication header (x-o-api-key)
Content type application/json
URL params All parameters are required.
Query params -
Body All parameters are required. See Data integration structure for parameter details.
{
  "segmentKey": "<string>",   
  "segmentName": "<string>"
}
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "segmentKey": "<string>",
  "segmentName": "<string>",
  "segmentId": "<integer>"
}

segmentId is a Pulse assigned ID and cannot be modified.

Example

Request header

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

Request body

{
  "segmentKey": "456",
  "segmentName": "Car Owners"
}

Success response

HTTP status:
  200 (OK)

Body:
{
   "segmentKey": "456",
   "segmentName": "Car Owners",
   "segmentId": 2
}

Update a segment for a segmentation

Method PUT
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation/{segmentationId}/segment/{segmentId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params All parameters are required.
Query params -
Body All parameters are required. See Data integration structure for parameter details.
{
  "segmentKey": "<string>",   
  "segmentName": "<string>"
}
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "segmentKey": "<string>",
  "segmentName": "<string>",
  "segmentId": "<integer>"
}

segmentId is a Pulse assigned ID and cannot be modified.

Example

Request header

PUT v1/audience/provider/8978549c-d433-4786-be1f-464cca582908/segmentation/2/segment/2 HTTP/1.1
Host: api.videoplaza.com
Content-­type: application/json
x-o-api-key="<your key>"

Request body

{
  "segmentKey": "456",
  "segmentName": "Car Enthusiasts"
}

Success response

HTTP status:
  200 (OK)

Body:
{
   "segmentKey": "456",
   "segmentName": "Car Enthusiasts",
   "segmentId": 2
}

List segments for a segmentation

Method GET
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation/{segmentationId}/segment
Header Authentication header (x-o-api-key)
Content type application/json
URL params All parameters are required.
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: paginated list of segments

{
  "pagination": {
      "totalCount": "<integer>",
      "pageSize": "<integer>",
      "pageNumber": "<integer>",
      "links": {
          "first": "<string>",
          "next": "<string>",
          "previous": "<string>",
          "last": "<string>"
  },
  "segments": [
    {
      "segmentKey": "<string>",
      "segmentName": "<string>",
      "segmentId": "<integer>"
    },
    {
      "segmentKey": "<string>",
      "segmentName": "<string>",
      "segmentId": "<integer>"
    }
  ]
}

segmentId is a Pulse assigned ID and cannot be modified.

Example

Request header

GET v1/audience/provider/8978549c-d433-4786-be1f-464cca582908/segmentation/2/segment 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:
{
    "pagination": {
        "totalCount": 2,
        "pageSize": 100,
        "pageNumber": 1
    },
    "segments": [
        {
            "segmentKey": "123",
            "segmentName": "Pet Owners",
            "segmentId": 1
        },
        {
            "segmentKey": "456",
            "segmentName": "Car Enthusiasts",
            "segmentId": 2
        }
    ]
}

Get specified segment for a segmentation

Method GET
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation/{segmentationId}/segment/{segmentId}
Header Authentication header (x-o-api-key)
Content type application/json
URL params All parameters are required.
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "segmentKey": "<string>",
  "segmentName": "<string>",
  "segmentId": "<integer>"
}

segmentId is a Pulse assigned ID and cannot be modified.

Example

Request header

GET v1/audience/provider/8978549c-d433-4786-be1f-464cca582908/segmentation/2/segment/1 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:
{
   "segmentKey": "123",
   "segmentName": "Pet Owners",
   "segmentId": 1
}