Advertiser API (UAS)

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

Description

The Advertiser API enables you to create, update and retrieve advertiser details. Advertiser records can be retrieved using dimensions, filters and sorting options. 

For more information about UAS Buyer Management Services, refer to Buyer Management Services (UAS)

Supported Operations

Service Name: /advertisers/

                                             

Method PathHTTP Method TypeDescriptionLink to Definition
/advertisers/POSTCreates an Advertiser in the system.Create an Advertiser
/advertisers/{id}GETRetrieves the details of a specific Advertiser for the requested Agency ID.Retrieve the Details of an Advertiser
/agencies/GET

Retrieves the list of Advertiser associated with your account.

Using this API, you can apply dimensions, filter criteria and sorting option to retrieve a list of records.

Retrieve a List of Advertisers
/advertisers/{id}PUT

This API method updates a single Advertiser. (This will be Transactional.)

  • This method will perform a full update. If the request does not contain a value for an attribute, it will either be set to NULL/default value. However, if the parameter is mandatory, the ad unit will not be updated.
  • Ensure that you are passing all the required attributes with the required values.
  • Once advertiser is moved to archive status, it cannot be updated.
Update an Advertiser
/advertisers/{id}PATCH

This API method performs a patch of an Advertiser (e.g., to change only the status of an Advertiser).

NOTE : It is different than PUT. In PUT full replacement of the Object takes place.

Update (Patch) an Advertiser
/advertisers/{id}DELETEThis API method deletes (archives) an Advertiser.Delete an Advertiser
 

 

Create an Advertiser

Overview

This API enables the creation of an Advertiser.  

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 NameTypeRequiredValidationsDescriptions
idNumericYes

Must be unique, non-zero and non-negative.

Mandatory for GET, PUT, PATCH & DELETE
nameStringYes

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

Name should be unique for Advertiser.

Advertiser Name
advertiserTypeNumericYesShould be valid and exist in the system.

Currently we support the following Advertiser Types:

  • Guaranteed
  • SSP
logoStringNo Advertiser Logo
accountNumericYesShould be valid and exist in the system.Advertiser Account Id
statusNumericYes

Should be valid and exist in the system.

It is expected to be in the request for the creation of an advertiser.

The advertiser is always created in default active status. If other status is provided during active,it is ignored.

'Archive' is the final status. It cannot be changed to another status once archived.

Advertiser Status.

(Retrieve a list of statuses using the Status API.)

The following are supported statuses for an Advertiser:

1=Active

2=Inactive

3= Archived

agenciesArray of Advertiser Agencies ObjectNo

Optional.

If passed Agency should be valid and exists.
The passed Agency to be associated should be not be in archived status.

If the associated agency is updated to archive status after associating with advertiser, it should not be validated during update of other entities.

Agency for the Advertiser.

You can create/edit/retrieve a list of Agencies using the Agency API

contactsList of Contact ObjectsYes
  • Should be valid and exist in the system.
  • The passed Contact to be associated should not be in archived status while creating/updating advertiser with archived Contact.
  • If the Contact is updated to archive status after associating with an advertiser, it should not be validated during the update operation.
Advertiser Contacts. You can create a new contact/retrieve a list using Contact API (UAS) 
iabCategoriesList of IAM Category ObjectsYes

There should be exactly one Primary IAB Category and at most 3 Secondary IAB categories associated with an Ad Unit.

IAB Category of the Advertiser. You can retrieve a list of IAB categories using the IAB Category API.

EXAMPLE:

    

