Skip to main content

Publishers: How to Implement Ringba RTB

Amanda Cross
Updated

This article explains how publishers correctly implement real-time bidding (RTB) to successfully sell their calls on Ringba. This article is for all publishers, regardless of whether they have a Ringba account.

Posting Instructions

To receive bids on a call, you must post the call using the Ringba API. This section describes multiple methods for posting your calls. You can choose whichever method works best for you.

Note: As a publisher or broker receiving a bid, it is very important that you configure your system to parse and utilize RTB response data properly or the call may be rejected. Most importantly, 1) the call must be transferred to the phoneNumber (or phoneNumberNoPlus or sipAddress) WITHIN the expireInSeconds number of seconds, and 2) the caller ID you include in your bid request must match the caller ID of the call that arrives. Failure to meet either of these criteria will result in the call being rejected.

The examples in this section use a sample phone number and ZIP code. A sample RTB_ID would make the examples look confusing, so they use RTB_ID.

  • Caller ID or CID: 1-555-777-9999
  • ZIP Code: 12345
  • RTB_ID: Any place you see RTB_ID, including in URLs, you'll replace it with the RTB ID value for the type of campaign.

Note: Caller ID is not required but highly recommended as it will increase buyer interest.

POST Methods

JSON

URL:
https://rtb.ringba.com/v1/production/RTB_ID.json

Header:
Content-Type: application/json

Body:

{
    "CID": "15557779999",
    "exposeCallerId": "yes",
    "zipcode": "12345"
}


XML

URL:
https://rtb.ringba.com/v1/production/RTB_ID.xml

Header:
Content-Type: application/xml

Body:

<bid_request> 
    <CID>15557779999</CID> 
    <zipcode>12345</zipcode> 
</bid_request>

GET Methods

JSON GET URL

https://rtb.ringba.com/v1/production/RTB_ID.json?CID=15557779999&zipcode=12345

XML GET URL:

https://rtb.ringba.com/v1/production/RTB_ID.xml?CID=15557779999&zipcode=12345


Note: as a publisher or broker receiving a bid from us, it is very important that the RTB response data be quickly parsed and utilized properly, or the call may be rejected.

Most importantly, the call must be transferred to the phoneNumber (or phoneNumberNoPlus or sipAddress) within the expireInSeconds number of seconds, or the call will be rejected and a new bid must be created.

Sample Response Data:

{
    "bidId": "RTB959b58bf69ed4282xx999x999xxxxx99",
    "bidAmount": 10,
    "expireInSeconds": 60,
    "bidExpireDT": "9/10/2024 8:00:09 PM +00:00",
    "bidExpireEpoch": 1725998409066,
    "phoneNumber": "+15557779999",
    "phoneNumberNoPlus": "15557779999",
    "sipAddress": "RTB959b58bf69ed4282xx999x999xxxxx99@rtb.ringba.sip.telnyx.com",
    "bidTerms": [
        {
            "code": 101,
            "description": "Call must connect"
        }
    ],
    "warnings": [
        {
            "code": 205,
            "description": "Sending calls via SIP is preferred over routing them to DID. DID numbers are not unique and are not protected from receiving spam calls or calls related to expired bids. Consider always providing Caller ID when not using SIP."
        }
    ]
}


Property Names and Descriptions

  • bidId: The Ringba ID for the bid. You can use this value to look up bid details later.
  • bidAmount: The dollar amount the buyer is bidding for the call.
  • expireInSeconds: The number of seconds you have to transfer the call to the buyer. It is very important that the call be transferred within this time period or the call will be rejected.
  • bidExpireDT: The datetime stamp when the bid expires.
  • bidExpireEpoch: The datetime stamp in Epoch format when the bid expires.
    phoneNumber: The phone number that the call must be immediately transferred to. Includes the + sign.
  • phoneNumberNoPlus: The phone number that the call must be immediately transferred to. Does not include the + sign.
  • sipAddress: SIP address alternative to the phone number options above.
  • bidTerms: Terms of the bid. Exact terms and parsing implementation steps will vary.
  • warnings: Warning messages with suggestions to help optimize the call.

Related articles