Publisher Management API 1.3

Version History

History	Note
Ver 1.3	Document update 2024-02-28 API updates regarding publisher api login Step 1. Log In and Copy the Secret Token Step 2. Sign a JWT Token
Ver 1.2	Document update 2022-03-21 API updates regarding in-app bidding Step 4. Create Placements Step 5. Update Your Placement (and Optionally Define a Flat CPM and in-app bidding)
Ver 1.1	Document update 2020-06-02 API updates regarding Flat CPM: Step 4. Create Placements Step 5. Update Your Placement (and Optionally Define a Flat CPM)
Ver 1.0	Document creation 2020-03-05

Overview

The Liftoff Monetize Publisher Management API allows you to perform a number of publishing and app management tasks. It includes:

• Create, get, and edit applications
• Create, get, and edit placements

You can view the app and placement you created on the dashboard when you log in with your Liftoff account information.

Get Started

To start using the Publisher Management API, make sure you: 

• have a valid account, set up in the Liftoff Monetize dashboard
• have read these API instructions 
• use the Vungle_Publisher_API_v1.2.yaml file that is attached to this article

API Endpoints

• https:/https://auth-api.vungle.com/v2/auth
• https://publisher-api.vungle.com/api/v1/applications

API Instructions

Step 1. Log In and Copy the Secret Token

Login to the Monetize Dashboard and select My Account from the menu in the top right. Copy your secret token.

Sample Token

Sample token if you have an existing account (your token will have the old format):

252d20a04235f953712db952ddf42374

Sample token if you are creating a new account (your token is generated using a new format):

eyJyYXciOiJhOTI3NjkxNDMyZWY1YzgyYTFkOWRjMzUzODI3ZDc4ZDY2MTViNGM4YWFmOWMxN2Q3YzI2MWY3MjUyZDZjMjExM2M1ZjI3ZWY4YjRiOWQ1NzE4Yzk3ZDcyZTZjMDJmZDQiLCJpZCI6IjYzZGI0MjVhZjQ1ZTBkMDAxMTA2NzEzMyIsIm5hbWUiOiJwdWJfYXBpX3JlZnJlc2gifQ==

Step 2. Sign a JWT Token

With your secret token copied in Step 1, sign a JWT token to call the Publisher Management API:

Example using cURL:

curl -X GET "https://auth-api.vungle.com/v2/auth" -H "x-api-key: [token]"

Replace [token] with the token you copied in Step 1.

The response should be similar to this:

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYzZGI0MjVhZjQ1ZTBkMDAxMTA2NzEzMyIsImFjY291bnQiOiI1YWFmNzY5NWZhNDc5NDIxNDkwZmRjNGEiLCJlbWFpbCI6Indlc2hpQGxpZnRvZmYuaW8iLCJmZWF0dXJlcyI6WyJmZWF0dXJlX2ZsYXRfY3BtX2Z1bGwiLCJmZWF0dXJlX2NwbV9mbG9vciIsImZlYXR1cmVfbWF4X2FkX2R1cmF0aW9uIiwiZmVhdHVyZV9mbGF0X2NwbV9ub25mdWxsIl0sInJvbGUiOiJzdXBlcl9hZG1pbiIsImlhdCI6MTY5MjA4MzM5MiwiZXhwIjoxNjkyMTEyMTkyfQ.GGsG5LoG9cinKdQUvH_PiYr4GjlQ2quWw7gR2-Y_4ck"}

Possible Errors

• Forbidden:
  {"messages":["Forbidden."],"code":400403}
  
  You may have copied the wrong token. Make sure you copy the Secret Token as opposed to the API Key or the Reporting API Key.
  
  
• Account not activated:
  {"messages":["Account not activated."],"code":403001}
  
  You must activate your Liftoff Monetize account first. Check your email inbox for the activation email.

Step 3. Create Applications

Use this API to create applications. The response will include the app name, platform, Liftoff app ID, etc. Refer to the response body for more details.

Method: POST / applications

cURL example:

curl -X POST "https://publisher-api.vungle.com/api/v1/applications" \
      -H "accept: application/json" \
      -H "Authorization: [API Token]" \
      -H "Content-Type: application/json" \
      -d '{ 
          "platform": "ios", 
          "name": "test_app_789", 
          "store": { 
              "id": "string",
              "category": "Battle Royale", 
              "isPaid": true, 
              "isManual": true, 
              "url": "https://testmyapp.com", 
              "thumbnail": "string" 
          }, 
          "isCoppa": true}'
  

Response body:

