Allow RTB requests without `caller_number` on a postback key (part 2)

You can now configure a postback key to accept RTB reservation requests that do not include a caller_number. Previously the request would fail with FAILED must include caller_number (string).

Why

Some publishers sending calls to Retreaver from external platforms are finding it difficult to work with the dynamic SIP numbers returned by Retreaver when no caller_number is provided. What they need is to send an RTB request without a caller_number and to receive a phone number that is +1 XXX XXX XXXX otherwise they can not given the option to send the call to Retreaver.

Background

• caller_number — where the call is originating from.
• inbound_number — where Retreaver wants you to send the call so it can be properly tracked and connected.

When caller_number is omitted, Retreaver needs another way to decide which inbound_number to return. There are three cases.

The three cases when caller_number is not provided

1. inbound_number is passed as a request parameter

Retreaver returns the inbound_number you passed in.

$ curl -X POST -s "https://rtb.retreaver.com/rtbs.json?key=f38240dd-7f65-4e17-a4d7-2e09ccafad0e&inbound_number=+35924930101" | jq
{
  "uuid": "64ce5820-a451-475b-be29-26a47ec338b1",
  "status": "reserved",
  "retreaver_payout": 90.0,
  "retreaver_seconds": 120,
  "inbound_number": "+35924930101",
  "expires_at": "2026-05-05T06:26:06.534Z"
}

2. inbound_number is configured on the postback key in the UI

Retreaver returns the inbound_number configured on the postback key (in this example, +18339510260).

$ curl -X POST -s "https://rtb.retreaver.com/rtbs.json?key=f38240dd-7f65-4e17-a4d7-2e09ccafad0e" | jq
{
  "uuid": "597060af-2fbd-4339-9df6-f252038a94f7",
  "status": "reserved",
  "retreaver_payout": 90.0,
  "retreaver_seconds": 120,
  "inbound_number": "+18339510260",
  "expires_at": "2026-05-05T06:28:02.509Z"
}

3. No inbound_number configured and none passed as a parameter

Retreaver returns a dynamic SIP number where the call should be sent.

$ curl -X POST -s "https://rtb.retreaver.com/rtbs.json?key=f38240dd-7f65-4e17-a4d7-2e09ccafad0e" | jq
{
  "uuid": "1ab464f8-bc50-47e6-a26d-2b1c92f9f7b1",
  "status": "reserved",
  "retreaver_payout": 90.0,
  "retreaver_seconds": 120,
  "inbound_number": "sip:1ab464f8-bc50-47e6-a26d-2b1c92f9f7b1@retreaver-rtb.sip.twilio.com",
  "expires_at": "2026-05-05T06:25:41.770Z"
}

For reference: when caller_number is provided

Behavior is unchanged — the returned inbound_number is dynamic and chosen by Retreaver.

$ curl -X POST -s "https://rtb.retreaver.com/rtbs.json?key=f38240dd-7f65-4e17-a4d7-2e09ccafad0e&caller_number=12025550102" | jq
{
  "uuid": "05d44513-666d-46f1-a4f6-fb23cf206011",
  "status": "reserved",
  "retreaver_payout": 90.0,
  "retreaver_seconds": 120,
  "inbound_number": "+18334583385",
  "expires_at": "2026-05-05T06:25:08.295Z"
}

When the postback key does not allow missing caller_number

If the postback key has not been configured to accept requests without a caller_number, the request still fails as before:

$ curl -X POST -s "https://rtb.retreaver.com/rtbs.json?key=f38240dd-7f65-4e17-a4d7-2e09ccafad0e" | jq
{
  "error": "FAILED must include caller_number (string)"
}

Note: This describes the behavior of the current release. If you are reading this some time from now, please refer to the RTB guide at https://learn.retreaver.com/guides/working-with-the-retreaver-real-time-bidding-api for the up-to-date behavior.