RTB API

Using merchenta.io for real-time bidding

Simple campaign 

Using merchenta.io RTB API, this is an example of a simple campaign setup. For illustrative purposes, this campaign will include two ad creatives (ie 2 ads) combined with simple placement targeting settings (ie above or below fold, blind or transparent inventory) for a fixed campaign period (also known as a “flight”) against a total budget of $5000. Media will be bought at a fixed CPM of $2/CPM.

The campaign - when approved and run - will buy media each day during the flight across standard display placements, displaying the two ads in rotation.

Note that as this is a simple example, we’ve chosen to run the campaign in US Dollars (the default). We could easily have chosen one of any number of other currencies by specifying a different currency - merchenta.io will do automatic foreign exchange conversion when bidding if the underlying media is priced in a different currency from the campaign itself.

Generate authentication token 

/v3/oauth/accessToken?username={username}&password={password}&advertiser={advertiser}
  • Parameters
  • username
    string (required) Example: username

    username

    password
    string (required) Example: password

    password

    advertiser
    string (required) Example: MERCHENTA

    advertiser code

  • Curl
  • Copy
    curl -i \ -X GET \ https://sandbox.rtbapi.io/v3/oauth/accessToken?username=username&password=password&advertiser=MERCHENTA
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZHYiOiJNRVJDSEVOVEEiLCJleHAiOiIyMDE0LTEwLTA3VDEwOjIwOjEyLjQ4OSIsInJsbSI6IkFETUlOIiwidXNyIjoidGVzdEBtZXJjaGVudGEuY29tIiwiaWF0IjoiMjAxNC0xMC0wN1QwOToyMDoxMi40NTAifQ.7fb8007c49abb7e083f4aca024512ef3c9d32ea1ab0502d2603f4c2c92545b80"
            }
        }

Upload creative file 

/v3/creatives/upload/push
  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -F creative=@[YOUR_FILENAME_HERE] \ https://sandbox.rtbapi.io/v3/creatives/upload/push
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: multipart/form-data
    Content-Disposition: form-data; name="creative"; filename="[YOUR_FILENAME_HERE]"
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "id": "MERCHENTA-b021a5e27751d90f56803375d4329d9a33e72bad.jpg",
                "location": "https://cdn3.merchenta.com/static/assets/MERCHENTA-b021a5e27751d90f56803375d4329d9a33e72bad.jpg"
            }
        }

Create simple ad campaign 

/v3/campaigns/{ADVERTISER_CODE}-simple

Campaign settings:

  • two display creatives
  • blind inventory
  • above and below the fold
  • frequency cap of 12 ads/day
  • lifetime budget of $5000 (allocated daily over the duration of the flight)
  • flight dates of start=now(), end = now()+5 days
  • Curl
  • Copy
    curl -i \ -X PUT \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "creatives":[ { "code":"{ADVERTISER_CODE}-simple-1", "creativeId":"MERCHENTA-afed737deeedbc6e21f3b2148c9f2865cbdba68b.jpg", "dimensions":{ "width":728, "height":90 }, "clickthroughUrl":"http://merchenta.com", "type":"IMAGE" }, { "code":"{ADVERTISER_CODE}-simple-2", "creativeId":"MERCHENTA-b021a5e27751d90f56803375d4329d9a33e72bad.jpg", "dimensions":{ "width":300, "height":250 }, "clickthroughUrl":"http://merchenta.com", "type":"IMAGE" } ], "inventorySettings":{ "inventoryType":"BLIND", "placementType":[ "ATF", "BTF" ], "exchangeBlockList": ["GD", "BS"] }, "biddingSettings":{ "frequencyCap" : 12, "biddingStrategy":{ "strategy":"CPMCappedBiddingStrategy", "maxBid":2 }, "budget":{ "lifetime":5000 }, "pacingType":"ACCELERATED" }, "timeSettings":{ "start" : "2014-01-01T12:00:00", "end" : "2014-01-05T12:00:00" } }' \ https://sandbox.rtbapi.io/v3/campaigns/{ADVERTISER_CODE}-simple
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: application/json
    Example body
    {
        "creatives":[
            {
                "code":"{ADVERTISER_CODE}-simple-1",
                "creativeId":"MERCHENTA-afed737deeedbc6e21f3b2148c9f2865cbdba68b.jpg",
                "dimensions":{
                    "width":728,
                    "height":90
                },
                "clickthroughUrl":"http://merchenta.com",
                "type":"IMAGE"
            },
            {
                "code":"{ADVERTISER_CODE}-simple-2",
                "creativeId":"MERCHENTA-b021a5e27751d90f56803375d4329d9a33e72bad.jpg",
                "dimensions":{
                    "width":300,
                    "height":250
                },
                "clickthroughUrl":"http://merchenta.com",
                "type":"IMAGE"
            }
        ],
        "inventorySettings":{
            "inventoryType":"BLIND",
            "placementType":[
                "ATF",
                "BTF"
            ],
            "exchangeBlockList": ["GD", "BS"]
        },
        "biddingSettings":{
            "frequencyCap" : 12,
            "biddingStrategy":{
                "strategy":"CPMCappedBiddingStrategy",
                "maxBid":2
            },
            "budget":{
                "lifetime":5000
            },
            "pacingType":"ACCELERATED"
        },
        "timeSettings":{
            "start" : "2014-01-01T12:00:00",
            "end" : "2014-01-05T12:00:00"
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success"
        }
Next page  Previous page