Information

Title	EMP API

URL Name	Manage-API

Details

Article Body

Overview

With the EMP API, you can automate operations on Equativ's Monetization Platform: handling of sites and pages, campaigns, insertions, advertisers etc.

API Documentation

Click here to access the EMP API documentation.

Authentication

For information about how to authenticate, refer to the API authentication article.

Base URL

The Base URL for the API is:

https://supply-api.eqtv.io

API limits

To prevent API performance issues by intended or accidental large scale operations, the API is subject to limits.

Limits per UTC day

Limits apply to the UTC day, not to the last 24 hours.
For instance, if you are doing an API call in France (UTC+2, summer time) at 01:00 AM on a Tuesday, the call will be counted for the Monday before, at 11:00 PM.

Action	Limit per UTC day
READ (ID: 1)	20000
WRITE (ID: 2)	2000
PUT ONLINE (ID: 4)	2000

Note that the limits above apply to the EMP API, Forecast API and RTB API globally.

EMP API limits

Action	Limit
Create pages	1000 (within last 10 minutes)
Create pages: total number of pages in the network (account at Equativ)	50000
Asynchronous requests to put online insertions (InsertionOnliningRequests) / Asynchronous requests to put offline insertions (InsertionOffliningRequests): time of storage of these requests after their completion (requests are removed after this time and become inaccessible through a GET request or the GUID)	12 hours

Pagination of responses

API responses are paginated with each page holding a maximum of 100 items. The pagination information is sent in the response headers.

The response header X-Pagination-Total-Count contains the total amount of items matching your request. If this total exceeds 100, the response headers will also contain information to retrieve the next page and the previous pages.

The "Link" response header contains the link to the next page: <NextPageUrl>; rel="next"

To retrieve the next page’s results, make the same request again (using the same headers and body), but replace the called url with the value of <NextPageUrl>.

If a page has a previous page, the "Link" response header contains the link to the previous page: <PreviousPageUrl>; rel="prev"

If a page has both a previous and a next page, the "Link" response header contains both links, separated by a comma (,).

To customize the page size (max. number of items per page), add the "limit" parameter in the called URL. The value must not exceed 100.

Example for a request with a page size of 10 items:

https://supply-api.eqtv.io/insertions/?offset=10&limit=10

Example response headers:

X-Pagination-Total-Count: 89
Link: <https://supply-api.eqtv.io/insertions/?offset=20&limit=10>; rel="next", <https://supply-api.eqtv.io/insertions/?offset=0&limit=10>; rel="prev"

Note: Calls which always return a single item are not concerned.

Data types

The following tables list the data types available in filters and in the body.

Data types in filters

Data type	Description	Example
IntList	list of integers	12,45,9484
OptionalBool	optional boolean	possible values: "True", "False", "Both"
Int32	integer; maximum value: 2147483647	1147483647
String	simple string	"this is a sample string"
StringList	list of strings	"DZA,AGO"
BigIntList	list of big integers; maximum value: 2^63-1
Boolean	simple boolean	possible values: "True" or "False"

Data types in the body

Data type	Description	Example
IntList	list of integers	"siteIds": [1411,1412]
OptionalBool	optional boolean	possible values: "True", "False", "Both"
Int32	integer; maximum value: 2147483647	"insertionId": 1000099233
String	simple string	"name": "example name"
StringList	list of strings	"insertionNames": ["example name 1","example name 2"]
BigIntList	list of big integers; maximum value: 2^63-1	"insertionId": 1000099233
Date	date	"startDate": "2016-09-06T00:00:00+02:00"

Get all insertions

Returns all the insertions.

Endpoint

GET  https://supply-api.eqtv.io/insertions

Parameters

