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.

This article contains the following sections:

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.

If you are sending calls over SIP, add sipOk=true to the URL in your GET request or to the body of your JSON post. If you are sending calls to a DID (traditional phone number) instead, leave this out. See SIP numbers with Ringba RTB for more information on the benefits of using SIP numbers.

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",
    "sipOk": "yes"
}

Note: If you are not sending calls over SIP, leave out the "sipOk": "yes" line.

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> 
    <sipOk>yes</sipOk>
</bid_request>

Note: If you are not sending calls over SIP, leave out the <sipOk>yes</sipOk> line.

GET Methods

JSON GET URL

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

Note: If you are not sending calls over SIP, leave off sipOk=yes.

XML GET URL

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

Note: If you are not sending calls over SIP, leave off sipOk=yes.

Sample Response Data

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. If you do not transfer the call within that number of seconds, the system rejects the call and a new bid must be created.

Accepted Bid Response over SIP

If the bid is accepted and you are using SIP, you receive a response like this. It contains the details you need to transfer the call. It does not include a phone number, so you must process this request to send he call to the value in sipAddress. 

{
    "bidId": "RTB959b58bf69ed4282xx999x999xxxxx99",
    "bidAmount": 10,
    "expireInSeconds": 60,
    "bidExpireDT": "9/10/2024 8:00:09 PM +00:00",
    "bidExpireEpoch": 1725998409066,
    "sipAddress": "RTB959b58bf69ed4282xx999x999xxxxx99@rtb.ringba.sip.telnyx.com",
    "bidTerms": [
        {
            "code": 101,
            "description": "Call must connect"
        }
    ]
}

Accepted Bid Response over DID

If the bid is accepted, the response contains the details you need to transfer the call. This response contains both the phone number and the SIP address. If you are using DID, you process this request to use the phone number.

{
    "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."
        }
    ]
}

Rejected Bid Responses

If a bid request fails, the system returns an error response:

{ 
    "bidId": "RTBabf2787f19ae4de5b0021b92bf595659", 
    "bidAmount": 0, 
    "rejectReason": "Caller ID (Code: 1004)" 
}

If the a parameter is missing, you may see a message like this:

{ 
    "error": { 
        "code": 3024, 
        "message": "Following required tags have not been 
specified: zipcode" 
    } 
}

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.
  • rejectReason: The reason the bid was rejected. See RTB Error Codes for descriptions of each of the reason codes.
  • 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.

Troubleshooting

If a bid is being consistently rejected, check the rejectReason field in the rejected bid response. Common errors include the following:

  • 1003: No capacity (target unavailable)
  • 1004: Caller ID (blocked due to spam, duplicate payout, blocked list)
  • 1100: Caller ID verification failure 
  • 1024: Rate-limited 

See the RTB Error Codes article for a complete list of errors and description. 

If you need to check the details of the request with your buyer, include the bidId value from
the response in your communication. The bidId is a unique identifiers for each request that your buyer can used to look up the request. 

Related articles