Publisher Management API Overview

We recently launched the Publisher Management API, a public REST API, to help you customize and manage your setup on our Publisher UI faster and with more consistency.

Overview

With the Publisher Management API, you can fetch, create, update, and delete (or archive) information on selected resources, managing your MoPub setup programmatically–in addition to managing it manually within our UI.

Resources

Supported resources include: Apps, Ad Units, Orders, Line Items, and Advanced Bidding.

About Versioning

Our URL-based versioning includes the version number in the URL. Not all resources will be on the same version, so be sure to check the Changelog provided for each resource.

The first version is v1, so the URL will look like this: https://api.mopub.com/v1/<endpoint>.

For each resource definition, we provide a changelog that includes when versions have been deprecated.

The API router automatically loads the most recent version of the appropriate view that does not exceed the specified version. If the API version ‘v2’ is specified, and there is no specified apps.py file in the /v2/ folder, the router automatically loads the v1 version. This allows us to avoid duplicating the entire API every time we need to bump the version. The most recent version is available under ‘latest’: https://api.mopub.com/latest/<endpoint>.

Example

curl -X GET \ 'https://api.mopub.com/v1/orders/' \ -H 'x-api-key: 9b1deb4d3zzzb7d4bad9bd2b0d’

Create an API Key

Each API request sent must include a valid API Key as a header. Begin by creating an API key to use for authenticating requests.

Only account administrators can generate keys. You can create up to 10 active keys. All keys provide read and write access. The time of API key creation is the only time that the API key is visible. MoPub does not store these keys; if the key is lost, we will not be able to provide it again. A new key must be generated.

Keys auto-expire after 6 months. Once a key is expired, it can no longer be used to perform any functionality on the API. A new one must be created and used for future API calls. You can delete keys from your Account Settings page prior to the 6-month expiration date. Once deleted, the key will no longer be valid.

To create an API key:

  1. In the Account Settings page of the Publisher UI. scroll down to the Publisher Management API Keys section.
  2. Click New API key.
  3. Name your API key, and click Create new API key.
  4. When your new API key displays in the dialogue box, note the key down in a safe place, because it will only be shown to you once and cannot be recovered.

Please be mindful when sharing API keys with others to ensure the security of your data and confidential information.

Handling List Responses

All “query” endpoints return a list response format that implements pagination.

{
    "data": [],
    "pagination": {
        "count": paginator.count,
        "currentPage": current_page,
        "perPage": per_page,
        "prevPage": prev_page,
        "nextPage": next_page,
        "lastPage": paginator.num_pages
    }
}

The following optional parameters are supported for all list response requests:

  • page: A cursor for use in pagination (default is ‘1’).
  • limit: A limit on the number of objects to be returned, between 1 and 100 (default is ‘50’).
  • sort: Sort the list by a field name. The list of fields varies by the type of objects being paginated (default is created_at).
  • apps: name
  • ad units: name, format
  • orders: name, advertiser
  • line items: name, priority, type
  • sortDir: The sort direction, ‘desc’ or ‘asc’ (default is desc).
  • query: This is a search term for searching multiple fields by line name, description. The list of supported fields varies depending on the object (optional). Refer to the Filters section for each object

Examples:

  • https://api.mopub.com/v2/line-items?page=3
  • https://api.mopub.com/v2/adunits?format=banner

Rate Limiting

The Publishers Management API enforces rate limiting per account. These limits help us provide the reliable and scalable API on which our developer community relies. These rate limits apply across all versions of the API.

Note that we enforce an over rate limit of 1000 requests per minute across all resources. For the Line Item resource, we enforce a rate limit of 5 requests per second.

Description Method Path Window Request Quota
All GET requests GET Any path starting with /{version} 60s 1080
All POST requests POST Any path starting with /{version} 60s 1080
All PUT requests PUT Any path starting with /{version} 60s 1080
All DELETE requests DELETE Any path starting /{version} 60s 1080
Line items bulk fetch per second GET /{version}/line-items 1s 5
Line items bulk update per minute PUT /{version}/line-items 60s 60
Creatives image upload per 5 seconds POST /{version}/creatives/image_upload 5s 5
Data GET requests GET Any path starting with /{version}/data 60s 10
Data POST requests POST Any path starting with /{version}/data 60s 5

Best Practices

  • Take advantage of the bulk update feature for the line item endpoints. This can reduce the overall number of calls you make and thus leverage rate limit more efficiently.

  • Request maximum “limit” in your requests: A limit on the number of objects to be returned, between 1 and 500 (default is 200).

Error and Validation Responses

The API will respond with the following HTTP response codes:

Unauthorized Response

{
  "statusCode": 401,
  "type": "UNAUTHORIZED",
  "errors": [{
    "message": "Invalid API key"
  }]
}

Forbidden Response

{
  "statusCode": 403,
  "type": "FORBIDDEN",
  "errors": [{
    "message": "The API key doesn't have permissions to perform the request."
  }]
}

Validation Error

{
  "statusCode": "400",
  "type": "VALIDATION_ERROR",
  "errors": [{
    "field": "name",
    "message": "Invalid name length."
  }]
}

Validation Error Without Specific Field

{
  "statusCode": "400",
  "type": "VALIDATION_ERROR",
  "errors": [{
    "message": "Missing or required parameters."
  }]
}

Object Not Found

{
  "statusCode": "404",
  "type": "OBJECT_NOT_FOUND",
  "errors": [{
    "message": "The order does not exist."
  }]
}

Invalid URL

{
  "statusCode": "404",
  "type": "ROUTE_NOT_FOUND",
  "errors": [{
    "message": "The provided URL does not exist."
  }]
}

Rate Limit Reached

{
  "statusCode": "429",
  "type": "TOO_MANY_REQUESTS",
  "errors": [{
    "message": "Too many requests."
  }]
}

Internal Server Error

{
  "statusCode": "500",
  "type": "INTERNAL_ERROR",
  "errors": [{
    "message": "Something went wrong with the request."
  }]
}

Versioning

Changelog

Version Path Introduction date Deprecated date End of life date
2 /v2/ May 10, 2021    
1 /v1/ Feburary 2, 2021 May 10, 2021 August 31, 2021

Small improvements (9/14/2021)

  • Default page size is now 200
  • Limit increased to 500

Open Beta V2 (7/28/2021) Updates: No Breaking Changes

To join the open beta, please contact your account team.

  • Creatives resource - new
    • New resource to manage direct serve creative
  • Line Item resource - update
    • Added support for gtee, promo, non_gtee, backfill_promo line item types.
  • App resource - update
    • Added support for automatic creative of applications using a Google Play Store or Apple Store URL.

V2

MoPub release of App Level Marketplace Content Blocking requires the following changes:

  • Line Item resource - fields removed
    • removal of fields: appBlocklist, categoryBlocklist, attributeBlocklist
    • added support for device ID targeting (IDFA targeting)
  • App resource - fields added
    • new fields appLevelContentBlockingEnabled, overrideAccountLevelContentBlocks
  • Content Blocking resource - new
    • New resource to manage Marketplace Content Blocking

Last updated September 14, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)