Order API (UAS)

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

Description

The Order API enables you to create, update and retrieve Orders. 

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

Supported Operations

Service Name: /orders/

                                             

Method PathHTTP Method TypeDescriptionLink to Definition
/orders/POSTCreate an Order Create an Order
/orders/{id}GETRetrieve the details of a specific Order for the requested Order IdRetrieve Details of an Order
/orders/GET

Retrieve a list of Orders associated with your account

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, 

Retrieve a List of Orders
/orders/{id}PUT

Update a single Order. This will be in transaction.

This method will do a full update. If the request does not contain a value for an attribute it will be set to NULL/default value. However, if it is mandatory, it will fail and no Order will be updated.

Be sure you are passing all required attributes with required values.

Updating an Order
/orders/{id}PATCH

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

Note: It is different than PUT. In PUT, full replacement of the Order takes place. 

Update (Patch) an Order
/orders/{id}DELETEThis method deletes (archives) an OrderDelete an Order

 

Create an Order

Overview

This API enables the creation of an Order.  

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
accountIntegerYes

Account of the publisher for which this order will be created.

Account of the Publisher
nameStringYes

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

Name should be unique for your account.

Order Name
descriptionStringNo

Can be a maximum of 1024 characters. If description length exceeds 1024 characters, the API will store only the first 1024 characters.

Default is null.

Description that includes more details about the order.
orderTypeIntegerYesShould be valid and non-negative identifier for Order types presented in the Unified Ad Server.Type of an Order. (Retrieve a list of Order Types using the Order Type API.)
timeZoneIntegerNo

Valid time zone in which the order will be scheduled.

If a timeZone is not passed, the system will run an order at the Account-level time zone. 

Date and time should be passed in the selected time zone.

All line items start and end date time will respect the Order level time zone. 

Time Zone for an Order.

startDateStringYes

Should be the start date and time the order is expected to start delivering in selected time zone.

Date and Time should be greater than current date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss if Order date is futuristic. Otherwise, you can pass "now" if you would like to deliver order ASAP once its ready to serve. 
E.g. 2016-06-01T00:00:00

Order start date and time.
endDateStringNo

End date and time the order is expected to complete delivery in selected time zone.

Date and Time should be greater than start date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
E.g. 2016-06-01T00:00:00

If you would like to set order which will run for indefinitely please do not pass this parameter.

The minimum life of order should be > 60 minutes.

Order end date and time
statusIntegerNo

Status should be valid and exist in the system.

Default is "Draft" for newly created order if not provided. 

Once assigned, the Line Items API will change the status to Active. 

Using this API, you cannot change the status to "Delivering" or "Completed". The Unified Ad Server is only able to set this status. 

Status of the Order. You can retrieve the list of statuses using the Status API.

The following statuses are supported for an Order:

                                   
IDName
1Active
2Inactive
4Archived
5Draft
7Delivering
8Paused
9Completed
advertiserIntegerYes

Advertiser should be valid and exist in the system.   

The passed advertiser to be associated with an Order should not be in Archived Status.

If the associated advertiser is updated to an archived status after being associated with an Order, it should  not be validated during the update operation.

Advertiser for the order.

To create/edit/retrieve a list of advertisers, use the Advertiser API.

contactsArray of Order Contact ObjectsNo

If passed, contacts should be valid and exist in the system.

The passed Contact to be associated should not be in archived status while creating/updating with an archived contact.

If the Contact is updated to archive status after associating with an Order, it should not be validated during an update operation.

Contacts for the Order.

You can create/edit/retrieve a list of Contacts using the Contact API.

agencyIntegerNo

Should be valid and exist in the system.

Agency to be associated should not be in 'archived' status.

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

Agency for the order.

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

Note: If you want to remove associated agencies, you must pass an empty array. i.e. [  ]

adOpsIntegerYesShould be valid and exist in the system.

Ad Operational user for an Order.

You can create/edit/retrieve a list of Operational User details using the User API.

salesPersonIntegerNoShould be valid and exist in the system.

Sales person for an Order.

You can create/edit/retrieve a list of Sales Person details using the User API.

frequencyCapStringNoFrequency should be valid.Frequency cap for the order.
labelsList of Label ObjectsNoIf passed, labels should be valid and exist in the system.

Labels applied to the Order.

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

