Label Exclusion API (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 29, 2017
Version 11Show Document
  • View in full screen mode

Description

The Label Exclusion API supports Label Management operations, including creating, updating and listing labels. When a label exclusion is used, it instructs the server not to display ads from a listed exclusion, which can be a Competitive Exclusion or an Ad Exclusion. When the exclusion order is in effect, the excluded ads are not displayed.  Once a label is created it can be applied to Advertiser, Order, Linked Item and Ad Unit.

The Unified Ad Server offers two types of labels:

  • Competitive Exclusion 
    Use Competitive Exclusion labels to restrict your ads from being displayed if a competitor’s advertisement has already been loaded on the page. By default, the selected exclusions apply to all of the line items in the order.
  • Ad Exclusion 
    Use Ad Exclusion labels to ensure that your line items are not served to undesirable or inappropriate websites or web pages. By default, Labels are applied to all line items in the order.

For more information about UAS Account & Admin Services APIs, refer to Account & Admin Services (UAS) 

Supported Operations

Service Name: /labels/

                                       

Method PathHTTP Method TypeDescriptionLink to Definition
/labels/POSTCreates a Label in the system.Create a Label
/labels/{id}GETRetrieves the details of a specific Label for requested label ID.Retrieve Details of a Specific Label
/labels/GET

Retrieves the list of Labels associated with your account. 

With this, you can apply supported dimensions by Labels, filters and sorting option to fetch list of Labels with specific set of details according to your requirements.

Retrieve a List of Labels
/labels {id}PUT

This API method updates a single Label.

  • This method will do a full update, which means it will update all fields that are passed. If a field is optional, the default value is set. However, if a field is mandatory and it is not one that is passed, an error message will display.
Update a Label
/labels/{id}PATCH

This API method performs a partial update on an object. This enables you to make an update to a specific field on the Label. For example, to update only the name or update a status. This request should only include those fields that need to be updated.

 

Note: This API is different than a PUT, which does a full replacement of the object takes place.

Update (Patch) a Label

 

Create a Label

 

Overview

This API enable you to create a label in the Unified Ad Server.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                  

Parameter NameTypeRequiredValidationsDescription
nameStringYes

Can be a maximum of 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks, and colons.

Should be unique for your account. (Different accounts can have the same Label Name, but an account cannot contain duplicate label names.)

The name of the label
accountNumericYesThere must be a corresponding account to which the Label belongs.Account of the label.
labelTypeNumericYesThe ID must exist in the system

This determines the type of the label. Retrieve label types using the Label Type API.

1 = Ad Exclusion

2 = Competitive Exclusion

statusNumericYes

Status should be valid and exist in the system. Status is an expected field in the label creation request. If it is not passed, the default status will be "Inactive."

Only "Active" and "Inactive" values are allowed.

Label can be one of the following statuses:

1 = Active

2 = Inactive

descriptionStringNo

Description is optional and can be a maximum of 1024 characters. If more than 1024 characters are passed, the remainder of the content is discarded silently.

Description is optional.
userNumeric YesMust be valid and exist in the system.Create/Edit/Retrieve List of Operational User details using the User API.
isinheritedBooleanNo

Optional 

This flag is used to indicate the label inheritance:

               
IsinheritedDescription
TrueThe label is inherited from above entities in the hierarchy.
FalseThe label is explicitly mapped to this entity.

NOTE: This field is used when the label is associated with any entity.

excludedIntegerNoIf specified, it must be a valid Integer (e.g., "1")

This field is used to exclude the label, which is inherited in the hierarchy.

               
excludedDescription
nullIf excluded is null, it means that the label has to be included in the hierarchy.
Any integerIf excluded has any Integer value (e.g., "1"), it means that this label must be excluded from the hierarchy.

NOTE: This field is used when the label is associated with any entity, such as Ad Unit, Order, Line Item and Advertiser. 

Sample Request URL

https://api.pubmatic.com/v1/uas/labels/ 

Sample Request JSON

    

{
    "name": "Label-1",
    "account": {
        "id": 118385
    },
    "labelType": {
        "id": 2
    },
    "status": {
        "id": 1
    },
    "description": "Test Label - 1",
    "user": {
        "id": 13700
    }
}

Response

Sample Response JSON

    

{
    "id": 1,
    "name": "Label-1",
    "account": {
        "id": 118385,
        "url": "https://api.pubmatic.com/v1/uas/"
    },
    "labelType": {
        "id": 2,
        "name": "Competitive Exclusion",
        "url": "https://api.pubmatic.com/v1/uas/labeltype/2"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "https://api.pubmatic.com/v1/uas/status/1"
    },
    "description": "Test Label - 1",
    "user": {
        "id": 13700,
        "url": "https://api.pubmatic.com/v1/uas/users/13700"
    }
}

Retrieve Details of a Specific Label

 

Overview

This API enables you to retrieve a specific label in the Unified Ad Server. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Labels with a specific set of details according to your requirements.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/labels/1 

Response

Sample Response JSON

{
    "id": 1,
    "name": "Label-1",
    "account": {
        "id": 118385,
        "url": "https://api.pubmatic.com/v1/uas/"
    },
    "labelType": {
        "id": 2,
        "name": "Competitive Exclusion",
        "url": "https://api.pubmatic.com/v1/uas/labeltype/2"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "https://api.pubmatic.com/v1/uas/status/1"
    },
    "description": "Test Description Label - 1",
    "user": {
        "id": 13700,
        "url": "https://api.pubmatic.com/v1/uas/users/13700"
    }
}

 

Retrieve a List of Labels

 

Overview

This API enables you to retrieve a list of labels in the Unified Ad Server. In the query, you can also apply supported dimensions, filters and sorting options to retrieve specific results.

Refer to Common Request Query Parameters to learn more about using dimensions, sort and filter options.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/labels 

Response

Sample Response 

    

This will return a list of all Labels associated with your account.

Sample URL for Generic Search

https://api.pubmatic.com/v1/uas//labels/?dimensions=name,status,labelType&filters= id eq 10

Sample Response for Generic Search

    

This will return all details associated with Label 10 in your account.

Update a Label

 

Overview

This API enables you to do a full update on a Label. This API completes a full replacement of the Label.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                  

Parameter NameTypeRequiredValidationsDescription
nameStringYes

Can be a maximum of 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks, and colons.

Should be unique for your account. (Different accounts can have the same Label Name, but an account cannot contain duplicate label names.

The name of the label
accountNumericYesThere must be a corresponding account to which the Label belongs.Account of the label.
labelTypeNumericYesThe ID must exist in the system

This determines the type of the label. Retrieve label types using the Label Type API.

1 = Ad Exclusion

2 = Competitive Exclusion

statusNumericYes

Status should be valid and exist in the system. Status is an expected field in the label creation request. If it is not passed, the default status will be "Inactive."

Only "Active" and "Inactive" values are allowed.

Label can be one of the following statuses:

1 = Active

2 = Inactive

descriptionStringNo

Description is optional and can be a maximum of 1024 characters. If more than 1024 characters are passed, the remainder of the content is discarded silently.

Description is optional.
userNumeric YesMust be valid and exist in the system.Create/Edit/Retrieve List of Operational User details using the User API.
isinheritedBooleanNo

Optional 

This flag is used to indicate the label inheritance:

               
IsinheritedDescription
TrueThe label is inherited from above entities in the hierarchy.
FalseThe label is explicitly mapped to this entity.

NOTE: This field is used when the label is associated with any entity.

excludedIntegerNoIf specified, it must be a valid Integer (e.g., "1")

This field is used to exclude the label, which is inherited in the hierarchy.

               
excludedDescription
nullIf excluded is null, it means that the label has to be included in the hierarchy.
Any integerIf excluded has any Integer value (e.g., "1"), it means that this label must be excluded from the hierarchy.

NOTE: This field is used when the label is associated with any entity, such as Ad Unit, Order, Line Item and Advertiser. 

Sample Request URL

https://api.pubmatic.com/v1/uas/labels/1

Sample Request JSON

    

{
    "name": "Label-1",
    "account": {
        "id": 118385
    },
    "labelType": {
        "id": 2
    },
    "status": {
        "id": 1
    },
    "description": "Test Description Label - 1",
    "user": {
        "id": 13700
    }
}

Response

Sample Response JSON

    

{
    "id": 1,
    "name": "Label-1",
    "account": {
        "id": 118385,
        "url": "https://api.pubmatic.com/v1/uas/"
    },
    "labelType": {
        "id": 2,
        "name": "Competitive Exclusion",
        "url": "https://api.pubmatic.com/v1/uas/labeltype/2"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "https://api.pubmatic.com/v1/uas/status/1"
    },
    "description": "Test Description Label - 1",
    "user": {
        "id": 13700,
        "url": "https://api.pubmatic.com/v1/uas/users/13700"
    }
}

Update (Patch) a Label

 

Overview

This API enables you to do a partial update on a Label. This API only updates the fields passed during this operation.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                  

Parameter NameTypeRequiredValidationsDescription
nameStringYes

Can be a maximum of 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks, and colons.

Should be unique for your account. (Different accounts can have the same Label Name, but an account cannot contain duplicate label names.

The name of the label
accountNumericYesThere must be a corresponding account to which the Label belongs.Account of the label.
labelTypeNumericYesThe ID must exist in the system

This determines the type of the label. Retrieve label types using the Label Type API.

1 = Ad Exclusion

2 = Competitive Exclusion

statusNumericYes

Status should be valid and exist in the system. Status is an expected field in the label creation request. If it is not passed, the default status will be "Inactive."

Only "Active" and "Inactive" values are allowed.

Label can be one of the following statuses:

1 = Active

2 = Inactive

descriptionStringNo

Description is optional and can be a maximum of 1024 characters. If more than 1024 characters are passed, the remainder of the content is discarded silently.

Description is optional.
userNumeric YesMust be valid and exist in the system.Create/Edit/Retrieve List of Operational User details using the User API.
isinheritedBooleanNo

Optional 

This flag is used to indicate the label inheritance:

               
IsinheritedDescription
TrueThe label is inherited from above entities in the hierarchy.
FalseThe label is explicitly mapped to this entity.

NOTE: This field is used when the label is associated with any entity.

excludedIntegerNoIf specified, it must be a valid Integer (e.g., "1")

This field is used to exclude the label, which is inherited in the hierarchy.

               
excludedDescription
nullIf excluded is null, it means that the label has to be included in the hierarchy.
Any integerIf excluded has any Integer value (e.g., "1"), it means that this label must be excluded from the hierarchy.

NOTE: This field is used when the label is associated with any entity, such as Ad Unit, Order, Line Item and Advertiser. 

Sample Request URL

https://api.pubmatic.com/v1/uas/labels/1 

Sample Request JSON

    

{
    "name": "Label-1 Patched"
}

Response

Sample Response JSON

    

{
    "id": 1,
    "name": "Label-1 Patched",
    "account": {
        "id": 118385,
        "url": "https://api.pubmatic.com/v1/uas/"
    },
    "labelType": {
        "id": 2,
        "name": "Competitive Exclusion",
        "url": "https://api.pubmatic.com/v1/uas/labeltype/2"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "https://api.pubmatic.com/v1/uas/status/1"
    },
    "description": "Test Description Label - 1",
    "user": {
        "id": 13700,
        "url": "https://api.pubmatic.com/v1/uas/users/13700"
    }
}

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

 

Version 0.1

Attachments

    Outcomes