{
    "isCoppa": true,
    "name": "Test_Creating_an_application",
    "platform": "ios",
    "store": {
      "category": "",
      "id": "1234567890",
      "isManual": true,
      "isPaid": false
    },
    "id": "5e56099c57d130000137da68",
    "owner": "5dd268c7a4305a00173ba129",
    "status": "test",
    "vungleAppId": "5e56099c57d130000137da68",
    "connection": "all",
    "defaultPlacement": "5e56099c57d130000137da6a",
    "forceView": {
      "nonRewarded": false,
      "rewarded": true
    },
    "maxVideoLength": 46,
    "minOsVer": "6.0",
    "orientation": "both",
    "tagFilters": {
      "blacklist": null
    },
    "testDevices": []
  }

Step 4. Create Placements

Use this API to create placements. The response will include the placement name, placement ID, Liftoff app ID, placement reference ID, etc. Refer to the response body for more details.

Method: POST / placements

• To create placements for your specific application, use that application’s vungleAppId with FlatCPM OR in-app bidding.
• For non-banner placements, you don’t need to pass the adRefreshDuration: field in the API call. However, if you do decide to pass that field, the adRefreshDuration in the body must be greater than or equal to '10'.

cURL example with FlatCPM:

curl -X POST "https://publisher-api.vungle.com/api/v1/placements" \
      -H "accept: application/json" \
      -H "Authorization: Bearer [Login Token]" \
      -H "Content-Type: application/json" \
      -d '{ 
          "application": "5ebe5918c41de60001bbd250", 
          "name": "api_inter_placement_20200515", 
          "type": "interstitial", 
          "allowEndCards": true, 
          "isSkippable": true, 
          "cpmFloor": { 
              "default": 20, 
              "geo": { 
                  "CN": 18, "US": 19, "JP": 20 
            } 
          },
          "flatCPM": { 
              "default": 20, 
              "geo": { 
                  "CN": 18, "US": 19, "JP": 20 
              } 
          }, 
          "isFlatCPMEnabled": true
      }'
  

Response body:

{
    "allowEndCards": true,
    "application": {
      "isCoppa": true,
      "name": "test_app_20200515",
      "platform": "ios",
      "store": {
        "category": "",
        "id": "string",
        "isManual": true,
        "isPaid": false
      },
      "id": "5ebe5918c41de60001bbd250",
      "mutable": false,
      "owner": "5a0b03dc33675100118bafad",
      "status": "test",
      "vungleAppId": "5ebe5918c41de60001bbd250"
    },
    "id": "5ebe59be5e11600001aa6454",
    "isSkippable": true,
    "mutable": true,
    "name": "api_inter_placement_20200515_2",
    "referenceID": "API_INTER_PLACEMENT_20200515_2-2202429",
    "status": "active",
    "type": "interstitial",
    "flatCPM": {
      "default": 22,
      "geo": {
        "CN": 21,
        "JP": 19,
        "US": 20
      }
    },
    "flatCPMCap": {
      "default": 25
    },
    "flatCPMCd": "2020-05-18T08:58:38.646Z",
    "isFlatCPMEnabled": true,
    "videoOrientationOverride": "none"
  }

cURL example with in-app bidding:

curl -X POST "https://publisher-api.vungle.com/api/v1/placements" \
      -H "accept: application/json" \
      -H "Authorization: Bearer [API Token]" \
      -H "Content-Type: application/json" \
      -d '{ 
          "application": "5ebe5918c41de60001bbd250", 
          "name": "api_inter_placement_20200515", 
          "type": "interstitial", 
          "allowEndCards": true, 
          "isSkippable": true, 
          "isHBParticipation": true
      }'
  

Response body:

{
    "allowEndCards": true,
    "application": {
      "isCoppa": true,
      "name": "test_app_20200515",
      "platform": "ios",
      "store": {
        "category": "",
        "id": "string",
        "isManual": true,
        "isPaid": false
      },
      "id": "5ebe5918c41de60001bbd250",
      "mutable": false,
      "owner": "5a0b03dc33675100118bafad",
      "status": "test",
      "vungleAppId": "5ebe5918c41de60001bbd250"
    },
    "id": "5ebe59be5e11600001aa6454",
    "isSkippable": true,
    "mutable": true,
    "name": "api_inter_placement_20200515_2",
    "referenceID": "API_INTER_PLACEMENT_20200515_2-2202429",
    "status": "active",
    "type": "interstitial",
    "isHBParticipation": true, 
    "isSkippable": true, 
    "videoOrientationOverride": "none"
  }