You can use the field "excluded" along with "id" if you want to remove the inherited label from Advertiser. e.g., "excluded": 1.

Note: If you want to remove associated labels, you must pass an empty array, i.e., [  ]. Only inherited labels (if any) will be associated.

isFavouriteBooleanNo Flag indicating whether or not an Order is a favorite.

Status Transition Matrix

                                                                            

FromToWho does it?
DraftActiveSystem
DraftArchivedUser
ActiveDeliveringSystem
ActiveInactiveUser
ActivePausedUser
DeliveringPausedUser
DeliveringInactiveUser
PausedActiveUser
PausedInactiveUser
PausedArchivedUser
InactiveActiveUser
InactiveArchivedUser
CompletedArchivedUser
ArchivedNot allowedUser

 

Status and Editable Fields Matrix

                                                                                   

StatusAdvertiserAgencyStarte TimeOrder TypeTime ZoneFrequency CapsComments
DraftYESYESYESYESYESYES
  • Order contains no Line Item
  • Status cannot be changed to Draft from the UI
ActiveNONONONONOYES
  • Current Time <Start Time OR Start TIME < Current Time < End Time.
  • Order contains at least one Line Item
  • No Line Item has started Delivering
DeliveringNONONONONONO
  • Start Time <==Current Time <==End Time
  • Order contains at least one Line Item
  • At least one Line Item has started Delivering OR at least one Line Item is currently Delivering
  • Status cannot be changed to Delivering from the UI
PausedNONONONONOYES
  • Active and Delivering Orders can be manually Paused
  • Paused Orders need to be manually started.
InactiveNONO

YES

  • ONLY if Current Time is less than old Start Time
  • New Start Time cannot be before the Current Time
NONONO
  • Active, Delivering and Paused Orders can be manually Deactivated.
  • Deactivated Orders need to be manually Activated.
CompletedNONONONONONO
  • Current Time > End Time
  • Status cannot be changed to Completed from the UI
ArchivedNONONONONONO
  • Draft, Inactive and Completed Orders can be manually Archived
  • Archived Orders need to be manually Deactivated.

Sample Request URL

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

Sample Request JSON

    

{
    "name": "Test-Order",
    "description": "This is test Order",
    "account": {
        "id": 118385
    },
    "orderType": {
        "id": 1
    },
    "status": {
        "id": 5
    },
    "startDate": "2016-01-18T13:49:25",
    "endDate": null,
    "advertiser": {
        "id": 4
    },
    "agency": {
        "id": 2
    },
    "adOps": {
        "id": 18314
    },
    "timeZone": {
        "id": 9
    },
    "contacts": [{
        "id": 8
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 1
    }],
    "labels": [{
        "id": 2,
        "isInherited": false
    }, {
        "id": 9,
        "isInherited": false
    }],
    "isFavourite": false
}

Response

Sample Response JSON

    

{
    "id": 160,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "Test-Order",
    "startDate": "2016-01-18T13:49:25",
    "orderType": {
        "id": 1,
        "name": "Sale",
        "url": "http://api.pubmatic.com/v1/uas/ordertypes/1"
    },
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "http://api.pubmatic.com/v1/uas/status/5"
    },
    "advertiser": {
        "id": 4,
        "name": "Advertiser-1",
        "url": "http://api.pubmatic.com/v1/uas/phoenix"
    },
    "agency": {
        "id": 2,
        "name": "Agency-1",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "description": "This is test Order",
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "adOps": {
        "id": 18314,
        "url": "http://api.pubmatic.com/v1/uas/users/18314"
    },
    "timeZone": {
        "id": 9,
        "code": "EET",
        "url": "http://api.pubmatic.com/v1/uas/timezones/9"
    },
    "contacts": [
        {
            "id": 8
        }
    ],
    "labels": [
        {
            "id": 2,
            "name": "Label-2",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/phoenix"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": false
        },
        {
            "id": 9,
            "name": "Label-9",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/phoenix"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": false
        },
        {
            "id": 6,
            "name": "Label-6",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/phoenix"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 7,
            "name": "Label-7",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 8,
            "name": "Label-8",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": true
        }
    ],
    "frequencyCaps": [
        {
            "frequencyCapPeriod": {
                "id": 1,
                "url": "http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
            },
            "capValue": 1,
            "periodValue": 1
        }
    ],
    "isFavourite": false
}
 

 

