RTB API

Using merchenta.io for real-time bidding

Segments 

We support these type of segments:

  • INTELLI_PIXEL – segment triggered by an IntelliPixel. It is mandatory to also provide a intelliPixelPath. To match all paths use “*“, some other examples are “*bonus*“ or “/sport_socks/*“.
  • EMAIL_OPEN – segment triggered by user opening an email
  • EMAIL_CLICK – segment triggered by user clicking on a link in an email
  • VIEW – segment triggered by user visiting page with product. Can be used instead on VIEW notification.
  • CART – segment triggered by user going to do checkout on your shopping cart. Can be used instead on CART notification.
  • PURCHASE – segment triggered by user after purchase. Can be used instead on PURCHASE notification.
  • IDFA - segment triggered by users who use iOS device.
  • ANDROID_ID - segment triggered by users who use Android device.

Create segment 

/v3/segments

Creates segment and provides newly generated segment ID in the response.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "name": "cart_segment", "type": "CART", "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": "CART",
        "durationInDays": 7,
        "status": "ACTIVE"
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "id": "p7xw8xeI8f"
            }
        }

Get single segment by ID 

/v3/segments/{segmentId}

Gets segment by ID

  • 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?cart=MERCHENTA&segment=uDVvnEvjqR&sku=PRODUCT-SKU-HERE\" />",
                    "durationInDays": 7
                }
            }
        }
  • Response  404

Get segments by type 

/v3/segments/type/{segmentType}

Gets segments by type

  • Parameters
  • segmentType
    string (required) Example: CART

    The segment type. Can be EMAIL_OPEN EMAIL_CLICK VIEW CART PURCHASE INTELLI_PIXEL IDFA or ANDROID_ID

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

List all segments 

/v3/segments

List all segments.

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

Edit segment 

/v3/segments/{segmentId}

Overrides existing segment.

  • Parameters
  • segmentId
    string (required) Example: p7xw8xeI8f

    The segment ID.

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

Delete segment 

/v3/segments/{segmentId}

Deletes segment by its ID.

  • Parameters
  • segmentId
    string (required) Example: p7xw8xeI8f

    The segment ID.

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

Check if user is present in segment 

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

    The segment ID.

    segmentType
    string (required) Example: IDFA

    The segment type ‘IDFA’ for iOS users or ‘AID’ for Android users.

    userId
    string (required) Example: 8cef646e5dad2f7742039f3d670b3c36

    IDFA or Android id MD5 encoded as hex string. Its size must be 32 characters.

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/segments/p7xw8xeI8f/IDFA/8cef646e5dad2f7742039f3d670b3c36
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "contains": true
            }
        }
  • Response  404

Add user to segment 

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

    The segment ID.

    segmentType
    string (required) Example: IDFA

    The segment type ‘IDFA’ for iOS users or ‘AID’ for Android users.

    userId
    string (required) Example: 8cef646e5dad2f7742039f3d670b3c36

    IDFA or Android id MD5 encoded as hex string. Its size must be 32 characters.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/segments/p7xw8xeI8f/IDFA/8cef646e5dad2f7742039f3d670b3c36
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success"
        }
  • Response  404

Remove user from segment 

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

    The segment ID.

    segmentType
    string (required) Example: IDFA

    The segment type ‘IDFA’ for iOS users or ‘AID’ for Android users.

    userId
    string (required) Example: 8cef646e5dad2f7742039f3d670b3c36

    IDFA or Android id MD5 encoded as hex string. Its size must be 32 characters.

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

Add user hashes to segment 

/v3/segments/{segmentId}/users

Upload the file with Merchenta user hashes via multipart/form-data POST request. File should contain user hashes delimited by commas.

  • Parameters
  • segmentId
    string (required) Example: p7xw8xeI8f

    The segment ID.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -F users=@[YOUR_FILENAME_HERE] \ https://sandbox.rtbapi.io/v3/segments/p7xw8xeI8f/users
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: multipart/form-data
    Content-Disposition: form-data; name="users"; filename="[YOUR_FILENAME_HERE]"
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success"
        }
  • Response  404
Next page  Previous page