RTB API

Using merchenta.io for real-time bidding

Accounts 

Account creation flow:

1) generate authentication token needed to access API endpoints used in next steps

2) create new user account

3) create new advertiser (advertiser will be automatically linked to API user who creating it)

4) link the user with the advertiser

Account deactivation flow:

1) generate authentication token needed to access API endpoints used in next steps

2) deactivate advertiser

Create / Edit user 

/v3/users/{username}

Creates / Edits user.

  • Parameters
  • username
    string (required) Example: test@merchenta.com

    The username

  • Curl
  • Copy
    curl -i \ -X PUT \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "password": "abc123", "reportingCurrency": "USD" }' \ https://sandbox.rtbapi.io/v3/users/test@merchenta.com
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: application/json
    Example body
    {
        "password": "abc123",
        "reportingCurrency": "USD"
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success"
    }

Get user 

/v3/users/{username}

Gets user by username

  • Parameters
  • username
    string (required) Example: test@merchenta.com

    The username

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/users/test@merchenta.com
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            user: {
                username: "test@merchenta.com",
                reportingCurrency: "USD",
                "connections": [
                    {
                        "advertiser": "MERCHENTA",
                        "realm": "ADMIN"
                    }
                ]
            }
        }
    }

Deactivate user 

/v3/users/{username}

Deletes user.

  • Parameters
  • username
    string (required) Example: test@merchenta.com

    The username

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

Create advertiser 

/v3/advertisers

Creates advertiser. See advertiser model for details.

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "name": "Merchenta", "status": "ACTIVE", "domain": "www.merchenta.com", "currencyCode": "USD", "correspondenceEmailAddress": "support@merchenta.com", "margins": { "mediaMargin": 5, "advertisingChargeCpm": 0, "contextualChargeCpm": 0, "brandSafetyChargeCpm": 0 }, "attributionSettings": { "postClick": { "windowInHours": 720, "percentage": 10 }, "postEngagement": { "windowInHours": 72, "percentage": 10 }, "postView": { "windowInHours": 72, "percentage": 10 } } }' \ https://sandbox.rtbapi.io/v3/advertisers
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: application/json
    Example body
    {
        "name": "Merchenta",
        "status": "ACTIVE",
        "domain": "www.merchenta.com",
        "currencyCode": "USD",
        "correspondenceEmailAddress": "support@merchenta.com",
        "margins": {
            "mediaMargin": 5,
            "advertisingChargeCpm": 0,
            "contextualChargeCpm": 0,
            "brandSafetyChargeCpm": 0
        },
        "attributionSettings": {
            "postClick": {
                "windowInHours": 720,
                "percentage": 10
            },
            "postEngagement": {
                "windowInHours": 72,
                "percentage": 10
            },
            "postView": {
                "windowInHours": 72,
                "percentage": 10
            }
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            "code": "MERCHENTA-WLIFC"
        }
    }

Add user to advertiser 

/v3/advertisers/{advertiserCode}/users/{username}/{realm}

Connect a user account to advertiser.

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

    username
    string (required) Example: test@merchenta.com

    The username

    realm
    string (optional) Example: VIEW

    The realm If parameter is not passed then ADMIN is used.

  • Curl
  • Copy
    curl -i \ -X PUT \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC/users/test@merchenta.com/VIEW
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success"
    }

List all users connected to advertiser 

/v3/advertisers/{advertiserCode}/users

Lists all users linked to advertiser

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC/users
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            "users": [
                "test@merchenta.com"
            ]
        }
    }

List all users and realms connected to advertiser 

/v3/advertisers/{advertiserCode}/users/connections

List all users and realms connected to advertiser. AGENCYADMINs from parent advertisers are not listed

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC/users/connections
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            "users": [
                {
                    "test@merchenta.com",
                    "realm": "ADMIN"
                },
                {
                    "tomek@tomek.pl",
                    "realm": "VIEW"
                }
            ]
        }
    }

Remove user from advertiser 

/v3/advertisers/{advertiserCode}/users/{username}

Removes a user account link to advertiser.

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

    username
    string (required) Example: test@merchenta.com

    The username

  • Curl
  • Copy
    curl -i \ -X DELETE \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC/users/test@merchenta.com
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success"
    }
  • Response  404

List advertisers 

/v3/advertisers

List user’s advertisers.

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            "advertisers": [
                "MERCHENTA-WLIFC"
            ]
        }
    }

Get advertiser 

/v3/advertisers/{advertiserCode}

Gets advertiser. See advertiser model for details.

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            "advertiser": {
                "code": "MERCHENTA-WLIFC",
                "name": "Merchenta",
                "status": "ACTIVE",
                "currencyCode": "USD",
                "margins": {
                    "mediaMargin": 5,
                    "advertisingChargeCpm": 0,
                    "contextualChargeCpm": 0,
                    "brandSafetyChargeCpm": 0
                },
                "attributionSettings": {
                    "postClick": {
                        "windowInHours": 720,
                        "percentage": 10
                    },
                    "postEngagement": {
                        "windowInHours": 72,
                        "percentage": 10
                    },
                    "postView": {
                        "windowInHours": 72,
                        "percentage": 10
                    }
                }
            }
        }
    }
  • Response  404