Retrieve Details of an Order

Overview

This API enables to retrieve the details of an Order.  

 

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/phoenix/orders/160 

Response

Sample Response JSON

    

{
    "id": 160,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "Test-Order",
    "startDate": "2016-01-18T13:49:25",
    "orderType": {
        "id": 1,
        "name": "Sale",
        "url": "http://api.pubmatic.com/v1/uas/ordertypes/1"
    },
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "http://api.pubmatic.com/v1/uas/status/5"
    },
    "advertiser": {
        "id": 4,
        "name": "Advertiser-1",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "agency": {
        "id": 2,
        "name": "Agency-1",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "description": "This is test Order",
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "adOps": {
        "id": 18314,
        "url": "http://api.pubmatic.com/v1/uas/users/18314"
    },
    "timeZone": {
        "id": 9,
        "code": "EET",
        "url": "http://api.pubmatic.com/v1/uas/timezones/9"
    },
    "contacts": [
        {
            "id": 8
        }
    ],
    "labels": [
        {
            "id": 2,
            "name": "Label-2",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": false
        },
        {
            "id": 9,
            "name": "Label-9",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": false
        },
        {
            "id": 6,
            "name": "Label-6",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 7,
            "name": "Label-7",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 8,
            "name": "Label-8",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": true
        }
    ],
    "frequencyCaps": [
        {
            "frequencyCapPeriod": {
                "id": 1,
                "url": "http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
            },
            "capValue": 1,
            "periodValue": 1
        }
    ],
    "isFavourite": false
}

 

Retrieve a List of Orders

Overview

This API allows you to retrieve a list of Orders associated with your 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.

Sample Request URL

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

 

Response

Sample Response

    

Returns all ordes associated with your account.

Generic Search

           

Sample Request URL

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

Sample Response

    

Retrieves orders that match the filter criteria.

Updating an Order

Overview

This API enables you to update an Order.  

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
accountIntegerYes

Account of the publisher for which this order will be created.

Account of the Publisher
nameStringYes

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

Name should be unique for your account.

Order Name
descriptionStringNo

Can be a maximum of 1024 characters. If description length exceeds 1024 characters, the API will store only the first 1024 characters.

Default is null.

Description that includes more details about the order.
orderTypeIntegerYesShould be valid and non-negative identifier for Order types presented in the Unified Ad Server.Type of an Order. (Retrieve a list of Order Types using the Order Type API.)
timeZoneIntegerNo

Valid time zone in which the order will be scheduled.

If a timeZone is not passed, the system will run an order at the Account-level time zone. 

Date and time should be passed in the selected time zone.

All line items start and end date time will respect the Order level time zone. 

Time Zone for an Order.

startDateStringYes

Should be the start date and time the order is expected to start delivering in selected time zone.

Date and Time should be greater than current date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss if Order date is futuristic. Otherwise, you can pass "now" if you would like to deliver order ASAP once its ready to serve. 
E.g. 2016-06-01T00:00:00

Order start date and time.
endDateStringNo

End date and time the order is expected to complete delivery in selected time zone.

Date and Time should be greater than start date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
E.g. 2016-06-01T00:00:00

If you would like to set order which will run for indefinitely please do not pass this parameter.

The minimum life of order should be > 60 minutes.

Order end date and time
statusIntegerNo

Status should be valid and exist in the system.

Default is "Draft" for newly created order if not provided. 

Once assigned, the Line Items API will change the status to Active. 

Using this API, you cannot change the status to "Delivering" or "Completed". The Unified Ad Server is only able to set this status. 

Status of the Order. You can retrieve the list of statuses using the Status API.

The following statuses are supported for an Order:

                                   
IDName
1Active
2Inactive
4Archived
5Draft
7Delivering
8Paused
9Completed
advertiserIntegerYes

Advertiser should be valid and exist in the system.   

The passed advertiser to be associated with an Order should not be in Archived Status.

If the associated advertiser is updated to an archived status after being associated with an Order, it should  not be validated during the update operation.

Advertiser for the order.

To create/edit/retrieve a list of advertisers, use the Advertiser API.

contactsArray of Order Contact ObjectsNo

If passed, contacts should be valid and exist in the system.

The passed Contact to be associated should not be in archived status while creating/updating with an archived contact.

If the Contact is updated to archive status after associating with an Order, it should not be validated during an update operation.

Contacts for the Order.

You can create/edit/retrieve a list of Contacts using the Contact API.

agencyIntegerNo

Should be valid and exist in the system.

Agency to be associated should not be in 'archived' status.

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

Agency for the order.

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

Note: If you want to remove associated agencies, you must pass an empty array. i.e. [  ]

adOpsIntegerYesShould be valid and exist in the system.

Ad Operational user for an Order.

You can create/edit/retrieve a list of Operational User details using the User API.

salesPersonIntegerNoShould be valid and exist in the system.

Sales person for an Order.

You can create/edit/retrieve a list of Sales Person details using the User API.

frequencyCapStringNoFrequency should be valid.Frequency cap for the order.
labelsList of Label ObjectsNoIf passed, labels should be valid and exist in the system.

Labels applied to the Order.

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

You can use the field "excluded" along with "id" if you want to remove the inherited label from Advertiser. e.g., "excluded": 1.

Note: If you want to remove associated labels, you must pass an empty array, i.e., [  ]. Only inherited labels (if any) will be associated.

isFavouriteBooleanNo Flag indicating whether or not an Order is a favorite.

Status Transition Matrix

                                                                            

FromToWho does it?
DraftActiveSystem
DraftArchivedUser
ActiveDeliveringSystem
ActiveInactiveUser
ActivePausedUser
DeliveringPausedUser
DeliveringInactiveUser
PausedActiveUser
PausedInactiveUser
PausedArchivedUser
InactiveActiveUser
InactiveArchivedUser
CompletedArchivedUser
ArchivedNot allowedUser

 

Status and Editable Fields Matrix

                                                                                   

StatusAdvertiserAgencyStarte TimeOrder TypeTime ZoneFrequency CapsComments
DraftYESYESYESYESYESYES
  • Order contains no Line Item
  • Status cannot be changed to Draft from the UI
ActiveNONONONONOYES
  • Current Time <Start Time OR Start TIME < Current Time < End Time.
  • Order contains at least one Line Item
  • No Line Item has started Delivering
DeliveringNONONONONONO
  • Start Time <==Current Time <==End Time
  • Order contains at least one Line Item
  • At least one Line Item has started Delivering OR at least one Line Item is currently Delivering
  • Status cannot be changed to Delivering from the UI
PausedNONONONONOYES
  • Active and Delivering Orders can be manually Paused
  • Paused Orders need to be manually started.
InactiveNONO

YES

  • ONLY if Current Time is less than old Start Time
  • New Start Time cannot be before the Current Time
NONONO
  • Active, Delivering and Paused Orders can be manually Deactivated.
  • Deactivated Orders need to be manually Activated.
CompletedNONONONONONO
  • Current Time > End Time
  • Status cannot be changed to Completed from the UI
ArchivedNONONONONONO
  • Draft, Inactive and Completed Orders can be manually Archived
  • Archived Orders need to be manually Deactivated.

Sample Request URL

https://$URI_PREFIX/{apiVersion}/phoenix/orders/160

Sample Request JSON

    

{
    "name": "Test-Order",
    "description": "This is test Order",
    "account": {
        "id": 118385
    },
    "orderType": {
        "id": 1
    },
    "status": {
        "id": 5
    },
    "startDate": "2016-01-18T13:49:25",
    "endDate": null,
    "advertiser": {
        "id": 4
    },
    "agency": {
        "id": 2
    },
    "adOps": {
        "id": 18314
    },
    "timeZone": {
        "id": 9
    },
    "contacts": [{
        "id": 8
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 1
    }],
    "labels": [{
        "id": 2,
        "isInherited": false
    }],
    "isFavourite": false
}

Response

Sample Response JSON

    

{
    "id": 160,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "Test-Order",
    "startDate": "2016-01-18T13:49:25",
    "orderType": {
        "id": 1,
        "name": "Sale",
        "url": "http://api.pubmatic.com/v1/uas/ordertypes/1"
    },
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "http://api.pubmatic.com/v1/uas/status/5"
    },
    "advertiser": {
        "id": 4,
        "name": "Advertiser-1",
        "url": "http://api.pubmatic.com/v1/uas/phoenix"
    },
    "agency": {
        "id": 2,
        "name": "Agency-1",
        "url": "http://api.pubmatic.com/v1/uas/phoenix"
    },
    "description": "This is test Order",
    "user": {
        "id": 18280,
        "url": "http://$URI_PREFIX/phoenix/users/18280"
    },
    "adOps": {
        "id": 18314,
        "url": "http://api.pubmatic.com/v1/uas/users/18314"
    },
    "timeZone": {
        "id": 9,
        "code": "EET",
        "url": "http://api.pubmatic.com/v1/uas/timezones/9"
    },
    "contacts": [
        {
            "id": 8
        }
    ],
    "labels": [
        {
            "id": 2,
            "name": "Label-2",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": false
        },
        {
            "id": 9,
            "name": "Label-9",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": false
        },
        {
            "id": 6,
            "name": "Label-6",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 7,
            "name": "Label-7",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 8,
            "name": "Label-8",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": true
        }
    ],
    "frequencyCaps": [
        {
            "frequencyCapPeriod": {
                "id": 1,
                "url": "http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
            },
            "capValue": 1,
            "periodValue": 1
        }
    ],
    "isFavourite": false
}
 

 

