Publisher Management API 1.1

Version History

History	Note
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 Vungle 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 Vungle account information.

Get Started

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

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

API Endpoints

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

API Instructions

Step 1. Log In and Get Token

In the Terminal application on your computer (for Mac, follow the instructions here), use the cURL command to log in and get a token, using your own account email and password.

• The token is valid for 24 hours. 
• Every time you use cURL to do a signature, you will get a new token.

cURL command:

curl -X POST "https://auth-api.vungle.com/login" -H "accept: application/json" -H "vungle-source: api" -H "vungle-version: 1" -H "Content-Type: application/json" -d '{ "username": "your account email", "password": "your account password"}'

Sample token:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkMWFkYWQyNDU5MzQ0MDAxMjA0Y2UzNSIsImFjY291bnQiOiI1ZDFhZGFkMjQ1OTM0NDAwMTIwNGNlMzMiLCJlbWFpbCI6ImFwaV90ZXN0QHRlc3QuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX0sImZsYXRfY3BtIjp7IndyaXRlIjp0cnVlLCJyZWFkIjp0cnVlfX19LCJyb2xlIjoid3JpdGUiLCJhcGlUb2tlbiI6IjFmMmI3NjcyN2YxMDkwZDliMDFhMmZmNmMwNmYwYmNmIiwiaWF0IjoxNTYyMDUwNDA3LCJleHAiOjE1NjIxMzY4MDd9.L7ooHi4_rMPd26QDTQrsW6jBiFympFM3GDRw3fTXSVs"

Step 2. Authorize: Call the Publisher API Using Your Own Token

Example using cURL:

curl -X GET "https://publisher-api.vungle.com/api/v1/applications" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkZDI2OGM3YTQzMDVhMDAxNzNiYTEyYiIsImFjY291bnQiOiI1ZGQyNjhjN2E0MzA1YTAwMTczYmExMjkiLCJlbWFpbCI6ImFwaV90ZXN0QHRlc3QuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX19LCJwdWIiOnsiYWNjZXNzIjp0cnVlfX0sInJvbGUiOiJ3cml0ZSIsImFwaVRva2VuIjoiMzlkN2I5M2QxNWQxNDM0MjZhYzA1MzlmZDdmNmYwOTUiLCJpYXQiOjE1NzQwNzE2NDcsImV4cCI6MTU3NDE1ODA0N30.sMzguUat2RFJKMp1qx4FW_arTXDejm7ejjmDq_JWzaU"

The token used above is only an example; you must use your own token, which you generated in Step 1.

Step 3. Create Applications

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

Method: POST / applications

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

Example value:

{
  "platform": "ios",
  "name": "string",
  "store": {
    "id": "string",
    "category": "Battle Royale",
    "isPaid": true,
    "isManual": true,
    "url": "string",
    "thumbnail": "string"
  },
  "isCoppa": true
}

cURL example:

curl -X POST "https://publisher-api.vungle.com/api/v1/applications" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVkZDI2OGM3YTQzMDVhMDAxNzNiYTEyYiIsImFjY291bnQiOiI1ZGQyNjhjN2E0MzA1YTAwMTczYmExMjkiLCJlbWFpbCI6ImFwaV90ZXN0QHRlc3QuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJmbGF0X2NwbSI6eyJ3cml0ZSI6dHJ1ZX0sImNwbV9mbG9vciI6eyJyZWFkIjpmYWxzZSwid3JpdGUiOmZhbHNlfX0sInB1YiI6eyJhY2Nlc3MiOnRydWV9fSwicm9sZSI6IndyaXRlIiwiYXBpVG9rZW4iOiIzOWQ3YjkzZDE1ZDE0MzQyNmFjMDUzOWZkN2Y2ZjA5NSIsImlhdCI6MTU4MjcxOTcwMCwiZXhwIjoxNTgyODA2MTAwfQ.4Puf39duKVhGP0wZfWkSGi3fPEnpAzdXSr4Tot8PljQ" -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,
  "minOs": 6,
  "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, Vungle app ID, placement reference ID, etc. Refer to the response body for more details.

Method: POST / placements

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

Example value:

{
  "application": "5e560cbb57d130000137da72",
  "name": "placement_creat_test_1",
  "type": "interstitial",
  "allowEndCards": true,
  "isSkippable": true
}

• To create placements for your specific application, use that application’s vungleAppId.
• 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:

curl -X POST "https://publisher-api.vungle.com/api/v1/placements" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX0sImZsYXRfY3BtIjp7IndyaXRlIjp0cnVlfX0sImFjY2Vzcy1ncm93LXZ1bmdsZS1jb20iOnRydWUsImFkbWluIjp7ImZsYXQtY3BtIjp0cnVlfSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX0sImltcGVyc29uYXRlIjp0cnVlLCJnb2Rtb2RlIjp0cnVlfSwicm9sZSI6InZ1bmdsZXIiLCJhcGlUb2tlbiI6IjdiOGE3MmUyMjJlYzk0NjUzMDgyYjNlNDI1NTJhY2UxIiwiaWF0IjoxNTg5NTMyNzc5LCJleHAiOjE1ODk2MTkxNzl9.UGpsL8-6TvHzNg3DKTgjXWbqUzCC_z8iSwyz4mfOC0o" -H "Content-Type: application/json" -d "{ \"application\": \"5ebe5918c41de60001bbd250\", \"name\": \"api_inter_placement_20200515\", \"type\": \"interstitial\", \"allowEndCards\": true, \"isSkippable\": true, \"cpmFloor\": { \"default\": 0, \"geo\": { \"additionalProp1\": 0, \"additionalProp2\": 0, \"additionalProp3\": 0 } }, \"flatCPM\": { \"default\": 20, \"geo\": { \"CN\": 18, \"US\": 19, \"JP\": 20 } }, \"isFlatCPMEnabled\": true, \"banner\": { \"adRefreshDuration\": 10, \"isRefreshEnabled\": 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",
  "banner": {
    "adRefreshDuration": 10,
    "isRefreshEnabled": true
  },
  "flatCPM": {
    "default": 22,
    "geo": {
      "CN": 21,
      "JP": 19,
      "US": 20
    }
  },
  "flatCPMCap": {
    "default": 25
  },
  "flatCPMCd": "2020-05-18T08:58:38.646Z",
  "isFlatCPMEnabled": true,
  "videoOrientationOverride": "none"
}

Step 5. Update Your Placement (and Optionally Define a Flat CPM)

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

Method: PATCH / placements/{id}

Request example URL: https://publisher-api.vungle.com/api/v1/placements/5e560daf57d130000137da76

Example value:

{
  "name": "api_inter_placement_20200515",
  "allowEndCards": true,
  "isSkippable": true,
  "_isSkippable": true,
  "videoOrientationOverride": "none",
  "status": "active",
  "banner": {
    "adRefreshDuration": 10,
    "isRefreshEnabled": true
  },
  "flatCPM": {
    "default": 22,
    "geo": {
      "CN": 19,
      "JP": 22,
      "US": 21
    }
  },
  "isFlatCPMEnabled": true
}

• Flat CPM is only available for select publisher accounts; contact your account manager to activate Flat CPM.
• 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:

curl -X PATCH "https://publisher-qa-api.vungle.io/api/v1/placements/5ebe596c5e11600001aa6452" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjVhMGIwM2RjMzM2NzUxMDAxMThiYWZhZSIsImFjY291bnQiOiI1YTBiMDNkYzMzNjc1MTAwMTE4YmFmYWQiLCJlbWFpbCI6Imhhbi5saUB2dW5nbGUuY29tIiwicGVybWlzc2lvbnMiOnsicGxhY2VtZW50cyI6eyJjcG1fZmxvb3IiOnsid3JpdGUiOmZhbHNlLCJyZWFkIjpmYWxzZX0sImZsYXRfY3BtIjp7IndyaXRlIjp0cnVlfX0sImFjY2Vzcy1ncm93LXZ1bmdsZS1jb20iOnRydWUsImFkbWluIjp7ImZsYXQtY3BtIjp0cnVlfSwiYWNjZXNzIjp7Im1pc3Npb24tY29udHJvbCI6dHJ1ZX0sImltcGVyc29uYXRlIjp0cnVlLCJnb2Rtb2RlIjp0cnVlfSwicm9sZSI6InZ1bmdsZXIiLCJhcGlUb2tlbiI6IjdiOGE3MmUyMjJlYzk0NjUzMDgyYjNlNDI1NTJhY2UxIiwiaWF0IjoxNTkxMjY0NTg4LCJleHAiOjE1OTEzNTA5ODh9.OvZWB386UUoppLwSzqpGC-oQ4aMRV1kJu6t2PGN28jc" -H "Content-Type: application/json" -d "{ \"name\": \"string\", \"allowEndCards\": true, \"isSkippable\": true, \"_isSkippable\": true, \"videoOrientationOverride\": \"none\", \"status\": \"active\", \"banner\": { \"adRefreshDuration\": 10, \"isRefreshEnabled\": true }, \"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",
  "banner": {
    "adRefreshDuration": 10,
    "isRefreshEnabled": true
  },
  "flatCPM": {
    "default": 22,
    "geo": {
      "CN": 19,
      "JP": 22,
      "US": 21
    }
  },
  "flatCPMCap": {
    "default": 25
  },
  "flatCPMCd": "2020-05-25T04:33:01.856Z",
  "isFlatCPMEnabled": 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,
  "minOs": 6,
  "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,
  "geoConfigs": {
    "additionalProp1": {
      "cpm_floor": 0,
      "flat_cpm": 0
    },
    "additionalProp2": {
      "cpm_floor": 0,
      "flat_cpm": 0
    },
    "additionalProp3": {
      "cpm_floor": 0,
      "flat_cpm": 0
    }
  },
  "isRefreshEnabled": true,
  "adRefreshDuration": 0
}

Best Practices

Read Our Documentation

Read the Vungle 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 Vungle 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
minOs:
  type: number
          
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 Vungle 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.