Name	Type	Mandatory	Description
Id	IntList	no	filters the insertions having the specified Ids; use comma to separate ids
name	string	no	filters the insertions having an insertion name which contains the specified string
nameBeginsWith	string	no	filters the insertions where the insertion name begins with the specified string
isArchived	OptionalBool	no	possible values: "False", or "Both" (to get even unusable insertions); "False" by default
insertionStatusIds	IntList	no	filters the insertions having the specified status Ids (see "insertionstatus" resource)
campaignIds	IntList	no	filters the insertions which belong to the specified campaignIds
salesChannelIds	IntList	no	filters the results having the specified channel ids (PMP, Direct, ...)

Example request

GET https://supply-api.eqtv.io/insertions?ids=6330048,6109308

Example response

[
    {
        "isDeliveryRegulated": true,
        "id": 6330048,
        "name": "API insertion",
        "insertionStatusId": 0,
        "startDate": "2017-06-23T00:00:00+02:00",
        "endDate": "2017-06-26T00:00:00+02:00",
        "campaignId": 1114707,
        "insertionTypeId": 0,
        "deliveryTypeId": 0,
        "timezoneId": 1,
        "priorityId": 62,
        "periodicCappingId": 0,
        "maxImpressions": 0,
        "weight": 0,
        "maxClicks": 0,
        "maxImpressionsPerDay": 0,
        "maxClicksPerDay": 0,
        "voiceShare": 0,
        "eventId": 0,
        "eventImpressions": 0,
        "isHolisticYieldEnabled": false,
        "deliverLeftVolumeAfterEndDate": false,
        "globalCapping": 0,
        "cappingPerVisit": 0,
        "cappingPerClick": 0,
        "autoCapping": 0,
        "periodicCappingImpressions": 0,
        "periodicCappingPeriod": 0,
        "formatId": 0,
        "externalId": 0,
        "externalDescription": "",
        "description": "",
        "updatedAt": "2017-01-12T10:15:00",
        "createdAt": "2017-01-03T16:57:00",
        "isArchived": false,
        "rateTypeId": 0,
        "rate": 0,
        "rateNet": 0,
        "discount": 0,
        "currencyId": 13,
        "insertionExclusionIds": [
            78980
        ]
    },
    {
        "isDeliveryRegulated": false,
        "id": 6109308,
        "name": "Insertion",
        "insertionStatusId": 4,
        "startDate": "2016-12-07T00:00:00+01:00",
        "endDate": "2016-12-18T23:59:00+01:00",
        "campaignId": 1114707,
        "insertionTypeId": 0,
        "deliveryTypeId": 0,
        "timezoneId": 71,
        "priorityId": 104,
        "periodicCappingId": 0,
        "maxImpressions": 0,
        "weight": 0,
        "maxClicks": 0,
        "maxImpressionsPerDay": 0,
        "maxClicksPerDay": 0,
        "voiceShare": 0,
        "eventId": 0,
        "eventImpressions": 0,
        "isHolisticYieldEnabled": false,
        "deliverLeftVolumeAfterEndDate": false,
        "globalCapping": 0,
        "cappingPerVisit": 0,
        "cappingPerClick": 0,
        "autoCapping": 0,
        "periodicCappingImpressions": 0,
        "periodicCappingPeriod": 0,
        "formatId": 9689,
        "siteIds": [
            20697
        ],
        "externalId": 0,
        "externalDescription": "",
        "description": "",
        "updatedAt": "2016-12-19T02:23:00",
        "createdAt": "2016-11-08T10:01:00",
        "isArchived": false,
        "rateTypeId": 0,
        "rate": 0,
        "rateNet": 0,
        "discount": 0,
        "currencyId": 13
    }
]

Get specific insertion

Returns a specific insertion.

Endpoint

GET https://supply-api.eqtv.io/insertions/{id}

Note: Replace <networkId> by the Id of your network.

Parameters

Name	Type	Mandatory	Description
{id}	Int32	yes	unique ID of the insertion to be retrieved

Example request

GET https://supply-api.eqtv.io/insertions/6109254

Example response