Update (Patch) an Order

Overview

This API enables you to patch update an Order.  

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
accountIntegerYes

Account of the publisher for which this order will be created.

Account of the Publisher
nameStringYes

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

Name should be unique for your account.

Order Name
descriptionStringNo

Can be a maximum of 1024 characters. If description length exceeds 1024 characters, the API will store only the first 1024 characters.

Default is null.

Description that includes more details about the order.
orderTypeIntegerYesShould be valid and non-negative identifier for Order types presented in the Unified Ad Server.Type of an Order. (Retrieve a list of Order Types using the Order Type API.)
timeZoneIntegerNo

Valid time zone in which the order will be scheduled.

If a timeZone is not passed, the system will run an order at the Account-level time zone. 

Date and time should be passed in the selected time zone.

All line items start and end date time will respect the Order level time zone. 

Time Zone for an Order.

startDateStringYes

Should be the start date and time the order is expected to start delivering in selected time zone.

Date and Time should be greater than current date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss if Order date is futuristic. Otherwise, you can pass "now" if you would like to deliver order ASAP once its ready to serve. 
E.g. 2016-06-01T00:00:00

Order start date and time.
endDateStringNo

End date and time the order is expected to complete delivery in selected time zone.

Date and Time should be greater than start date and time.

Date and Time must be in  yyyy-MM-dd'T'HH:mm:ss 
E.g. 2016-06-01T00:00:00

