Help Center Home

REST API MGID for publishers

* Please note that all API requests must be performed via HTTPS.

The main provisions of REST API
Identification
Mgid REST API answer
Working with clients
1. Getting the current client's token
Working with widgets
1. Custom reports

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&parameter_2=value_of_parameter_2&parameter_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 clients

Getting the current client's token

Method	URL
POST	api.mgid.com/v1/auth/token

Transferred parameters:

Parameter	Value
email	E-mail of the client, specified at registration in Mgid system
password	The password of the client received during registration in Mgid system

Returns an answer:

{
"token":"_current_token_",
"refreshToken":"_token_for_refresh_"
"idAuth":"_client_api_id_"
}

_current_token_ is used to identify the client;
_token_for_refresh_ will be used in future versions to update an overdue current token.

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 lastWeek 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
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
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
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 ( TZ ). If the parameter not passed timeZone will be set to America/Los_Angeles