RTB API

Using merchenta.io for real-time bidding

3rd party user ids targeting campaign 

It’s possible using the API to associate your own (“3rd party”) identifier with a consumer/user and use this subsequently for targeting campaigns. This is very useful in cases where you wish to maintain your own user profile store (or where teh store is physically too large to easily move around or synchronise).

By associating your own userid with our platform, you can subsequently run campaigns with a “sub segmentation” strategy that enable you to target individual consumers as well as larger groups of people (represented by segments).

There are a few steps in setting up the data stores to enable targeting campaigns :

  • create a Merchenta segment to synchronise your user profiles to (this will take the form of a pixel that can be deployed online)
  • deploy the segment pixel online (for example, on your website)
  • synchronise your user profiles with Merchenta on an ongoing basis
  • define Merchenta campaigns targeting specific members (user profiles) within the segment
  • run the campaign - reach only those user profiles within the segment that you have targeted

The specific steps to synchronise user profiles and run 3rd party profile targeted campaigns are as follows :

  • authenticate / connect to the API
  • create the segment
  • call the segment, specifying the userid parameter
  • target campaign to specific users in the segment

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"
            }
        }

Create segment 

First of all, create a segment into which you will place your user profiles.

/v3/segments
  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "name": "cart_segment", "type": "VIEW", "durationInDays": 7, "status": "ACTIVE" }' \ https://sandbox.rtbapi.io/v3/segments
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: application/json
    Example body
    {
        "name": "cart_segment",
        "type": "VIEW",
        "durationInDays": 7,
        "status": "ACTIVE"
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "id": "p7xw8xeI8f"
            }
        }

Call this segment from the site with userId 

When creating a segment, you will be retuned a pixel, which looks like this :

http://PIXELLING_ENDPOINT/merchenta/pxl?view=XXX&segment=XXX&sku=PRODUCT-SKU-HERE

To enable 3rd party user profile synchronisation, simply append the pixel url with a userid parameter, like this :

http://PIXELLING_ENDPOINT/merchenta/pxl?view=XXX&segment=XXX&sku=PRODUCT-SKU-HERE&userid=USER-ID-HERE

On your side of the interface (eg website or server-to-server process), be sure to deploy the pixel and substitute the USER-ID-HERE with your user profile identifier. This may be alphanumeric (characters and numbers only) to a maximum length of 40 characters.

If you do not add the userid parameter you will still be able to target all users in a segment but not specific users within the segment.

/v3/segments/{segmentId}
  • Parameters
  • segmentId
    string (required) Example: p7xw8xeI8f

    The segment ID.

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/segments/p7xw8xeI8f
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "segment": {
                    "id": "p7xw8xeI8f",
                    "status": "ACTIVE",
                    "type": "CART",
                    "name": "cart_segment",
                    "htmlScript": "<a href=\"http://api.merchenta.com/merchenta/pxl?view=MERCHENTA&segment=uDVvnEvjqR&sku=PRODUCT-SKU-HERE\" />",
                    "durationInDays": 7
                }
            }
        }
  • Response  404

Setup 3rd party user id targeting for campaign 

Once the segment pixel has been deployed and is synchronising profiles, you can create a 3rd party user id targeting campaign. This will enable you to target specific user profile members of the segment you created earlier.

Note : If you added users to the segment with userId you can target the campaign only on users with specific matching pforile/userids within this segment. User ids should be comma separated.

/v3/campaigns/{campaignCode}/3rdPartyUserIdsTargeting/{segmentId}

Upload the file with ids via multipart/form-data POST request. Third party user ids should delimited by comma. For example “userProfileA,userProfileB,userProfileC”.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -F userIds=@[YOUR_FILENAME_HERE] \ https://sandbox.rtbapi.io/v3/campaigns/{campaignCode}/3rdPartyUserIdsTargeting/{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"
                    }
            }
        }
Next page  Previous page