Edit advertiser 

/v3/advertisers/{advertiserCode}

Overrides existing advertiser. See advertiser model for details.

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

  • Curl
  • Copy
    curl -i \ -X PUT \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ -H 'Content-Type: application/json' \ -d '{ "name": "Merchenta", "status": "ACTIVE", "domain": "www.merchenta.com", "currencyCode": "USD", "correspondenceEmailAddress": "support@merchenta.com", "margins": { "mediaMargin": 5, "advertisingChargeCpm": 0, "contextualChargeCpm": 0, "brandSafetyChargeCpm": 0 }, "attributionSettings": { "postClick": { "windowInHours": 720, "percentage": 10 }, "postEngagement": { "windowInHours": 72, "percentage": 10 }, "postView": { "windowInHours": 72, "percentage": 10 } } }' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC
  • Request
  • Headers
    Authorization: Bearer {YOUR_TOKEN_HERE}
    Content-Type: application/json
    Example body
    {
        "name": "Merchenta",
        "status": "ACTIVE",
        "domain": "www.merchenta.com",
        "currencyCode": "USD",
        "correspondenceEmailAddress": "support@merchenta.com",
        "margins": {
            "mediaMargin": 5,
            "advertisingChargeCpm": 0,
            "contextualChargeCpm": 0,
            "brandSafetyChargeCpm": 0
        },
        "attributionSettings": {
            "postClick": {
                "windowInHours": 720,
                "percentage": 10
            },
            "postEngagement": {
                "windowInHours": 72,
                "percentage": 10
            },
            "postView": {
                "windowInHours": 72,
                "percentage": 10
            }
        }
    }
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success"
    }

Deactivate advertiser 

/v3/advertisers/{advertiserCode}

Deactivates advertiser by its code.

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

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

Show blocklisted domains for advertiser 

/v3/advertisers/{advertiserCode}/blocklist

Deactivates advertiser by its code.

  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC/blocklist
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
        "data": {
            "blocklist": [
                "opposingviews.com"
            ]
        }
    }
  • Response  404

Add domain to blocklist for advertiser 

/v3/advertisers/{advertiserCode}/blocklist/{domain}
  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

    domain
    string (required) Example: opposingviews.com

    Domain name has to be top level private domain like opposingviews.com, ebay.co.uk, etc. not shop1.ebay.co.uk

  • Curl
  • Copy
    curl -i \ -X POST \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/advertisers/MERCHENTA-WLIFC/blocklist/opposingviews.com
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
        "status": "success",
    }
  • Response  404

Remove domain from blocklist for advertiser 

/v3/advertisers/{advertiserCode}/blocklist/{domain}
  • Parameters
  • advertiserCode
    string (required) Example: MERCHENTA-WLIFC

    The advertiser code

    domain
    string (required) Example: opposingviews.com

    Domain name has to be top level private domain like opposingviews.com, ebay.co.uk, etc. not shop1.ebay.co.uk

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

Advertiser model 

Path Required Type Description
code N String The advertiser code (generated).
name Y String The advertiser name.
status N String The advertiser status. Valid values are: ACTIVE, INACTIVE.
Default: ACTIVE.
domain Y String The advertiser domain. It needs to be a valid domain e.g. www.merchenta.com.
currencyCode N String The advertiser currency code.
Default: USD.
correspondenceEmailAddress Y String The advertiser correspondence email address. This address will be used for example to send credit card top-up receipts.
margins Y Object The advertiser margin settings.
margins / mediaMargin Y Number The advertiser media margin.
margins / advertisingChargeCpm N Number The advertiser ad serving charge in CPM.
Default 0.
margins / contextualChargeCpm N Number The advertiser contextual targeting charge in CPM.
Default 0.
margins / brandSafetyChargeCpm N Number The advertiser brand safety charge in CPM.
Default 0.
attributionSettings N Object The advertiser attribution settings.
attributionSettings / postClick N Object The advertiser post click attribution settings.
attributionSettings / postClick / windowInHours Y Number The advertiser post click attribution window in hours.
Default 720.
attributionSettings / postClick / percentage Y Number The advertiser post click attribution percentage.
Default 10.
attributionSettings / postEngagement N Object The advertiser post engagement attribution settings.
attributionSettings / postEngagement / windowInHours Y Number The advertiser post engagement attribution window in hours.
Default 72.
attributionSettings / postEngagement / percentage Y Number The advertiser post engagement attribution percentage.
Default 10.
attributionSettings / postView N Object The advertiser post view attribution settings.
attributionSettings / postView / windowInHours Y Number The advertiser post view attribution window in hours.
Default 72.
attributionSettings / postView / percentage Y Number The advertiser post view attribution percentage.
Default 10.
Next page  Previous page