Audience segmentation requests

Audience segmentation is a grouping of related segments, for example Age, Gender, or Interests. You can have a maximum of 200 segmentations per DMP integration. Audience segmentations cannot be deleted through the API. Contact Technical Support if you reach the limit and need to have a segmentation 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 segmentation requests allow you to retrieve segmentation information for an audience provider, as well as create new and update existing segmentations.

Create a segmentation for a provider

When creating a new audience segmentation for a provider, at least one audience segment must be provided.

Method POST
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation
Header Authentication header (x-o-api-key)
Content type application/json
URL params (Required) ID of the audience provider, which can be retrieved using List audience providers
Query params -
Body

All parameters are required. When creating a segmentation, at least one segment must be provided. See Data integration structure for parameter details.

{
  "segmentationKey": "<string>",    
  "segmentationName": "<string>",    
  "segments": [    
    {
      "segmentKey": "<string>",    
      "segmentName": "<string>"    
    }
  ]
}
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "segmentationKey": "<string>",
  "segmentationName": "<string>",
  "segmentationId": "<integer>",    
  "segments": [
    {
      "segmentKey": "<string>",
      "segmentName": "<string>",
      "segmentId": "<integer>"  
    }
  ]
}

segmentationId and segmentId are Pulse assigned IDs and cannot be modified.

Example

Request header

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

Request body

{
  "segmentationKey": "xyz",
  "segmentationName": "Interests",
  "segments": [
    {
      "segmentKey": "123",
      "segmentName": "Pet Owners"
    }
  ]
}

Success response

HTTP status:
  200 (OK)

Body:
{
    "segmentationKey": "xyz",
    "segmentationName": "Interests",
    "segmentationId": 2,
    "segments": [
        {
            "segmentKey": "123",
            "segmentName": "Pet Owners",
            "segmentId": 1
        }
    ]
}

Update a segmentation for a provider

Method PUT
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation/{segmentationId}
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.

{
  "segmentationKey": "<string>",
  "segmentationName": "<string>"
}
Success response

HTTP status: 200 OK

Header: -

Body:

{
  "segmentationKey": "<string>",
  "segmentationName": "<string>",
  "segmentationId": "<integer>",   
  "segments": [
    {
      "segmentKey": "<string>",
      "segmentName": "<string>",
      "segmentId": "<integer>"   
    }
  ]
}

segmentationId and segmentId are Pulse assigned IDs and cannot be modified.

Example

Request header

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

Request body

{
  "segmentationKey": "abc",
  "segmentationName": "Interests"
}

Success response

HTTP status:
  200 (OK)

Body:
{
    "segmentationKey": "abc",
    "segmentationName": "Interests",
    "segmentationId": 2,
    "segments": [
        {
            "segmentKey": "123",
            "segmentName": "Pet Owners",
            "segmentId": 1
        }
    ]
}

List segmentations for a provider

Method GET
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation
Header Authentication header (x-o-api-key)
Content type application/json
URL params (Required) ID of the audience provider, which can be retrieved using List audience providers
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: paginated list of segmentations

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

segmentationId and segmentId are Pulse assigned IDs and cannot be modified.

Example

Request header

GET /v1/audience/provider/8978549c-d433-4786-be1f-464cca582908/segmentation 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": 3,
        "pageSize": 100,
        "pageNumber": 1
    },
    "segmentations": [
        {
            "segmentationKey": "kv1001",
            "segmentationName": "Gender",
            "segmentationId": 0,
            "segments": [
                {
                    "segmentKey": "b",
                    "segmentName": "Female",
                    "segmentId": 2
                },
                {
                    "segmentKey": "a",
                    "segmentName": "Male",
                    "segmentId": 1
                }
            ]
        },
        {
            "segmentationKey": "kv1002",
            "segmentationName": "Age",
            "segmentationId": 1,
            "segments": [
                {
                    "segmentKey": "a",
                    "segmentName": "0-16",
                    "segmentId": 1
                },
                {
                    "segmentKey": "b",
                    "segmentName": "16-21",
                    "segmentId": 2
                },
                {
                    "segmentKey": "c",
                    "segmentName": "21-29",
                    "segmentId": 3
                },
                {
                    "segmentKey": "d",
                    "segmentName": "30-39",
                    "segmentId": 4
                },
                {
                    "segmentKey": "e",
                    "segmentName": "40-49",
                    "segmentId": 5
                },
                {
                    "segmentKey": "f",
                    "segmentName": "50-59",
                    "segmentId": 6
                },
                {
                    "segmentKey": "g",
                    "segmentName": "60-99",
                    "segmentId": 7
                }
            ]
        },
        {
            "segmentationKey": "abc",
            "segmentationName": "Interests",
            "segmentationId": 2,
            "segments": [
                {
                    "segmentKey": "123",
                    "segmentName": "Pet Owners",
                    "segmentId": 1
                }
            ]
        }   
    ]
}

Get specified segmentation for a provider

Method GET
URL https://api.videoplaza.com/v1/audience/provider/{providerId}/segmentation/{segmentationId}
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: segmentation object

{
    "segmentationKey": "<string>",
    "segmentationName": "<string>",
    "segmentationId": "<integer>",
    "segments": [
        {
            "segmentKey": "<string>",
            "segmentName": "<string>",
            "segmentId": "<integer>"
        },
        {
            "segmentKey": "<string>",
            "segmentName": "<string>",
            "segmentId": "<integer>"
        }
    ]
}

segmentationId and segmentId are Pulse assigned IDs and cannot be modified.

Example

Request header

GET /v1/audience/provider/8978549c-d433-4786-be1f-464cca582908/segmentation/0 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:
{
    "segmentationKey": "kv1001",
    "segmentationName": "Gender",
    "segmentationId": 0,
    "segments": [
        {
            "segmentKey": "b",
            "segmentName": "Female",
            "segmentId": 2
        },
        {
            "segmentKey": "a",
            "segmentName": "Male",
            "segmentId": 1
        }
    ]
}