Step 5. Update Your Placement (and Optionally Define a Flat CPM and in-app bidding)

Use this API to update your placements, including setting up a Flat CPM value for them. The response will include the placement ID, the Liftoff app ID, and the placement reference ID. Refer to the response body below for more details. 

Method: PATCH / placements/{id}

• Flat CPM is only available for select publisher accounts; contact your account manager to activate Flat CPM.
• In-App Bidding is only available for select publisher accounts; contact your account manager to use in-app bidding.
• Please either enable in-app bidding or Flat CPM, but not both at the same time.
• Put your placement name in the PATCH call instead of leaving it as "string".

  For example, in the API call shown below, a user tries to update the placement, but leaves the “name” as “String” instead of passing the placement name. This oversight will generate errors on the dashboard:

  

cURL example for Flat CPM:

curl -X PATCH "https://publisher-qa-api.vungle.io/api/v1/placements/5ebe596c5e11600001aa6452" \
      -H "accept: application/json" \
      -H "Authorization: Bearer [API Token]" \
      -H "Content-Type: application/json" \
      -d '{ 
          "name": "string", 
          "allowEndCards": true, 
          "isSkippable": true, 
          "isSkippable": true, 
          "videoOrientationOverride": "none", 
          "status": "active", 
          "flatCPM": { 
              "default": 25, 
              "geo": { "CN": 21, "JP": 22, "US": 23 } 
          }, 
          "isFlatCPMEnabled": true
      }'
  

Response body:

{
    "allowEndCards": true,
    "application": {
      "isCoppa": true,
      "name": "test_app_20200515",
      "platform": "ios",
      "store": {
        "category": "",
        "id": "string",
        "isManual": true,
        "isPaid": false
      },
      "id": "5ebe5918c41de60001bbd250",
      "mutable": false,
      "owner": "5a0b03dc33675100118bafad",
      "status": "test",
      "vungleAppId": "5ebe5918c41de60001bbd250"
    },
    "id": "5ebe596c5e11600001aa6452",
    "isSkippable": true,
    "mutable": true,
    "name": "api_inter_placement_20200515",
    "referenceID": "API_INTER_PLACEMENT_20200515-2630554",
    "status": "active",
    "type": "interstitial",
    "flatCPM": {
      "default": 22,
      "geo": {
        "CN": 19,
        "JP": 22,
        "US": 21
      }
    },
    "flatCPMCap": {
      "default": 25
    },
    "flatCPMCd": "2020-05-25T04:33:01.856Z",
    "isFlatCPMEnabled": true,
    "videoOrientationOverride": "none"
  }

cURL example for in-app bidding:

curl -X PATCH "https://publisher-qa-api.vungle.io/api/v1/placements/5ebe596c5e11600001aa6452" \
      -H "accept: application/json" \
      -H "Authorization: Bearer [API Token]" \
      -H "Content-Type: application/json" \
      -d '{ 
          "name": "string", 
          "allowEndCards": true, 
          "isSkippable": true, 
          "isSkippable": true, 
          "videoOrientationOverride": "none", 
          "status": "active", 
          "isHBParticipation": true
      }'
  

Response body:

{
    "allowEndCards": true,
    "application": {
      "isCoppa": true,
      "name": "test_app_20200515",
      "platform": "ios",
      "store": {
        "category": "",
        "id": "string",
        "isManual": true,
        "isPaid": false
      },
      "id": "5ebe5918c41de60001bbd250",
      "mutable": false,
      "owner": "5a0b03dc33675100118bafad",
      "status": "test",
      "vungleAppId": "5ebe5918c41de60001bbd250"
    },
    "id": "5ebe596c5e11600001aa6452",
    "isSkippable": true,
    "mutable": true,
    "name": "api_inter_placement_20200515",
    "referenceID": "API_INTER_PLACEMENT_20200515-2630554",
    "status": "active",
    "type": "interstitial",
    "isHBParticipation": true, 
    "videoOrientationOverride": "none"
  }

Other API Calls

Get an Application

Method: GET /applications/{id}

Request example URL: https://publisher-api.vungle.com/api/v1/applications/5e65ebcd688ef40001e7f436

cURL example:

curl -X GET "https://publisher-api.vungle.com/api/v1/applications/5e65ebcd688ef40001e7f436" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX19LCJhY2Nlc3MtZ3Jvdy12dW5nbGUtY29tIjp0cnVlLCJnb2Rtb2RlIjp0cnVlLCJpbXBlcnNvbmF0ZSI6dHJ1ZSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX19LCJyb2xlIjoidnVuZ2xlciIsImFwaVRva2VuIjoiN2I4YTcyZTIyMmVjOTQ2NTMwODJiM2U0MjU1MmFjZTEiLCJpYXQiOjE1ODM3Mzc2NDgsImV4cCI6MTU4MzgyNDA0OH0.EFtjHvwusymKq5jwoFemDEBexJUzExNlwtVYApY5if0"

Response body:

{
    "isCoppa": true,
    "name": "test_app_hanli_api_production",
    "platform": "ios",
    "store": {
      "category": "",
      "id": "string",
      "isManual": true,
      "isPaid": false
    },
    "id": "5e65ebcd688ef40001e7f436",
    "owner": "5a0b03dc33675100118bafad",
    "placement_count": 1,
    "status": "test",
    "vungleAppId": "5e65ebcd688ef40001e7f436",
    "connection": "all",
    "forceView": {
      "nonRewarded": false,
      "rewarded": true
    },
    "maxVideoLength": 46,
    "minOsVer": "6.0",
    "orientation": "both",
    "tagFilters": {
      "blacklist": []
    },
    "testDevices": []
  }

Get a Placement

Method: GET/ placements/{id}

Request example URL: https://publisher-api.vungle.com/api/v1/placements/520d751489e451af34000028

cURL example:

curl -X GET "https://publisher-api.vungle.com/api/v1/placements/520d751489e451af34000028" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX19LCJhY2Nlc3MtZ3Jvdy12dW5nbGUtY29tIjp0cnVlLCJnb2Rtb2RlIjp0cnVlLCJpbXBlcnNvbmF0ZSI6dHJ1ZSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX19LCJyb2xlIjoidnVuZ2xlciIsImFwaVRva2VuIjoiN2I4YTcyZTIyMmVjOTQ2NTMwODJiM2U0MjU1MmFjZTEiLCJpYXQiOjE1ODM3Mzg2NTYsImV4cCI6MTU4MzgyNTA1Nn0.oJH2btCK_54C64s25Ls-Ez4pp0DZG4WudXS3YL32-NE"

Response body:

{
    "application": {
      "platform": "ios",
      "name": "string",
      "store": {
        "id": "string",
        "category": "Battle Royale",
        "isPaid": true,
        "isManual": true,
        "url": "string",
        "thumbnail": "string"
      },
      "isCoppa": true,
      "id": "520d751489e451af34000028",
      "vungleAppId": "string",
      "owner": "string",
      "placement_count": 0,
      "status": "active"
    },
    "name": "string",
    "type": "interstitial",
    "allowEndCards": true,
    "isSkippable": true,
    "referenceID": "string",
    "id": "520d751489e451af34000028",
    "status": "active",
    "videoOrientationOverride": "none",
    "defaultCPMFloor": 0,
    "defaultFlatCPM": 0,
    "isFlatCPMEnabled": true,
    "flatCPM": {
      "geo": {
        "DZ": 2
      }
    },
    "cpmFloor": {
    "default": 1,
    "geo": {
        "CN": 3
      }
    },
    "isRefreshEnabled": true,
    "adRefreshDuration": 0
  }

Best Practices

Read Our Documentation

Read the Liftoff Monetize Publisher API YAML file attached to this article, as well as this entire Publisher Management API article. Pay attention to the bullet points in each section of this article.

Optional Fields

If a field is optional, it is denoted as x-omitempty or x-nullable in the Liftoff Monetize Publisher API YAML file, which is attached to this article. If you don’t pass a value for an optional field, the default value will be 'False', NULL, or '0', depending on the type of the field.

Example of optional (x-omitempty and x-nullable) fields:

  nonRewarded:
      type: boolean
      x-omitempty: false
  minOsVer:
    type: string
            
  maxVideoLength:
    type: integer
    minimum: 15
    maximum: 60
    x-nullable: true

Editing or Updating Fields

To edit or update fields using the API, we strongly recommend using the GET method to get the object, editing that object, and then passing the value you want to change through the API.

Setting a Flat CPM (Contact Your Account Manager)

• You must contact your account manager to be able to use Flat CPM.
• Setting a Flat CPM is optional in the API. Optional fields are denoted as x-omitempty or x-nullable in the Liftoff Monetize Publisher API YAML file that is attached to this article to indicate an optional field.
• When you first create a placement, Flat CPM is disabled by default. To use Flat CPM, you can enable it in Step 5 above.
• To edit or update the field, refer to Editing or Updating Fields.