{
    "isDeliveryRegulated": false,
    "id": 6109254,
    "name": "Kopie von RTB+",
    "insertionStatusId": 0,
    "startDate": "2016-10-11T00:00:00+02:00",
    "endDate": "2017-10-31T23:59:00+01:00",
    "campaignId": 1114707,
    "insertionTypeId": 0,
    "deliveryTypeId": 0,
    "timezoneId": 71,
    "priorityId": 62,
    "periodicCappingId": 0,
    "maxImpressions": 10000,
    "weight": 0,
    "maxClicks": 0,
    "maxImpressionsPerDay": 0,
    "maxClicksPerDay": 0,
    "voiceShare": 0,
    "eventId": 0,
    "eventImpressions": 0,
    "isHolisticYieldEnabled": true,
    "deliverLeftVolumeAfterEndDate": false,
    "globalCapping": 0,
    "cappingPerVisit": 0,
    "cappingPerClick": 0,
    "autoCapping": 0,
    "periodicCappingImpressions": 0,
    "periodicCappingPeriod": 0,
    "formatId": 11999,
    "siteIds": [
        20697
    ],
    "externalId": 0,
    "externalDescription": "",
    "description": "",
    "updatedAt": "2017-01-12T10:15:00",
    "createdAt": "2016-11-08T09:53:00",
    "isArchived": false,
    "rateTypeId": 0,
    "rate": 0,
    "rateNet": 0,
    "discount": 0,
    "currencyId": 13,
    "insertionExclusionIds": [
        78980,
        78983
    ]
}

Get details on property of insertion

Returns details on a property of the insertion with the given id.

Endpoint

GET https://supply-api.eqtv.io/insertions/{id}/{subAction}

Note: Replace <networkId> by the Id of your network.

Parameters

Name	Type	Mandatory	Description
{id}	Int32	yes	insertion Id
{subAction}	String	yes	allowed sub-actions: "creatives" returns the list of creatives associated with the current insertion; the returned objects have only common properties to all types of creatives "insertionTargetings" returns the targeting of the current insertion "insertionTemplates" returns the template information of the current insertion
ids	IntList	no	filters results according to the specified ids
creativeTypeIds	IntList	no	filters results according to the specified creative type ids
name	String	no	filters creatives where the creative name contains the specified string
nameBeginsWith	String	no	filters results where the creative name starts with the specified string
isArchived	OptionalBool	no	state to check if the item can be used (not deprecated, not removed etc.)

Example request

GET https://supply-api.eqtv.io/insertions/6330048/insertionTargetings

Example response

{
    "insertionId": 6330048,
    "isExactMatch": true,
    "targetBrowserWithCookies": false,
    "browserIds": [
        16
    ]
}

Create new insertion

Creates a new insertion.

Endpoint

POST https://supply-api.eqtv.io/insertions

Note: Replace <networkId> by the Id of your network.

Parameters