If you would like to set order which will run for indefinitely please do not pass this parameter.

The minimum life of order should be > 60 minutes.

Order end date and time
statusIntegerNo

Status should be valid and exist in the system.

Default is "Draft" for newly created order if not provided. 

Once assigned, the Line Items API will change the status to Active. 

Using this API, you cannot change the status to "Delivering" or "Completed". The Unified Ad Server is only able to set this status. 

Status of the Order. You can retrieve the list of statuses using the Status API.

The following statuses are supported for an Order:

                                   
IDName
1Active
2Inactive
4Archived
5Draft
7Delivering
8Paused
9Completed
advertiserIntegerYes

Advertiser should be valid and exist in the system.   

The passed advertiser to be associated with an Order should not be in Archived Status.

If the associated advertiser is updated to an archived status after being associated with an Order, it should  not be validated during the update operation.

Advertiser for the order.

To create/edit/retrieve a list of advertisers, use the Advertiser API.

contactsArray of Order Contact ObjectsNo

If passed, contacts should be valid and exist in the system.

The passed Contact to be associated should not be in archived status while creating/updating with an archived contact.

If the Contact is updated to archive status after associating with an Order, it should not be validated during an update operation.

Contacts for the Order.

You can create/edit/retrieve a list of Contacts using the Contact API.

agencyIntegerNo

Should be valid and exist in the system.

Agency to be associated should not be in 'archived' status.

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

Agency for the order.

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

Note: If you want to remove associated agencies, you must pass an empty array. i.e. [  ]

adOpsIntegerYesShould be valid and exist in the system.

Ad Operational user for an Order.

You can create/edit/retrieve a list of Operational User details using the User API.

