RTB API

Using merchenta.io for real-time bidding

Campaign setup 

Create campaign 

Once the campaign ad creative has been uploaded, the campaign itself can be created & scheduled. This is done by submitting a campaign definition using the campaign endpoint. Upon receipt, Merchenta will validate the campaign settings and – if valid – initiate the campaign.

/v3/campaigns/{campaignCode}

Creates campaign.

  • Parameters
  • campaignCode
    string (required) Example: MERCHENTA-test

    The campaign code. Must be unique and consist only of letters, numbers and hyphens. Once created, the campaign code will not change – it may be used as a primary key for further operations. Campaign codes can be a maximum of 32 characters long and may only contain characters A to Z, a to z, 0 to 9 and hyphen (“-”). Campaign codes must be prefixed with an advertiser code followed by hyphen (“-“).

  • Curl
  • Copy
    curl -i \ -X PUT \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "creatives":[ { "code":"MERCHENTA-test-1", "creativeId":"MERCHENTA-fa1a576f2b68bb5b6a8601ae1a669e32e99ab14a.png", "dimensions":{ "width":160, "height":600 }, "clickthroughUrl":"https://merchenta.io", "type":"IMAGE" } ], "inventorySettings":{ "inventoryType":"TRANSPARENT", "placementType":[ "ATF" ] }, "biddingSettings":{ "biddingStrategy":{ "strategy":"CPMCappedBiddingStrategy", "maxBid":2 }, "budget":{ "daily":10 }, "pacingType":"ACCELERATED" } }' \ https://sandbox.rtbapi.io/v3/campaigns/MERCHENTA-test
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: application/json
    Example body
    {
        "creatives":[
            {
                "code":"MERCHENTA-test-1",
                "creativeId":"MERCHENTA-fa1a576f2b68bb5b6a8601ae1a669e32e99ab14a.png",
                "dimensions":{
                    "width":160,
                    "height":600
                },
                "clickthroughUrl":"https://merchenta.io",
                "type":"IMAGE"
            }
        ],
        "inventorySettings":{
            "inventoryType":"TRANSPARENT",
            "placementType":[
                "ATF"
            ]
        },
        "biddingSettings":{
            "biddingStrategy":{
                "strategy":"CPMCappedBiddingStrategy",
                "maxBid":2
            },
            "budget":{
                "daily":10
            },
            "pacingType":"ACCELERATED"
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success"
        }

Setup mobile device id targeting for campaign 

Set up IDFA or Android id targeting for campaign.

/v3/campaigns/{campaignCode}/mobileDeviceIdTarget

Returns IDFA / Android id targeting for campaign.

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/mobileDeviceIdTarget
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "mobileDeviceTargeting": {
                    "campaignCode":"MERCHENTA-AJC-Test6",
                    "batchName":"mobile_ids",
                    "numberOfIds":300,
                    "lastModificationTime":"2015-05-22T16:28:37.000"
                    }
            }
        }
/v3/campaigns/{campaignCode}/mobileDeviceIdTarget

Upload the file with ids via multipart/form-data POST request. IDFAs or Android Ids in file should MD5 digests (as a hex strings) delimited by comma.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -F mobileIds=@[YOUR_FILENAME_HERE] \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/mobileDeviceIdTarget
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: multipart/form-data
    Content-Disposition: form-data; name="mobileIds"; filename="[YOUR_FILENAME_HERE]"
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "mobileDeviceTargeting": {
                    "campaignCode":"MERCHENTA-AJC-Test6",
                    "batchName":"mobile_ids",
                    "numberOfIds":300,
                    "lastModificationTime":"2015-05-22T16:28:37.000"
                    }
            }
        }
/v3/campaigns/{campaignCode}/mobileDeviceIdTarget

Deletes IDFA / Android id targeting for campaign.

  • Curl
  • Copy
    curl -i \ -X DELETE \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/mobileDeviceIdTarget
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success"
    }

Setup 3rd party user id targeting for campaign 

Set up 3rd party user id targeting for campaign. If you added users to the segment with userId you can target the campaign only on user with specific id in this segment. User ids should be comma separated.

/v3/campaigns/{campaignCode}/segmentUserIdsTargeting/{segmentId}

Upload the file with ids via multipart/form-data POST request. Third party user ids should delimited by comma.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -F userIds=@[YOUR_FILENAME_HERE] \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/segmentUserIdsTargeting/{segmentId}
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: multipart/form-data
    Content-Disposition: form-data; name="userIds"; filename="[YOUR_FILENAME_HERE]"
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "segmentUserIdsTargeting": {
                    "campaignCode":"MERCHENTA-AJC-Test6",
                    "numberOfIds":300,
                    "segmentId": "abc123",
                    "lastModificationTime":"2015-05-22T16:28:37.000"
                    }
            }
        }

Check 3rd party user id targeting for campaign 

/v3/campaigns/{campaignCode}/segmentUserIdsTargeting

Returns 3rd party user id targeting for campaign.

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/segmentUserIdsTargeting
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "segmentUserIdsTargeting": {
                    "campaignCode":"MERCHENTA-AJC-Test6",
                    "numberOfIds":300,
                    "segmentId": "abc123",
                    "lastModificationTime":"2015-05-22T16:28:37.000"
                    }
            }
        }
/v3/campaigns/{campaignCode}/segmentUserIdsTargeting

Deletes IDFA / Android id targeting for campaign.

  • Curl
  • Copy
    curl -i \ -X DELETE \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/segmentUserIdsTargeting
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success"
    }
Next page  Previous page