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.

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 ID of the audience provider, required.
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.
  • ID of the audience provider
  • ID of the audience segmentation
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 ID of the audience provider, required.
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.
  • ID of the audience provider
  • ID of the audience segmentation
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
        }
    ]
}