External API Usage Documentation

Usage

Identity Access Management (IAM)

All external HTTP requests are authenticated against our internal IAM provider. Consequently, all users of our API will require that an account be created within our IAM provider, and you will use this account’s credentials to access our External Orders REST API.

Please contact your AdCellerant representative to create your account.

Auth Token

Once your account has been created, we will provide you with your username and an auth token.

REST API

Authentication

As mentioned in our Identity Access Management (IAM) section, all HTTP requests are authenticated against our internal AIM provider by validating every HTTP request against your account’s credentials. The credentials must be included in the ‘Authorization’ header of your request as defined by the ‘basic’ authorization specification RFC 7617: https://tools.ietf.org/html/rfc7617 .

For example:

If the user agent wishes to send the user-id "Aladdin" and password "open sesame," it would use the following header field:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Response Codes

200 - When the request was successful and there is a body to be returned
204 - When the request was successful but there is no body to be returned
- A common case for this is a DELETE operation
401 - The user is unauthorized to call the API
403 - The user is authorized to call the API but does not have access to this resource.
404 - The requested resource was not found.
- This should not be used for operations where multiple results are expected such as a list or search. In this case an empty array or excluding the result from the array is the desired behavior.
429 - rate limit exceeded.
500 - An unexpected error occurred.

Base Host

All API requests start with our base API host:

Production: https://api.adcellerant.com
Staging: https://stg.api.adcellerant.com

External id

The external Id allows API partners to store their unique Id on a proposal and correlate it back to a sold order. The API partner needs to create a link out from their system to AdCellerrant, which will allow a user to complete a proposal in AdCellerant. The API partner can correlate the external Id saved on that proposal back to the original order within their software application. The <external_id> would like the unique Id with the API partners system.

Staging: https://stg.ui.marketing/proposals/new?externalId=%3Cexternal_id%3E
Production: https://ui.marketing/proposals/new?externalId=%3Cexternal_id%3E

Proposals

Get Proposals

The Get Proposals API provides our Partners' capability to retrieve proposals without requiring the use of our proprietary Proposals tool in UI.Marketing.

To get proposals, submit an HTTP request to our external API following the specifications below:

METHOD: GET
HOST: Base Host
Endpoint: /proposal

Header Specifications

Authorization

Input Specifications

Parameters
- hierarchId (Long, required)
- externalId (String, required)
- updatedAfter (Date String, optional, ISO format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX)
- pageNumber (Integer, optional, defaults to 1)
- pageSize (Integer, optional, defaults to 25)

Output Specifications

Pagination Information
- Total number of results
- Total number of pages
- The current page number
- The page size
Results
- The page of proposals that match the query params

Example Request:

http://stg.api.adcellerant.com/proposal?hierarchyId=54&externalId=1a2b&pageNumber=1&pageSize=25

Example Response:

Status: 200 OK
Body:

{
   "pageNumber": 1,
   "pageSize": 25,
   "totalPages": 1,
   "totalCount": 1,
   "results": [
       {
          "products": [{
               "id":100
               "productKey": "key",
               "budget": 10000,
               "proposedRetailRate": 0.0,
               "retailRate": 10.0,
               "wholeSaleRate": 10.0,
               "startDate": "2021-01-02T14:00:00.000Z",
               "endDate": "2021-02-09T14:00:00.000Z",
               "monthlyAllocations": [
                     {
                        "startDate": "2021-01-01",
                        "endDate": "2021-01-31",
                        "amount": 100
                     },
                     {
                        "startDate": "2021-02-01",
                        "endDate": "2021-02-29",
                        "amount": 100
                     }
                ],
               "managementFee": null
            }
         ],
          "id": 2040,
          "externalId": "47h8347W3",
          "orderId": "2398",
          "startDate": "2021-01-02T14:00:00.000Z",
          "endDate": "2021-03-09T14:00:00.000Z",
          "createdDate": "2020-11-28T11:20:12.097Z",
          "updatedDate": "2020-12-01T05:30:45.123Z",
          "name": "Example Proposal Foo",
          "advertiserId": "300",
          "authorizationIds":[
                "0000-1234-1234-1244-14abcdefg"
          ],
          "requester": "Some Requester",
          "budget": 23000
       }
   ]
}