salesPersonIntegerNoShould be valid and exist in the system.

Sales person for an Order.

You can create/edit/retrieve a list of Sales Person details using the User API.

frequencyCapStringNoFrequency should be valid.Frequency cap for the order.
labelsList of Label ObjectsNoIf passed, labels should be valid and exist in the system.

Labels applied to the Order.

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

You can use the field "excluded" along with "id" if you want to remove the inherited label from Advertiser. e.g., "excluded": 1.

Note: If you want to remove associated labels, you must pass an empty array, i.e., [  ]. Only inherited labels (if any) will be associated.

isFavouriteBooleanNo Flag indicating whether or not an Order is a favorite.

Status Transition Matrix                                            

FromToWho does it?
DraftActiveSystem
DraftArchivedUser
ActiveDeliveringSystem
ActiveInactiveUser
ActivePausedUser
DeliveringPausedUser
DeliveringInactiveUser
PausedActiveUser
PausedInactiveUser
PausedArchivedUser
InactiveActiveUser
InactiveArchivedUser
CompletedArchivedUser
ArchivedNot allowedUser

 

Status and Editable Fields Matrix

                                                                          

StatusAdvertiserAgencyStarte TimeOrder TypeTime ZoneFrequency CapsComments
DraftYESYESYESYESYESYES
  • Order contains no Line Item
  • Status cannot be changed to Draft from the UI
ActiveNONONONONOYES
  • Current Time <Start Time OR Start TIME < Current Time < End Time.
  • Order contains at least one Line Item
  • No Line Item has started Delivering
DeliveringNONONONONONO
  • Start Time <==Current Time <==End Time
  • Order contains at least one Line Item
  • At least one Line Item has started Delivering OR at least one Line Item is currently Delivering
  • Status cannot be changed to Delivering from the UI
PausedNONONONONOYES
  • Active and Delivering Orders can be manually Paused
  • Paused Orders need to be manually started.
InactiveNONO

YES

  • ONLY if Current Time is less than old Start Time
  • New Start Time cannot be before the Current Time
NONONO
  • Active, Delivering and Paused Orders can be manually Deactivated.
  • Deactivated Orders need to be manually Activated.
CompletedNONONONONONO
  • Current Time > End Time
  • Status cannot be changed to Completed from the UI
ArchivedNONONONONONO
  • Draft, Inactive and Completed Orders can be manually Archived
  • Archived Orders need to be manually Deactivated.

Sample Request URL

https://api.pubmatic.com/v1/uas/orders/160 

 

Sample Request JSON

    

{
    "name": "Test-Order-Patch"
}

Response

Sample Response JSON

    

