--- title: REST API MGID for Publishers description:   REST API allows you to integrate external applications with Mgid online   advertising system. API provides the ability to retrieve, add, and modify the data. Practically each  object in Mgid (whethe --- [Skip to content](https://help.mgid.com/api-publishers#main-content) English Show submenu for translations ![MGID\_Logo\_Help\_Center\_W\_R\_Swoosh.svg\]](https://help.mgid.com/hubfs/MGID_Logo_Help_Center_W_R_Swoosh.svg) - [Advertisers](https://www.mgid.com/advertisers) - [Publishers](https://www.mgid.com/publishers) - [Contact Us](https://www.mgid.com/about#tabs-contactus) Open main navigation Close main navigation - [Advertisers](https://www.mgid.com/advertisers) - [Publishers](https://www.mgid.com/publishers) - [Contact Us](https://www.mgid.com/about#tabs-contactus) - English Show submenu for translations - Contact us Contact us Welcome to MGID! How can we help you? - There are no suggestions because the search field is empty. 1. [Help Center Home](https://help.mgid.com/?hsLang=en) 2. [API](https://help.mgid.com/api?hsLang=en) # REST API MGID for Publishers ###### Please note that all API requests must be performed **via HTTPS** *Table of contents:* 1. [The main provisions of REST API](https://help.mgid.com/api-publishers#toc1) 2. [Identification](https://help.mgid.com/api-publishers#toc2) 3. [Mgid REST API answer](https://help.mgid.com/api-publishers#toc3) 4. [Working with widgets](https://help.mgid.com/api-publishers#toc5) 1. [Custom reports](https://help.mgid.com/api-publishers#toc6-2) 5. [Website Custom Report](https://help.mgid.com/api-publishers#toc7)   ### The main provisions of REST API REST API allows you to integrate external applications with Mgid online   advertising system. API provides the ability to retrieve, add, and modify the data. Practically each  object in Mgid (whether it's a client, an advertising company, a teaser, etc.) can  be controlled by API. Mgid REST API Request is an HTTP request, which, with  the help of the ways in URL the object to perform the action is specified, and  with the help of parameters the necessary data is passed. Mgid API is a "RESTful  Web API". The API uses the following REST commands: - GET - PUT - PATCH - POST - DELETE The query parameters are case sensitive. These commands correspond to certain actions within the Mgid system. Get an item or a collection of items (for example, a list of advertising campaigns):     | **Command** | **Action** | **Description** | | --- | --- | --- | | **POST** | Create | Creates a new element (eg, a teaser) | | **GET** | Get (read) | Retrieve an element or a collection of elements | | **PUT** | Update | Recreate an existing element or a collection of elements | | **PATCH** | Change | Change certain properties of an element | | **DELETE** | Delete | Delete an item or collection of items (eg, move a teaser to recycle bin) | | **Important!** POST and PUT are not interchangeable. Each of the commands fulfills its specific function. | | | **In general, the query looks like this:** *https://api.mgid.com/v1/module/controller/action?parameter\_1=value\_of\_parameter\_1¶meter\_2=value\_of\_parameter\_2¶meter\_3=value\_of\_parameter\_3*   ### Identification For identification the Mgid REST API uses a unique token consisting of 32 characters which is passed in client’s request Authorization header. To obtain a valid token client should use a special API function. | Every request sent to the Mgid REST API must contain the API token | | --- |   ### MGID REST API Answer In response to a request to the REST API server always returns the HTTP response with a status code , depending on the result of the query. | **Answer code** | **Description** | | --- | --- | | 200 OK | The query has been successfully processed | | 400 Bad Request | Syntax error | | 404 Not Found | Item or page not found | ### Format of the returned data The returned data can be formatted as JSON, or XML.  The default format is JSON. The request header is used to specify the format in which the data is   returned. The client sends an Accept header, which indicates desired response format:   *Accept: application / xml*   or   *Accept: application / json* A description of the response format is sent in the response header Content Type. The data returned is the answer is a JSON string, which generally looks as follows:   ``` {    "element_1":"value_of_element_1",        "element_2":"value_of_element_2",     "element_3":{         "property_1_of_element_3":"value_of_property_1_of_element_3",                "property_2_of_element_3":[               "value_1_of_property_2_of_element_3",               "value_2_of_property_2_of_element_3"         ]            }      . . . .  } ``` If an error has occurred during the execution of the query   the description corresponding to the error is returned, such as: ``` { "errors": [ "[_error_description_]" ] } ```   ### Working with widgets #### ***Custom reports*** | **Method** | GET | | --- | --- | | **URL** | *api.mgid.com/v1/publishers/{authId}/widget-custom-report* | | **Header** | Accept: application/json Authorization: Bearer {token} | Transfered parameters (required parameters are marked with asterisk \*): | **Parameter** | **Value** | | --- | --- | | dateInterval\* | Interval of time you need to get a statistics. Valid values: - interval - if selected, must be specified startDate/endDate in format yyyy-mm-dd - all - thisWeek - starting from Monday - lastWeek - starting from Monday - thisMonth - lastMonth - lastSeven - today - yesterday - last30Days In addition, you can transfer the hour intervals: - startHour - start hour 0-23 - endHour - end hour 0-23 | | siteId | Client's site ID - If presented stats will be provided for particular website. - If not presented - stats will be provided for the whole account (considering the dimensions) | | dimensions\* | list of fields to group. It can take multiple values separated by a comma. Valid values are: - date - widgetId - deviceType - subId - countryIso - widgetName - domain - trafficType - trafficSource | | metrics\* | list of fields for extracting indicators. It can take multiple values separated by a comma. Valid values are: - shows \[deprecated\] - realShows \[deprecated\] - pageViews \[deprecated\] - adRequests - impressions - visibilityRate - clicks - wages - cpm - vCpm \[deprecated\] - eCpm - cpc - ctr - videoImpressions - orgClicks - orgCTR - orgvCTR | | page | page number with statistics | | perPage | records number per page. Default 1000, maximum 100 000, minimum 1 | | widgetId | composite widget ID | | deviceType | device type (desktop, tablet, mobile) | | countryIso | country code (alpha2) | | sortBy | sort by field (can take one of the transmitted values dimensions or metrics), if not passed, sorts by the first parameter from dimensions | | sortMethod | direction of sorting (asc, desc), if not sent then applied ASC direction | | timeZone | Timeshift of statistics. Available list of timeZones [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) ( TZ ). If the parameter not passed timeZone will be set to America/Los\_Angeles | ### Website Custom Report Retrieve statistics aggregated at the **website level**. Use this endpoint when you need website-scoped metrics — including pageviews — instead of per-widget breakdowns. | **Method** | GET | | --- | --- | | **URL** | https://api.mgid.com/v2/pub/account/{clientId}/website-custom-report | | **Header** | Accept-Language: en Authorization: Bearer {token} Content-Type: application/json | **Required Parameters** | **Parameter** | **Type** | **Description** | | --- | --- | --- | | dateInterval | string | Time period for the report. *See [Date interval values](https://help.mgid.com/api-publishers#toc7-1) below.* | | dimensions | string | Comma-separated list of fields to group results by. Accepts multiple values. *See [Dimensions](https://help.mgid.com/api-publishers#toc7-2) below.* | | metrics | string | Comma-separated list of metric fields to return. Accepts multiple values. *See [Metrics](https://help.mgid.com/api-publishers#toc7-3) below.* | **Optional Parameters** | **Parameter** | **Type** | **Description** | | --- | --- | --- | | website | string | Filter results to one or more websites. Accepts comma-separated domain names (e.g., example.com,other.com). Omit returning account-wide data. | | startHour | integer | Start the hour filter (0–23). Use with endHour to narrow results to a time window within each day. | | endHour | integer | End hour filter (0–23). | | limit | integer | Records per page. Default: 1000. Min: 1. Max: 100000. | | offset | integer | Pagination offset (number of records to skip). Default: 0. | | orders\\\[{field}\\\] | string | Sort results by any dimension or metric. Replace {field} with the field name. Value: asc or desc. Example: orders\\\[revenue\\\]=desc. | | timeZone | string | TZ database timezone identifier (e.g., America/New\_York). Default: America/Los\_Angeles. | **Date Interval Values** Available presets: - today - yesterday - thisWeek - lastWeek - thisMonth - lastMonth - lastSeven - last30Days - last90Days For a custom range, use interval with startDate and endDate in yyyy-mm-dd format. **Dimensions** | **Value** | **Description** | | --- | --- | | date | Groups results by day | | website | Groups results by website domain | | countryIso | Groups results by two-letter ISO country code | | deviceType | Groups results by device type (desktop, tablet, mobile) | | OS | Groups results by operating system | | trafficType | Groups results by traffic type | | trafficSource | Groups results by traffic source | **Metrics** | **Value** | **Description** | | --- | --- | | pageViews | Total number of page views | | viewWithVisibility | Impressions with viewability measured | | visibilityRate | Percentage of visible impressions | | revenue | Total publisher revenue | | adCTR | Ad click-through rate | | advCTR | Advertiser click-through rate | | adCPC | Ad cost per click | | adCPM | Ad cost per thousand impressions | | advCPM | Advertiser CPM | | orgClicks | Organic clicks | | orgCTR | Organic click-through rate | | orgvCTR | Organic viewable click-through rate | **Example Request** ``` curl -X GET \"https://api.mgid.com/v2/pub/account/{clientId}/website-custom-report?dateInterval=last30Days&dimensions=date,website&metrics=pageViews,revenue&website=example.com&orders[revenue]=desc&limit=100" \-H "Accept-Language: en" \-H "Authorization: Bearer {token}" \-H "Content-Type: application/json" ``` **Example Response** ``` [{"date": "2025-04-01","website": "example.com","pageViews": 124500,"revenue": 42.15},{"date": "2025-04-02","website": "example.com","pageViews": 131200,"revenue": 47.80}] ``` **Error Response** ``` {"errors": ["[error_description]"]} ``` **Common error codes:** - 422 Unprocessable Entity — Missing or invalid required parameters. The response body includes a descriptive error message. - 401 Unauthorized — Missing or invalid authorization token.   - [Advertisers](https://help.mgid.com/advertisers?hsLang=en#main-content) - [Get started with MGID Ads](https://help.mgid.com/advertisers?hsLang=en#get-started-with-mgid-ads) - [Campaign Setup & Management](https://help.mgid.com/advertisers?hsLang=en#campaign-setup-management) - [CPA Tune](https://help.mgid.com/advertisers?hsLang=en#cpa-tune) - [Conversion tracking: general](https://help.mgid.com/advertisers?hsLang=en#conversion-tracking-general) - [Tracking with MGID Pixel](https://help.mgid.com/advertisers?hsLang=en#tracking-with-mgid-pixel) - [Postback & Trackers](https://help.mgid.com/advertisers?hsLang=en#postback-trackers) - [Affiliate Networks Integration](https://help.mgid.com/advertisers?hsLang=en#affiliate-networks-integration) - [Webhook tracking method & Integrations](https://help.mgid.com/advertisers?hsLang=en#webhook-tracking-method-integrations) - [Native integrations](https://help.mgid.com/advertisers?hsLang=en#native-integrations) - [Ad Creatives Management](https://help.mgid.com/advertisers?hsLang=en#ad-creatives-management) - [Campaign Optimization & Performance](https://help.mgid.com/advertisers?hsLang=en#campaign-optimization-performance) - [FAQ](https://help.mgid.com/advertisers?hsLang=en#faq) - [MGID Video Guides](https://help.mgid.com/advertisers?hsLang=en#mgid-video-guides) - [Publishers](https://help.mgid.com/publishers?hsLang=en#main-content) - [General](https://help.mgid.com/publishers?hsLang=en#general) - [Prohibited content and practices](https://help.mgid.com/publishers?hsLang=en#prohibited-content-and-practices) - [Types of integration](https://help.mgid.com/publishers?hsLang=en#types-of-integration) - [Compliance](https://help.mgid.com/publishers?hsLang=en#compliance) - [Payment](https://help.mgid.com/publishers?hsLang=en#payment) - [FAQ](https://help.mgid.com/publishers?hsLang=en#faq) - [Ad Quality Policies and Creative Guidelines](https://help.mgid.com/ad-quality-policies-and-creative-guidelines?hsLang=en#main-content) - [Ad Approval & Compliance Guidelines](https://help.mgid.com/ad-quality-policies-and-creative-guidelines?hsLang=en#ad-approval-compliance-guidelines) - [Creative AI Hub](https://help.mgid.com/ad-quality-policies-and-creative-guidelines?hsLang=en#creative-ai-hub) - [Creative Hub](https://help.mgid.com/ad-quality-policies-and-creative-guidelines?hsLang=en#creative-hub) - [Compliance & Security](https://help.mgid.com/ad-quality-policies-and-creative-guidelines?hsLang=en#compliance-security) - [Advertisers Super Client Account](https://help.mgid.com/advertisers-super-client-account?hsLang=en#main-content) - [Clients](https://help.mgid.com/advertisers-super-client-account?hsLang=en#clients) - [Fraud Prevention](https://help.mgid.com/fraud-prevention?hsLang=en#main-content) - [Fraud Prevention](https://help.mgid.com/fraud-prevention?hsLang=en#fraud-prevention) - [API](https://help.mgid.com/api?hsLang=en) - [DSP](https://help.mgid.com/dsp?hsLang=en) - [SSP](https://help.mgid.com/ssp?hsLang=en) - [Advertisers](https://www.mgid.com/advertisers) - [Publishers](https://www.mgid.com/publishers) - [Contact Us](https://www.mgid.com/about#tabs-contactus) [![Chill listening crop-3](https://help.mgid.com/hubfs/MGID_Logo_Icon_HC.svg "Chill listening crop-3")](https://www.mgid.com) Native performance through innovation Copyright © 2026, MGID Inc.