A guide for publishers and sellers sending RTB phone-call opportunities to a buyer using Moja.

What Moja calls this: The feature is named Inbound RTB inside Moja because your request enters your buyer's Moja campaign. From your perspective as the publisher, you are simply sending an RTB request to your buyer.

Before you begin

Ask your buyer for the following integration details:

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 test caller ID

Important: Each endpoint is tied to a specific publisher and campaign. Do not reuse an endpoint for another campaign unless your buyer confirms that setup.

1. Send the RTB request

Your buyer will provide an endpoint similar to:

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 supported by your sending platform. The example values are not placeholder syntax.

Request 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 format is preferred when your platform supports it.
Do not copy Moja's outbound variable syntax, such as [CALLER_ID], into your request.

GET with query-string parameters is the recommended default because it is easy to inspect and troubleshoot. Moja can also accept POST requests, including JSON payloads, for integrations configured that way. Use POST only when your buyer provides the expected request format.

2. Include the required caller data

Parameter	Requirement	Purpose
`CALLER_ID` or `CID`	Required	Identifies the caller. Use one name consistently.
`ZIP_CODE`	Recommended when available	Improves geographic qualification and routing accuracy.
`CALLER_STATE`	Recommended when available	Supports state-based qualification and routing.

Moja may derive geography from the caller number when ZIP or state is not supplied, but publisher-provided location data can be more accurate.

3. Send only agreed metadata

Your buyer may ask for additional 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. Custom values must be configured in Moja if the buyer wants to use them for reporting, pass-through, or Advanced Filtering. An arbitrary parameter is not automatically part of the buyer's routing logic.

4. Read the response

When a route is available, Moja returns a response similar to:

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

Field	Meaning
`success`	Whether the request produced a usable result.
`request_id`	The unique request reference to retain for troubleshooting.
`eligible_routes`	The available phone number, payout, and duration terms.
`allocation_time_seconds`	How long the returned number remains allocated for the call.

If your buyer has enabled publisher-facing eligibility details, an unsuccessful response may also include reasons that routes did not qualify. Retain the complete response and request_id when reporting a problem.

5. Send the call to the returned number

Confirm that the response is successful and contains an eligible route.
Apply the payout and duration terms according to your agreement with the buyer.
Route the caller to the returned phone number within allocation_time_seconds.
Preserve the request and response in your logs.

A number returned for one request should not be reused for a later caller or after its allocation window expires.

6. Test before sending production traffic

Coordinate a controlled test with your buyer. You can send GET tests with a browser, cURL, or Postman; use cURL or Postman for POST integrations.

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'

Verify all of the following:

The request reaches the exact endpoint supplied by your buyer.
The response is valid JSON and your system reads 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.

Troubleshooting checklist

No usable route: Confirm the caller data, geography, campaign, test window, and buyer eligibility requirements.
Malformed request: Check the endpoint, HTTP method, query separators, URL encoding, and parameter names.
Call does not connect: Confirm that you dialed the returned number for the same request before the allocation expired.
Unexpected payout or duration: Share the complete response and request_id with your buyer.

Need help?

Contact your Moja-integrated buyer first. Include the request timestamp, caller ID used for testing, complete request and response, and request_id. Your buyer can then review the campaign in Moja or contact Moja Support.

📘 How Publishers Send RTB Requests to a Moja Buyer