Name	Type	Mandatory	Description
id	Int32	no	insertion Id; is ignored if passed
name	String	yes	insertion name; maximum length: 1 to 250 characters
insertionStatusId	Int32	no	insertion status; default: "0" (offline); see "insertionstatus" resource
startDate	Date	yes	insertion start date
endDate	Date	yes	insertion end date
campaignId	Int32	yes	insertion's campaignId
insertionTypeId	Int32	yes	insertion typeId; default is "0“, see "insertiontypes" resource
deliveryTypeId	Int32	yes	insertion deliveryTypeId: "Web", "Mobile", etc.; see "deliverytypes“ resource
timezoneId	Int32	yes	insertion timezoneId
priorityId	Int32	no	insertion priorityId; see "insertionpriorities“ resource
periodicCappingId	Int32	no	insertion PeriodicCappingId
maxImpressions	Int32	no	insertion maximum impressions (volume)
weight	Int32	no	insertion weight (weight is assigned through comparison of insertions with equal priority); between 0 and 100
maxClicks	Int32	no	insertion maximum clicks (volume)
maxImpressionsPerDay	Int32	no	maximum impressions delivered by the insertion per day
maxClicksPerDay	Int32	no	maximum clicks delivered by the insertion per day
insertionGroupedVolumeId	Int32	no	insertion groupedVolume Id (read-only)
voiceShare	Int32	no	percentage of volume to be delivered on the selected placement, compared to the other insertions running on this placement
eventId	Int32	no	insertion eventId (volume)
eventImpressions	Int32	no	insertion bookedEvents (volume)
isHolisticYieldEnabled	Bool	no	"True" if holistic yield is enabled in the insertion
deliverLeftVolumeAfterEndDate	Bool	no	"True" to make the insertion continue delivery after its end date, even if it has not delivered its complete volume
globalCapping	Int32	no	insertion global capping
cappingPerVisit	Int32	no	insertion capping by visit
cappingPerClick	Int32	no	deprecated; insertion capping of clicks
autoCapping	Int32	no	deprecated; offers the advantages of the global capping (increasing the click rates), combined with automatic deactivation when the insertion is late
periodicCappingImpressions	Int32	no	insertion impressions for periodic capping
periodicCappingPeriod	Int32	no	insertion period for periodic capping (in minutes)
formatId	Int32	no	format Id of the insertion
siteIds	IntList	no	list of site ids linked to the insertion
pageIds	IntList	no	list of page ids linked to the insertion
packIds	IntList	no	list of pack ids linked to the insertion
externalId	Int32	no	external Id (any Int32; used to cross-reference with an external tool)
externalDescription	String	no	description of the external description passed; maximum length: 50 characters
description	String	no	description of the insertion; maximum length: 3000 characters
updatedAt	Date	no	the insertion's last modification date; is ignored if passed
createdAt	Date	no	the insertion's creation date; is ignored if passed
isArchived	Bool	no	"False" if you can update the insertion; "True" otherwise; is ignored if passed
rateTypeId	Int32	no	type of the rate (CPM, CPC...)
rate	Double	no	value of the rate
rateNet	Double	no	value of the rate (net value); this value is calculated
discount	Double	no	percentage of discount
currencyId	Int32	no	cost's currency
insertionLinkId	Int32	no	if existing, the link between this insertion and other insertion(s); this property is ReadOnly; to create or update an insertion link see "InsertionLinks" resource
insertionExclusionIds	IntList	no	if existing, the list of insertion exclusion ids; this property is read only; to create or update an insertion exclusion see "InsertionExclusions" resource

Example request

{
    "id": "",
    "name": "test",
    "insertionStatusId": "",
    "startDate": "2017-06-23",
    "endDate": "2017-06-29",
    "campaignId": "1114707",
    "insertionTypeId": "",
    "deliveryTypeId": "0",
    "timezoneId": "71",
    "priorityId": "",
    "periodicCappingId": "",
    "maxImpressions": "",
    "weight": "",
    "maxClicks": "",
    "maxImpressionsPerDay": "",
    "maxClicksPerDay": "",
    "insertionGroupedVolumeId": "",
    "voiceShare": "",
    "eventId": "",
    "eventImpressions": "",
    "isHolisticYieldEnabled": "",
    "deliverLeftVolumeAfterEndDate": "",
    "globalCapping": "",
    "cappingPerVisit": "",
    "cappingPerClick": "",
    "autoCapping": "",
    "periodicCappingImpressions": "",
    "periodicCappingPeriod": "",
    "formatId": "",
    "siteIds": "",
    "pageIds": "",
    "packIds": "",
    "externalId": "",
    "externalDescription": "",
    "description": "",
    "updatedAt": "",
    "createdAt": "",
    "isArchived": "",
    "rateTypeId": "",
    "rate": "",
    "rateNet": "",
    "discount": "",
    "currencyId": "",
    "insertionLinkId": "",
    "insertionExclusionIds": ""
}

Example response

empty

Create new creative related to current insertion

Creates a new creative related to the current insertion.

Endpoint

POST https://supply-api.eqtv.io/insertions/{id}/{subAction}

Note: Replace <networkId> by the Id of your network.

Parameters

