Account API (UAS)

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

Overview

The Account API enables you to create the Account Object in the Unified Ad Server. Most of the entities in the Unified Ad Server (e.g., Ad Unit, Order, Line Item) are bound to the Account object.

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

Supported Operations

                     

Method PathHTTP Method TypeDescriptionLink to Definition
/accounts/{id}GETRetrieve the account details using account idRetrieve details of an Account
/accounts/GET

Retrieve a list of all accounts in the system for a given user.

You can apply supported dimensions, filters and sorting options to fetch a list of Tracking Events with a specific set of details.

Retrieve a list of Accounts

 

Retrieve the Details of an Account

 

Overview

This API enables you to retrieve the details for a specific Account.

 

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 Name/DimensionsTypeRequiredValidationDescription
id (network id)IntegerYesShould be unique (no duplicates exist)Account Identifier - Shared by PubMatic
name (network name)StringOptional

Convention : Please use the following convention for name.

Account <ID> ( Company Name)

Update is allowed only if Account is Active

  1. Name can be of maximum 64 characters.
  2. Name should be unique.
  3. You can change the name only if account is active.
Name for the Account
statusObjectNo

Default is 'Active'

               
IdName
1Active
2Inactive
Status of an account
frontLoadPercentIntegerNo

Update is allowed only if Account is Active.

frontLoadPercent default = 0% 

Valid range for frontLoadPercent is 0 - 100%`

 
timeZoneObjectRead Only

Reserved by the system.

Not expected while creating and updating the account. If passed, it will be ignored, however, this API will populate this attribute in the GET response.

Time zone is configured for your account while onboarding in PubMatic.

The configured time zone will be used as the default time zone if you have not specified the time zone while creating an Order for the account.

currencyObjectRead Only

Reserved by the system.

Not expected while creating and updating the account. If passed, it will be ignored.

Reporting currency for your account. The same currency will be used when you create the Guaranteed Line Item for your account and for Reporting.
programmaticChannelsObjectRead Only

Reserved by the system.

Not expected while creating and updating the account. If passed, it will be ignored.

As the Universal Ad Server is holistic in nature, it supports both Guaranteed and Programmatic Channels. To supply your inventory to the Programmatic channel, the Universal Ad Server creates the following default Advertiser and Order during Onboarding:

Advertiser with Name "PubMatic SSP Advertiser" : Advertiser under which you can create Programmatic Order. You can not update any attribute of Programmatic Advertiser.

Order with Name "PubMatic Programmatic" - Programmatic Order is created with "PubMatic SSP Advertiser" advertiser.

 

When you would like to compete/open your inventory to Programmatic Channel,
you can create a PMP Deal/Open Exchange Line Item Under "PubMatic Programmatic" and assigned the priority and do the inventory targeting.

Sample Request URL

https://api.pubmatic.com/v1/uas/accounts/118385

Response

Sample Response JSON

    

{
    "id": 118385,
    "name": "Account 118385(My Company)",
    "status": {
        "id": 1,
        "name": "Active",
        "url": "https://api.pubmatic.com/v1/uas/status/1"
    },
    "frontLoadPercent": 14,
    "timeZone": {
        "id": 2,
        "code": "JST",
        "url": "https://api.pubmatic.com/v1/uas/timezones/2"
    },
    "currency": {
        "id": 1,
        "code": "USD",
        "sign": "$"
    },
    "programmaticChannels": [{
        "advertiser": {
            "id": 10000000,
            "name": "PubMatic SSP Advertiser",
            "url": "https://api.pubmatic.com/v1/uas/"
        },
        "order": {
            "id": 10000000,
            "name": "PubMatic Programmatic",
            "url": "https://api.pubmatic.com/v1/uas/"
        }
    }]
}

Response Codes

HTTP Status Codes

 

Retrieve a List of Accounts

 

Overview

Retrieves a list of Accounts that are authorized to the user running the API. 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.

Request Body Parameters

                                                           

Parameter Name/DimensionsTypeRequiredValidationDescription
id (network id)IntegerYesShould be unique (no duplicates exist)Account Identifier - Shared by PubMatic
name (network name)StringOptional

Convention : Please use the following convention for name.

Account <ID> ( Company Name)

Update is allowed only if Account is Active

  1. Name can be of maximum 64 characters.
  2. Name should be unique.
  3. You can change the name only if account is active.
Name for the Account
statusObjectNo

Default is 'Active'

               
IdName
1Active
2Inactive
Status of an account
frontLoadPercentIntegerNo

Update is allowed only if Account is Active.

frontLoadPercent default = 0% 

Valid range for frontLoadPercent is 0 - 100%`

 
timeZoneObjectRead Only

Reserved by the system.

Not expected while creating and updating the account. If passed, it will be ignored, however, this API will populate this attribute in the GET response.

Time zone is configured for your account while onboarding in PubMatic.

The configured time zone will be used as the default time zone if you have not specified the time zone while creating an Order for the account.

currencyObjectRead Only

Reserved by the system.

Not expected while creating and updating the account. If passed, it will be ignored.

Reporting currency for your account. The same currency will be used when you create the Guaranteed Line Item for your account and for Reporting.
programmaticChannelsObjectRead Only

Reserved by the system.

Not expected while creating and updating the account. If passed, it will be ignored.

As the Universal Ad Server is holistic in nature, it supports both Guaranteed and Programmatic Channels. To supply your inventory to the Programmatic channel, the Universal Ad Server creates the following default Advertiser and Order during Onboarding:

Advertiser with Name "PubMatic SSP Advertiser" : Advertiser under which you can create Programmatic Order. You can not update any attribute of Programmatic Advertiser.

Order with Name "PubMatic Programmatic" - Programmatic Order is created with "PubMatic SSP Advertiser" advertiser.

 

When you would like to compete/open your inventory to Programmatic Channel,
you can create a PMP Deal/Open Exchange Line Item Under "PubMatic Programmatic" and assigned the priority and do the inventory targeting.

 

Request Sample URL

http://api.pubmatic.com/v1/uas/accounts?dimensions=name,description&filters=id eq 118385

Response

Sample Response 

    

Response will include account name and descriptions containing account id 118385.

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

Attachments

    Outcomes