{
    "id": 160,
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "Test-Order-Patch",
    "startDate": "2016-01-18T13:49:25",
    "orderType": {
        "id": 1,
        "name": "Sale",
        "url": "http://api.pubmatic.com/v1/uas/ordertypes/1"
    },
    "status": {
        "id": 5,
        "name": "Draft",
        "url": "http://api.pubmatic.com/v1/uas/status/5"
    },
    "advertiser": {
        "id": 4,
        "name": "Advertiser-1",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "agency": {
        "id": 2,
        "name": "Agency-1",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "description": "This is test Order",
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "adOps": {
        "id": 18314,
        "url": "http://api.pubmatic.com/v1/uas/users/18314"
    },
    "timeZone": {
        "id": 9,
        "code": "EET",
        "url": "http://api.pubmatic.com/v1/uas/timezones/9"
    },
    "contacts": [
        {
            "id": 8
        }
    ],
    "labels": [
        {
            "id": 2,
            "name": "Label-2",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": false
        },
        {
            "id": 9,
            "name": "Label-9",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": false
        },
        {
            "id": 6,
            "name": "Label-6",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 7,
            "name": "Label-7",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 1,
                "name": "Ad Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
            },
            "isInherited": true
        },
        {
            "id": 8,
            "name": "Label-8",
            "account": {
                "id": 118385,
                "url": "http://api.pubmatic.com/v1/uas/"
            },
            "labelType": {
                "id": 2,
                "name": "Competitive Exclusion",
                "url": "http://api.pubmatic.com/v1/uas/labeltype/2"
            },
            "isInherited": true
        }
    ],
    "frequencyCaps": [
        {
            "frequencyCapPeriod": {
                "id": 1,
                "url": "http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
            },
            "capValue": 1,
            "periodValue": 1
        }
    ],
    "isFavourite": false
}

 

Delete an Order

Overview

This API allows you to delete (archive) an Order.  

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/orders/160 

Response

Sample Response

    

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

Error Codes For Order API

                                                                         

Sr. No

Error Codes

Description

1.

PH_MISSING_OR_INVALID_PARAMETER

This error occurs when a mandatory field is missing or its value is not valid (not present in database).

It can occur for following fields in case of Order API

  1. id

  2. name

  3. account

  4. status

  5. user

  6. adOps

  7. advertiser

  8. agency

  9. timeZone

  10. label

2.

PH_DUPLICATE_ENTITY

This error occurs when value already exists in database for an unique identifier field.

It can occur for following fields in case of Order API

  1. Name

3.

PH_PARAMETER_VALUE_TOO_LARGE

This error occurs when input exceeds permitted number of characters.

  1. Name

  2. Description

4.

PH_INVALID_START_DATE

Order start date should be greater than/ equal to current date.

5.

PH_INVALID_ENTITY_END_DATE

Order End Date must be greater than/equal to order Start Date.

6.

PH_UNSUPPORTED_VALUE

Unsupported value of a field is provided in request.

It can occur for following fields -

  1. status

7.

PH_ATTEMPT_TO_UPDATE_RESTRICTED_FIELD_IN_STATUS

This error occurs when a field is not editable in that status of line item. See editable field matrix below.

8.

PH_CAN_NOT_CHANGE_STATUS

This error occurs when status transition is not valid. see status transition matrix below.

9.

PH_LABEL_REPEATED_IN_HIERARCHY

This error occurs when you try to map an inherited label again to the entity.

10.

PH_CANNOT_CREATE_RECORD_FOR_SSP_ADVERTISER

This error occurs when you try to create an order for an SSP type of Advertiser.

11.

PH_ATTEMPT_TO_UPDATE_SEALED_VALUE

This error occurs when you try to update non editable field.

It can occur for following fields -

  1. Advertiser

  2. Account

12.

PH_ENTITY_NOT_BELONGS_TO_ACCOUNT

This error occurs when a user tries to create / update an order for a different account than that of its advertiser.

13.

PH_ORDER_MINIMUM_ALLOWED_TIME_SPAN

This error occurs when user tries to create an Order with difference in Start Date and End Date less than one hour.

 

Status Transition Matrix

                                                                            
FromToWho does it?
DraftActiveSystem
DraftArchivedUser
ActiveDeliveringSystem
ActiveInactiveUser
ActivePausedUser
DeliveringPausedUser
DeliveringInactiveUser
PausedActiveUser
PausedInactiveUser
PausedArchivedUser
InactiveActiveUser
InactiveArchivedUser
CompletedArchivedUser
ArchivedNot allowedUser

 

Status and Editable Fields Matrix

                                                                                   
StatusAdvertiserAgencyStart TimeOrder TypeTime ZoneFrequency CapsComments
DraftYESYESYESYESYESYES
  • Order contains no Line Item
  • Status cannot be changed to Draft from the UI
ActiveNONONONONOYES
  • Current Time <Start Time OR Start TIME < Current Time < End Time.
  • Order contains at least one Line Item
  • No Line Item has started Delivering
DeliveringNONONONONONO
  • Start Time <==Current Time <==End Time
  • Order contains at least one Line Item
  • At least one Line Item has started Delivering OR at least one Line Item is currently Delivering
  • Status cannot be changed to Delivering from the UI
PausedNONONONONOYES
  • Active and Delivering Orders can be manually Paused
  • Paused Orders need to be manually started.
InactiveNONO

YES

  • ONLY if Current Time is less than old Start Time
  • New Start Time cannot be before the Current Time
NONONO
  • Active, Delivering and Paused Orders can be manually Deactivated.
  • Deactivated Orders need to be manually Activated.
CompletedNONONONONONO
  • Current Time > End Time
  • Status cannot be changed to Completed from the UI
ArchivedNONONONONONO
  • Draft, Inactive and Completed Orders can be manually Archived
  • Archived Orders need to be manually Deactivated.

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 65

Attachments

    Outcomes