"iabCategories": [{
       "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }]
labelsList of Label ObjectsNoShould be valid and exist in the system.

Labels applied on an Ad Unit.

You can create/edit/retrieve a list of Label details using the Label Exclusion API (UAS) .

Note: If you want to remove associated labels, you will need to pass an empty array (i.e, [  ])

 

Sample Request URL

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

 

Sample Request JSON

    


{
    "account": {
        "id": 118385
    },
    "name": "Advertiser-1",
    "logo": "logo url",
    "status": {
        "id": 1
    },
    "advertiserType": {
        "id": 4
    },
    "contacts": [{
        "id": 1
    }, {
        "id": 2
    }],
    "iabCategories": [{
        "id": 1
    }, {
        "id": 2
    }, {
        "id": 3
    }],
    "labels": [{
        "id": 1
    }]
}

Response

Sample Response JSON

    

{
    "id": 66,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "Advertiser-1",
    "logo": "logo url",
    "status": {
        "id": 1,
        "name": "active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "advertiserType": {
        "id": 4,
        "name": "Guaranteed"
    },
    "contacts": [{
        "id": 1
    }, {
        "id": 2
    }],
    "iabCategories": [{
            "id": 1
        }, {
            "id": 2
        }, {
            "id": 3
        },
        "labels": [{
            "id": 1,
            "name": "CarAccident",
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": false
        }]
    }
    "id": 1,
    "account": {
        "id": 118385,
        "url": "
    },
    "name": "41Media",
    "logo": "logo url",
    "agencyType": {
        "id": 3,
        "name": "Advertising Agency",
        "url": "
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "
    },
    "contacts": [{
        "id": 1
    }],
    "advertisers": [{
        "id": 1
    }, {
        "id": 2
    }]
}
 

 

Retrieve the Details of an Advertiser

Overview

This API enables you to retrieve the details of an Advertiser.  

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/advertisers/66 

Response

Sample Response JSON

    

{
    "id": 66,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "Advertiser-Test1",
    "logo": "logo url",
    "status": {
        "id": 1,
        "name": "active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "advertiserType": {
        "id": 4,
        "name": "Guaranteed"
    },
    "contacts": [{
        "id": 1
    }, {
        "id": 2
    }],
    "iabCategories": [{
        "id": 1
    }, {
        "id": 2
    }, {
        "id": 3
    }],
    "labels": [{
        "id": 1,
        "name": "CarAccident",
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }, {
        "id": 2,
        "name": "FlightCrash",
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }]
}

 

Retrieve a List of Advertisers

Overview

This API enables you to retrieve a list of an Advertisers.  

In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Ad Units with a specific set of details according to your requirements.

 

Refer to Common Request Query Parameters for more information about using dimensions, filters and sorting, 

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/advertisers/ 

 

Response

Sample Response JSON

    

Retrieves a list of all the advertisers associate with this account.

Generic Search

           

Sample Request URL

https://api.pubmatic.com/v1/uas/advertisers?dimensions=id,name,status&sort=id&filters=id eq 10000001

Sample Response

    

Retrieves advertisers that match the filter criteria.

Update an Advertiser

Overview

This API enables you to update an Advertiser.  

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 NameTypeRequiredValidationsDescriptions
idNumericYes

Must be unique, non-zero and non-negative.

Mandatory for GET, PUT, PATCH & DELETE
nameStringYes

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

Name should be unique for Advertiser.

Advertiser Name
advertiserTypeNumericYesShould be valid and exist in the system.

Currently we support the following Advertiser Types:

  • Guaranteed
  • SSP
logoStringNo Advertiser Logo
accountNumericYesShould be valid and exist in the system.Advertiser Account Id
statusNumericYes

Should be valid and exist in the system.

It is expected to be in the request for the creation of an advertiser.

The advertiser is always created in default active status. If other status is provided during active,it is ignored.

Archive is the last status. It cannot be changed once in archived state.

Advertiser Status.

(Retrieve a list of statuses using the Status API.)

The following are supported statuses for an Advertiser:

1=Active

2=Inactive

3= Archived

agenciesArray of Advertiser Agencies ObjectNo

Optional.

If passed Agency should be valid and exists.
The passed Agency to be associated should be not be in archived status.

If the associated agency is updated to archive status after associating with advertiser, it should not be validated during update of other entities.

Agency for the Advertiser.

You can create/edit/retrieve a list of Agencies using the Agency API

contactsList of Contact ObjectsYes
  • Should be valid and exist in the system.
  • The passed Contact to be associated should not be in archived status while creating/updating advertiser with archived Contact.
  • If the Contact is updated to archive status after associating with an advertiser, it should not be validated during the update operation.
Advertiser Contacts. You can create a new contact/retrieve a list using Contact API
iabCategoriesList of IAM Category ObjectsYes

There should be exactly one Primary IAB Category and at most 3 Secondary IAB categories associated with an Ad Unit.

IAB Category of the Advertiser. You can retrieve a list of IAB categories using the IAB Category API.

EXAMPLE:

    

"iabCategories": [{
       "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }]
labelsList of Label ObjectsNoShould be valid and exist in the system.

Labels applied on an Ad Unit.

You can create/edit/retrieve a list of Label details using the Label Exclusion API.

Note: If you want to remove associated labels, you will need to pass an empty array (i.e, [  ])

 

Sample Request URL

https://api.pubmatic.com/v1/uas/advertisers/66

Sample Request JSON

    

{
    "id": 66,
    "account": {
        "id": 118385
    },
    "name": "Advertiser-Test1",
    "logo": "logo url",
    "status": {
        "id": 1
    },
    "advertiserType": {
        "id": 4
    },
    "account": {
        "id": 1
    },
    "contacts": [{
        "id": 1
    }, {
        "id": 2
    }],
    "iabCategories": [{
        "id": 1
    }, {
        "id": 2
    }, {
        "id": 3
    }],
    "labels": [{
        "id": 1
    }, {
        "id": 2
    }]
}

Response

Sample Response JSON

    

{
    "id": 66,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "Advertiser-Test1",
    "logo": "logo url",
    "status": {
        "id": 1,
        "name": "active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "advertiserType": {
        "id": 4,
        "name": "Guaranteed"
    },
    "contacts": [{
        "id": 1
    }, {
        "id": 2
    }],
    "iabCategories": [{
        "id": 1
    }, {
        "id": 2
    }, {
        "id": 3
    }],
    "labels": [{
        "id": 1,
        "name": "CarAccident",
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }, {
        "id": 2,
        "name": "FlightCrash",
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }]
}
 

 

Update (Patch) an Advertiser

Overview

This API enables you to (patch) update an Advertiser.  

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 NameTypeRequiredValidationsDescriptions
idNumericYes

Must be unique, non-zero and non-negative.

Mandatory for GET, PUT, PATCH & DELETE
nameStringYes

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

Name should be unique for Advertiser.

Advertiser Name
advertiserTypeNumericYesShould be valid and exist in the system.

Currently we support the following Advertiser Types:

  • Guaranteed
  • SSP
logoStringNo Advertiser Logo
accountNumericYesShould be valid and exist in the system.Advertiser Account Id
statusNumericYes

Should be valid and exist in the system.

It is expected to be in request for creation of advertiser.

The advertiser is always created in default active status. If other status is provided during active,it is ignored.

It is expected to be in the request for the creation of an advertiser.

Advertiser Status.

(Retrieve a list of statuses using the Status API.)

The following are supported statuses for an Advertiser:

1=Active

2=Inactive

3= Archived

agenciesArray of Advertiser Agencies ObjectNo

Optional.

If passed Agency should be valid and exists.
The passed Agency to be associated should be not be in archived status.

If the associated agency is updated to archive status after associating with advertiser, it should not be validated during update of other entities.

Agency for the Advertiser.

You can create/edit/retrieve a list of Agencies using the Agency API

contactsList of Contact ObjectsYes
  • Should be valid and exist in the system.
  • The passed Contact to be associated should not be in archived status while creating/updating advertiser with archived Contact.
  • If the Contact is updated to archive status after associating with an advertiser, it should not be validated during the update operation.
Advertiser Contacts. You can create a new contact/retrieve a list using Contact API
iabCategoriesList of IAM Category ObjectsYes

There should be exactly one Primary IAB Category and at most 3 Secondary IAB categories associated with an Ad Unit.

IAB Category of the Advertiser. You can retrieve a list of IAB categories using the IAB Category API.

EXAMPLE:

    

"iabCategories": [{
       "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }]
labelsList of Label ObjectsNoShould be valid and exist in the system.

Labels applied on an Ad Unit.

You can create/edit/retrieve a list of Label details using the Label Exclusion API.

Note: If you want to remove associated labels, you will need to pass an empty array (i.e, [  ])

 

Sample Request URL

https://api.pubmatic.com/v1/uas/advertisers/66 

Sample Request JSON

    

{
    "name": "Advertiser-Test Name"
}

Response

Sample Response JSON

    

{
    "id": 66,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "Advertiser-Test Name",
    "logo": "logo url",
    "status": {
        "id": 1,
        "name": "active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "contacts": [{
        "id": 1
    }, {
        "id": 2
    }],
    "iabCategories": [{
        "id": 1
    }, {
        "id": 2
    }, {
        "id": 3
    }],
    "labels": [{
        "id": 1,
        "name": "CarAccident",
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }, {
        "id": 2,
        "name": "FlightCrash",
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion",
            "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
        },
        "isInherited": false
    }]
}
 

 

Delete an Advertiser

Overview

This API enables you to delete (archive) an Advertiser.  

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://$URI_PREFIX/{apiVersion}/phoenix/advertisers/66

Response

Sample Response 

    

Returns 'true' if archival is successful; 'false' if unsuccessful.

 

Error Codes for Advertiser API

                                      

Sr. NoError CodesDescription
1.PH_MISSING_OR_INVALID_PARAMETER

Can occur when mandatory parameter is missing or invalid in the request.

Can occur in the following parameters:

  • Account Id
  • Name
  • Label
  • IAB category
  • Contacts
2.PH_DUPLICATE_ENTRIES_FOUNDWill occur if the system finds duplicate information in the Agency Request for the Name or Contact parameter.
3.PH_PARAMETER_VALUE_TOO_LARGE

Occurs when a parameter contains a value exceeding its allowable limit.

It can occur in the following parameters:

  • Advertiser Id
  • Name
4.PH_UNSUPPORTED_VALUEOccurs when status value is not supported for the agency.
 
5.PH_ATTEMPT_TO_UPDATE_SEALED_VALUE Will occur if an attempt is made to update a sealed value in the system. This can occur for the Account parameter.
6.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED_STATUS_ENTITYThe error message occurs if the agency to be associated is in archive status.

 

 

 

Version 39

Attachments

    Outcomes