Name	Type	Mandatory	Description
{id}	Int32	yes	insertion Id
{subAction}	String	yes	allowed sub-action: "creatives" to add a new creative to the current insertion
file	FileAndClickUrl	yes	FileAndClickUrl is a custom model, containing: 'fileName' - the file name with its extension 'fileContent' - the file to upload, converted to a base64 string 'clickUrl' - an optional click URL The FileAndClickUrl must be passed in the request's body.

Update insertion

Updates an existing insertion.

Endpoint

PUT https://supply-api.eqtv.io/insertions

Note: Replace <networkId> by the Id of your network.

Parameters

Name	Type	Mandatory	Description
id	Int32	no	insertion Id;
name	String	yes	insertion name; maximum length: 1 to 250 characters
insertionStatusId	Int32	no	insertion status; default: "0" (offline); see "insertionstatus" resource
startDate	Date	yes	insertion start date
endDate	Date	yes	insertion end date
campaignId	Int32	yes	insertion's campaign Id
insertionTypeId	Int32	yes	insertion typeId; default is "0“, see "insertiontypes" resource
deliveryTypeId	Int32	yes	insertion deliveryTypeId: "Web", "Mobile", etc.; see "deliverytypes“ resource
timezoneId	Int32	yes	insertion timezoneId
priorityId	Int32	no	insertion priorityId; see "insertionpriorities“ resource
periodicCappingId	Int32	no	insertion periodic capping Id
maxImpressions	Int32	no	insertion maximum impressions (volume)
weight	Int32	no	insertion weight (weight is assigned through comparison of insertions with equal priority); between 0 and 100
maxClicks	Int32	no	insertion maximum clicks (volume)
maxImpressionsPerDay	Int32	no	maximum impressions delivered by the insertion per day
maxClicksPerDay	Int32	no	maximum clicks delivered by the insertion per day
insertionGroupedVolumeId	Int32	no	insertion groupedVolume Id (read-only)
voiceShare	Int32	no	percentage of volume to be delivered on the selected placement, compared to the other insertions running on this placement
eventId	Int32	no	Insertion eventId (volume)
eventImpressions	Int32	no	Insertion bookedEvents (volume)
isHolisticYieldEnabled	Bool	no	"True" if holistic yield is enabled in the insertion
deliverLeftVolumeAfterEndDate	Bool	no	"True" to make the insertion continue delivery after its end date, even if it has not delivered its complete volume
globalCapping	Int32	no	insertion global capping
cappingPerVisit	Int32	no	insertion capping by visit
cappingPerClick	Int32	no	deprecated; insertion capping for clicks
autoCapping	Int32	no	deprecated; offers the advantages of the global capping (increasing the click rates), combined with automatic deactivation when the insertion is late
periodicCappingImpressions	Int32	no	insertion impressions for periodic capping
periodicCappingPeriod	Int32	no	insertion period for periodic capping (in minutes)
formatId	Int32	no	format Id of the insertion
siteIds	IntList	no	list of site ids linked to the insertion
pageIds	IntList	no	list of page ids linked to the insertion
packIds	IntList	no	list of pack ids linked to the insertion
externalId	Int32	no	external Id (any Int32; used to cross-reference with an external tool)
externalDescription	String	no	description of the external description passed; maximum length: 50 characters
description	String	no	description of the insertion; maximum length: 3000 characters
updatedAt	Date	no	the insertion's last modification date; is ignored if passed
createdAt	Date	no	the insertion's creation date; is ignored if passed
isArchived	Bool	no	"False" if you can update the insertion; "True" otherwise
rateTypeId	Int32	no	type of the rate (CPM, CPC...)
rate	Double	no	value of the rate
rateNet	Double	no	value of the rate (net value); this value is calculated
discount	Double	no	percentage of discount
currencyId	Int32	no	cost's currency
insertionLinkId	Int32	no	if existing, the link between this insertion and other insertion(s); this property is read only; to create or update an insertion link see "InsertionLinks" resource
insertionExclusionIds	IntList	no	if existing, the list of insertion exclusion ids; this property is read only; to create or update an insertion exclusion see "InsertionExclusions" resource

Example response

empty (code 200 OK)

Notes