Agency API (UAS)

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

Description

The Agency API enables you to create, update and retrieve agency details. Agency 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: /agencies/

                                             

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

Retrieves the list of Agencies 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 Agencies
/agencies/{id}PUT

This API method updates a single Agency. (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.
  • Archive is the last status. It cannot be changed once in archived state.
Update an Agency
/agencies/{id}PATCH

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

NOTE : This is different than PUT. In PUT full replacement of the Object takes place.
Update (Patch) an Agency
/agencies/{id}DELETEThis API method deletes (archives) an AgencyDelete an Agency

 

Create an Agency

Overview

This API enables the creation of an Agency.  

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 and update.

Id is system-generated while the Agency is created in the system.
nameStringYes

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

Name should be unique for Agency.

Agency Name
agencyTypeNumericYesShould be valid and exist in the system.Agency Type (Retrieve a list of Agency Types using the Agency Type API)
logoStringYes Agency Logo
accountNumericYesShould be valid and exist in the system.Account of the Publisher.
statusNumericYes

Should be valid and exist in the system.

Agency is created in the default active status and input of status during creation is ignored.


Archive is final status. Cannot edit any fields or change status once agency is archived.

Agency Status.

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

The following are supported statuses for an Agency:

1=Active

2=Inactive

3= Archived

contactsList of Contacts

Yes

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

Should be valid and exist in the system.

Agency Advertisers

 

Sample Request URL

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

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "name": "41Media",
    "logo": "logo url",
    "agencyType": {
        "id": 3
    },
    "status": {
        "id": 1
    },
    "contacts": [{
        "id": 1
    }],
    "advertisers": [{
        "id": 1
    }, {
        "id": 2
    }]
}

Response

Sample Response JSON

    

{
    "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 Agency

Overview

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

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/agencies/4 

Response

Sample Response JSON

    

{
    "id": 4,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "41MediaFirst",
    "logo": "logo url",
    "agencyType": {
        "id": 3,
        "name": "Advertising Agency",
        "url": "http://api.pubmatic.com/v1/uas/agencytype/3"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "contacts": [{
        "id": 1
    }],
    "advertisers": [{
        "id": 1
    }, {
        "id": 2
    }]
}

 

Retrieve a List of Agencies

 

Overview

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

In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list 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/agencies/ 

Response

Sample Response

    

Retrieves all agencies.

Generic Search

           

Sample Request URL

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

 

Sample Response

    

Retrieves agencies that match the filter criteria.

Update an Agency

Overview

This API enables the update of an Agency.  

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 and update.

Id is system-generated while the Agency is created in the system.
nameStringYes

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

Name should be unique for Agency.

Agency Name
agencyTypeNumericYesShould be valid and exist in the system.Agency Type (Retrieve a list of Agency Types using the Agency Type API)
logoStringYes Agency Logo
accountNumericYesShould be valid and exist in the system.Account of the Publisher.
statusNumericYes

Should be valid and exist in the system.

Agency is created in the default active status and input of status during creation is ignored.

Archive is final status. Cannot edit any fields or change status once agency is archived.

Agency Status.

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

The following are supported statuses for an Agency:

1=Active

2=Inactive

3= Archived

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

Should be valid and exist in the system.

Agency Advertisers

 

Sample Request URL

https://api.pubmatic.com/v1/uas/agencies/4 

Sample Request JSON

    

{
    "id": 1,
    "account": {
        "id": 118385
    },
    "name": "41Media2015",
    "logo": "logo url",
    "agencyType": {
        "id": 3,
        "name": "Advertising Agency",
        "url": "http://api.pubmatic.com/v1/uas/agencytype/3"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "contacts": [{
        "id": 1
    }],
    "advertisers": [{
        "id": 1
    }, {
        "id": 2
    }]
}

Response

Sample Response JSON

    

{
    "id": 1,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "41Media2015",
    "agencyType": {
        "id": 3,
        "name": "Advertising Agency",
        "url": "http://api.pubmatic.com/v1/uas/agencytype/3"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "contacts": [{
        "id": 1
    }],
    "advertisers": [{
        "id": 1
    }, {
        "id": 2
    }]
}

 

Update (Patch) an Agency

 

Overview

This API enables the (patch) update of an Agency.  

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 and update.

Id is system-generated while the Agency is created in the system.
nameStringYes

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

Name should be unique for Agency.

Agency Name
agencyTypeNumericYesShould be valid and exist in the system.Agency Type (Retrieve a list of Agency Types using the Agency Type API)
logoStringYes Agency Logo
accountNumericYesShould be valid and exist in the system.Account of the Publisher.
statusNumericYes

Should be valid and exist in the system.

Agency is created in the default active status and input of status during creation is ignored.

Archive is final status. Cannot edit any fields or change status once agency is archived.

Agency Status.

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

The following are supported statuses for an Agency:

1=Active

2=Inactive

3= Archived

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

Should be valid and exist in the system.

Agency Advertisers

 

Sample Request URL

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

Sample Request JSON

    

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

Response

Sample Response JSON

    

{
    "id": 4,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/accounts/1"
    },
    "name": "Agency-Test Name",
    "logo": "logo url",
    "agencyType": {
        "id": 3,
        "name": "Advertising Agency",
        "url": "http://api.pubmatic.com/v1/uas/agencytype/3"
    },
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "contacts": [{
        "id": 1
    }],
    "advertisers": [{
        "id": 1
    }, {
        "id": 2
    }]
}
 

 

Delete an Agency

 

Overview

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

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/agencies/2 

Response

Sample Response

    

Returns 'true' if the archive is successful; 'false' if unsuccessful.

 

Error Codes for Agency

                                 

Sr. NoError CodesDescription
1.MISSING_OR_INVALID_PARAMETER

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

Can occur in the following parameters:

  • Agency Id
  • Account Id
  • Name
  • Status
  • Agency Type
2.DUPLICATE_ENTRIES_FOUNDWill occur if the system finds duplicate information in the Agency Request for the Name 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:

  • Agency Id
  • Name
  • Description
  • Status
  • Account
4.PH_UNSUPPORTED_STATUSOccurs when status value is not supported for the agency.
5.PH_ATTEMPT_TO_ASSOCIATE_WITH_UNSUPPORTED_STATUS_ENTITYThe error message occurs if the agency to be associated is in archive status.

 

 

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 30

Attachments

    Outcomes