Edit Proposals

Once the proposal is created, the API partner can edit a proposal by concatenating the URL with the external API's Proposal data.

Staging: https://stg.ui.marketing/proposals/proposal/%3Cid%3E
Production: https://ui.marketing/proposals/proposal/%3Cid%3E

Orders

Get Orders

The Get Orders API provides our Partners' capability to retrieve orders without requiring the use of our proprietary Proposals tool in UI.Marketing.

To get orders, submit an HTTP request to our external API following the specifications below:

METHOD: GET
HOST: Base Host
Endpoint: /order

Header Specifications

Authorization

Input Specifications

Parameters
- advertiserId (optional, required if no hierarchyId given)
- hierarchyId (optional, required if no advertiserId given)
- pageNumber (optional, defaults to 1)
- pageSize (optional, defaults to 25)

Output Specifications

Pagination Information
- Total number of results
- Total number of pages
- The current page number
- The page size
Results
- The page of orders that match the query params

Example Request:

http://stg.api.adcellerant.com/order?advertiserId=123&pageNumber=1&pageSize=25

Example Response:

Status: 200 OK
Body:

{
   "pageNumber": 1,
   "pageSize": 25,
   "totalPages": 1,
   "totalCount": 2,
   "results": [
       {
           "id": 2,
           "status": "SOLD",
           "advertiserId": "123",
           "ownerEmail": "someEmail@domain.com",
           "name": "Sample Order - 1",
           "orderDetails": [
               {
                   "id": 14,
                   "status": "SOLD",
                   "name": "Sample Order - 1, Detail - 2",
                   "budget": 1234.0,
                   "approvedBy": "someApprover@domain.com",
                   "startDate": "2020-05-01T04:30:45.123Z",
                   "endDate": "2020-05-30T04:30:45.123Z"
               },
               {
                   "id": 13,
                   "status": "SOLD",
                   "name": "Sample Order - 1, Detail - 1",
                   "budget": 123.0,
                   "approvedBy": null,
                   "startDate": "2020-05-11T04:30:45.123Z",
                   "endate": "2020-05-30T04:30:45.123Z"
               }
           ]
       },
       {
           "id": 1,
           "status": "SOLD",
           "advertiserId": "123",
           "hierarchyId": "200",
           "ownerEmail": "someEmail@domain.com",
           "name": "Sample Order - 2",
           "orderDetails": [
               {
                   "id": 12,
                   "status": "SOLD",
                   "name": "Sample Order - 2, Detail - 1",
                   "budget": 123.0,
                   "approvedBy": null,
                   "startDate": "2020-05-23T04:30:45.123Z",
                   "endDate": "2020-05-26T04:30:45.123Z"
               }
           ]
       }
   ]
}

Create Order

The Create Order API provides our Partners' capability to create orders without requiring the use of our proprietary Proposals tool in UI.Marketing.

To create orders, submit an HTTP request to our external API following the specifications below:

METHOD: POST
HOST: Base Host
Endpoint: /order

Header Specifications

Authorization
Content-Type: application/JSON

Input Specifications

Body
- advertiserId (String, required)
- hierarchyId (String, required)
- name (String, required)
- email (String, required)
- orderDetail (JSON, required)
  - productKey (String, required)
  - budget (Integer, required)
  - name (String, required)
  - startDate (Date/Time, required)
  - endDate (Date/Time, required)
  - additionalInfo (JSON, optional)

Output Specifications

The Created Order
- id
- status
- advertiserId
- hierarchyId
- name
- ownerEmail
- orderDetail
  - id
  - status
  - budget
  - name
  - approvedBy
  - startDate
  - endDate

Example Request:

{
   "advertiserId": "5134",
   "hierarchyId": "37",
   "name": "My Order",
   "email": "ownerEmail@company.com",
   "orderDetail" : {
       "productKey": "some_display_product",
       "budget": 10000,
       "name": "My Order Detail",
       "startDate": "2021-01-23T04:30:45.123Z",
       "endDate": "2021-02-23T07:30:45.123Z",
       "additionalInfo": {
           "website": "company.website.net",
           "proposedImpressions": 250000
       }
   }
}

Example Response:

Status: 200 OK
Body: