Send RTB requests to a Moja buyer

Who this is for: publishers and sellers sending call opportunities to a buyer who runs Moja. What you’ll need: the RTB endpoint URL, the HTTP method, and the agreed parameter list from your buyer, plus a test caller ID and an agreed test window. Time: about 20 minutes, including a test call.

Note

Inside Moja this feature is called Inbound RTB, because your request arrives at your buyer’s campaign. From where you sit, you are simply sending an RTB request to a buyer.

How it works

sequenceDiagram
    participant You as Your platform
    participant Moja as Buyer's Moja campaign
    You->>Moja: RTB request with caller data
    Moja-->>You: Bid response — number, payout, allocation window
    You->>Moja: Send the caller to the returned number
    Moja->>Moja: Route the call to the buyer's target

Four moves: you ask, Moja answers with a number and terms, you dial that number, Moja routes the call. Everything in this guide is about getting the first two right so the last two work.

Before you begin

Ask your buyer for all five of these. Missing any one of them will cost you a round of failed tests.

• The exact Moja RTB endpoint for your publisher account and campaign
• The HTTP method to use — GET is the recommended default
• The required parameter names and any buyer-specific metadata
• The expected payout and duration rules
• A test window and a test caller ID

Caution

Each endpoint is tied to one publisher and one campaign. Do not reuse an endpoint for another campaign unless your buyer confirms that setup — the calls will be attributed to the wrong place, or rejected.

Step 1 — Send the RTB request

Your buyer will provide an endpoint in this shape:

https://rtb.moja.cloud/inbound_rtb/{inbound_rtb_id}

For a GET request, add the caller information as query-string parameters:

https://rtb.moja.cloud/inbound_rtb/{inbound_rtb_id}?CALLER_ID=19995551234&ZIP_CODE=90210&sub_id=source_1

Replace the sample values with real values, or with the dynamic variables your sending platform supports. The example values are literal, not placeholder syntax.

Formatting rules

• Use the complete https:// endpoint supplied by your buyer.
• Start the first GET parameter with ? and each additional parameter with &.
• URL-encode parameter values.
• Send a clean caller number. E.164 — a leading +, country code, then the national number — is preferred where your platform supports it.
• Do not copy Moja’s outbound variable syntax, such as [CALLER_ID], into your request. Those are macros the buyer’s system expands, not values you send.

GET with query-string parameters is the recommended default because it is easy to inspect and troubleshoot in a browser or a log. Moja also accepts POST, including JSON payloads, for integrations configured that way — use POST only when your buyer gives you the expected request format.

Expected result: an HTTP 200 with a JSON body.

Step 2 — Include the required caller data

Parameter	Requirement	Example	Purpose
CALLER_ID or CID	Required	19995551234	Identifies the caller. Pick one of the two names and use it consistently.
ZIP_CODE	Recommended when available	90210	Improves geographic qualification and routing accuracy.
CALLER_STATE	Recommended when available	CA	Supports state-based qualification and routing.

Moja can derive geography from the caller number when ZIP or state is missing, but the location data you hold is usually more accurate than an inference from an area code.

Step 3 — Send only the metadata you agreed to send

Your buyer may ask for extra fields such as:

• Publisher or sub-ID
• Traffic source or channel
• Lead or session ID
• Campaign or vertical
• Buyer-specific caller attributes

Use the exact parameter names agreed with your buyer.

Caution

An arbitrary parameter is not automatically part of the buyer’s routing logic. For a custom value to affect reporting, pass-through, or advanced filtering, the buyer has to configure it in Moja first. Sending a field nobody configured is silent — it neither helps nor errors.

Step 4 — Read the response

When a route is available, Moja returns a body like this:

{
  "success": true,
  "request_id": "165b3f3a-5301-4ea1-a74c-66bf352481d1",
  "allocation_time_seconds": 60,
  "eligible_routes": [
    {
      "number": "+17014919171",
      "payout": 57.60,
      "duration": 60
    }
  ]
}

Field	Meaning	What to do with it
success	Whether the request produced a usable result	Branch on this before reading eligible_routes
request_id	Unique reference for this request	Store it. It is the first thing your buyer or Moja support will ask for
eligible_routes	The available phone number, payout, and duration terms	Dial number; record payout and duration against the call
allocation_time_seconds	How long the returned number stays allocated for this call	Start a timer. Dial inside this window or the number is no longer yours

If your buyer has enabled publisher-facing eligibility details, an unsuccessful response may also carry the reasons routes did not qualify. Keep the complete response body alongside the request_id — a partial paste is rarely enough to diagnose anything.

Step 5 — Send the call to the returned number

1. Confirm the response was successful and contains an eligible route.

2. Apply the payout and duration terms according to your agreement with the buyer.

3. Route the caller to the returned phone number within allocation_time_seconds.

4. Preserve the request and the response in your logs.

Caution

A number returned for one request belongs to that caller, for that window. Do not reuse it for a later caller, and do not dial it after the allocation window has expired. Both produce calls that either fail or attribute to the wrong request. See Preventing stale RTB bids with bid expiration controls.

Verify it works

Coordinate a controlled test with your buyer inside the agreed window. GET requests can be tested from a browser, cURL, or Postman; use cURL or Postman for POST.

curl --get 'https://rtb.moja.cloud/inbound_rtb/{inbound_rtb_id}' \
  --data-urlencode 'CALLER_ID=19995551234' \
  --data-urlencode 'ZIP_CODE=90210' \
  --data-urlencode 'sub_id=test'

Check all five:

• The request reaches the exact endpoint your buyer supplied.
• The response is valid JSON and your system parses it correctly.
• Your system stores the request_id, route, payout, duration, and allocation window.
• A test call reaches the returned number before the allocation expires.
• The buyer confirms the test appears under the expected publisher and campaign.

Success looks like: a success: true response with one eligible route, followed by a call your buyer can see in their call log with your publisher name on it.

Troubleshooting

Symptom	Likely cause	Fix
success: false, or no eligible route	Caps, filters, schedule, or geography on the buyer’s side; or a missing required parameter	How to troubleshoot RTB no-bid responses
HTTP error or unparseable body	Wrong endpoint, wrong method, bad query separators, or unencoded parameter values	Re-check step 1 against the URL your buyer sent, character for character
Response is slow	Too many targets, or slow downstream bidders inside the buyer’s campaign	How to troubleshoot high RTB processing time
You see RTB activity but the buyer sees no calls	The returned number was never dialled, or was dialled after the allocation expired	Why am I seeing RTB logs but no call logs?
Call connects but you are not paid	The buyer’s conversion rule was not met — usually a duration threshold	Why am I getting calls but no revenue?
Payout or duration is not what you expected	Terms differ from the agreement, or a different route won	Send your buyer the complete response and the request_id

Getting help

Contact your Moja-integrated buyer first. Include the request timestamp, the caller ID used for testing, the complete request and response bodies, and the request_id. Your buyer can review the campaign in Moja from there, or escalate to Moja Support with everything already in hand.

Related

• Getting started as a publisher or seller
• What is RTB?
• Inbound RTB buyer guide — the same exchange from the buyer’s side
• Integrating publishers and sellers with your Moja Inbound RTB campaign
• Custom tags with RTBs

Last reviewed: August 2026.