Contact support
    • Monetization
    • Developer documentation
    • Automate monetization

    Automate trafficking (API)

    Table of Contents

    Overview API Documentation Authentication Base URL API limits Limits per UTC day EMP API limits Pagination of responses Data types Data types in filters Data types in the body Get all insertions Endpoint Parameters Example request Example response Get specific insertion Endpoint Parameters Example request Example response Get details on property of insertion Endpoint Parameters Example request Example response Create new insertion Endpoint Parameters Example request Example response Create new creative related to current insertion Endpoint Parameters Update insertion Endpoint Parameters Example response

    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
    PUT ONLINE (ID: 4) 2000
    READ (ID: 1) 20000
    WRITE  (ID: 2) 2000

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

    EMP API limits

    Action Limit
    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 
    Create pages 1000 (within last 10 minutes)
    Create pages: total number of pages in the network (account at Equativ) 50000

     

    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"

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

     

    Data types in the body

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

    Get all insertions

    Returns all the insertions.

    Endpoint

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

    Parameters

    Name Type Mandatory Description
    campaignIds IntList no filters the insertions which belong to the specified campaignIds
    Id IntList no filters the insertions having the specified Ids; use comma to separate ids
    insertionStatusIds IntList no filters the insertions having the specified status Ids (see "insertionstatus" resource)
    isArchived OptionalBool no possible values: "False", or "Both" (to get even unusable insertions); "False" by default
    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
    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}

    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
    creativeTypeIds IntList no filters results according to the specified creative type ids
    ids IntList no filters results according to the specified ids
    isArchived OptionalBool no state to check if the item can be used (not deprecated, not removed etc.)
    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

    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

    Replace <networkId> by the Id of your network.

    Parameters

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

    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

    Creates a new creative related to the current insertion.

    Endpoint

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

    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

    Replace <networkId> by the Id of your network.

    Parameters

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

    Example response

    empty (code 200 OK)

    RELATED ARTICLES