Signal Source

Publisher API Docs

Getting Started: SignalSource Publisher API Integration

This guide will walk you through connecting to our platform to send calls via API.

The most important part of this integration is call attribution. For you to get paid and for us to route calls correctly, every call you send must be tagged with your unique Publisher ID.

What You Need from SignalSource

Before you start, contact your campaign manager and ask for these two items:

  1. Your Publisher ID: Your unique identifier (e.g., cbef29a7).
  2. Campaign ID: The unique ID for the campaign you are sending calls to (e.g., 48adc4c8-39jd0snm-…).

API Integration: How to Send a Call

Our API uses a “Ping & Post” process. You will send us a POST request with the caller’s details. If we have an available buyer, we will respond with a unique phone number for you to transfer the call to.

Step 1: Construct the API Request

You will send a POST request to the following endpoint. All data, including your Campaign ID and caller information, must be sent as URL query parameters.

Endpoint URL: https://rtb.retreaver.com/rtbs.json

Mandatory Parameters: Your request must include these four parameters:

  • key: Your unique Campaign ID
  • publisher_id: Your unique Publisher ID
  • caller_number: The customer’s full phone number (E.164 format +1… is recommended)
  • caller_zip: The customer’s zip code

*You can also send additional data by appending more parameters to the URL if we want to optimize by more granular detail

Example (Mandatory Fields Only):

				
					https://rtb.retreaver.com/rtbs.json?key=YOUR_CAMPAIGN_ID_HERE&publisher_id=YOUR_PUBLISHER_ID_HERE&caller_number=[caller_number]&caller_zip=[zip]

Step 2: Handle the API Response

If we find an available buyer, our server will immediately reply with a JSON response.

Example JSON Response:

				
					{
  "uuid": "66b905ef-bc03-420e-ad43-e8eeae03918f",
  "status": "reserved",
  "retreaver_payout": 1.173,
  "retreaver_seconds": 95,
  "inbound_number": "+18444021146",
  "expires_at": "2024-05-29T16:16:18.246Z"
}

You must parse this response to extract three critical values:

  1. retreaver_payout: The payout you will receive for a successful conversion.
  2. retreaver_seconds: The minimum call duration (in seconds) required for conversion.
  3. inbound_number: The unique, temporary phone number to transfer the call to.

Example JavaScript parsing:

				
					var response = JSON.parse(Webhook_Response);
var payout = response.retreaver_payout;
var duration = response.retreaver_seconds;
var transfer_number = response.inbound_number;

Step 3: Check Criteria and Transfer the Call

If the retreaver_payout and retreaver_seconds meet your criteria, you must immediately transfer the call.

CRITICAL: When you transfer the call to the inbound_number, you must use the original caller_number (from your Step 1 request) as the outbound Caller ID (ANI). This is how our system matches the live call to your reservation.

Warning: Reservations Expire! This reservation is temporary. The default expiration time is 20 seconds. You must transfer the call using the correct Caller ID before it expires, or the number will become invalid and the call will fail.

Handling API Responses & Troubleshooting

This section covers common responses and issues.

Successful Response: “status”: “reserved”

  • This is the only successful response. It means a buyer has been found and a number has been reserved for your call. You should proceed with the transfer (Step 3).

Failed Response: “status”: “no-target”

  • This is a common failed response. It is not an error. It means no buyer was available to take the call based on the campaign’s routing logic (e.g., filters, business hours, caps).

  • What to do: Do not transfer the call. No inbound_number will be returned.

Failed Response: “status”: “rejected”

  • This means an error occurred, such as the system being unable to connect to a buyer.
  • What to do: Do not transfer the call.

Reservation Expiration

  • A reservation is temporary. You should always read the expires_at timestamp in the response. This timestamp is the absolute source of truth for when the reservation expires.

  • What to do: You must transfer the call before this timestamp. Dialing an expired inbound_number will lead to a dead line.

Duplicate Pings (Ping Shield)

Our system includes a “Ping Shield.” If you send multiple, rapid-fire requests for the exact same caller_number, the system may throttle or return a cached response. This is normal behavior to prevent spam and duplicate processing.

Quick Troubleshooting

What are the mandatory fields for the API? You must include the key (your Campaign ID), publisher_id, caller_number, and caller_zip in the URL of your POST request.

What happens if I wait too long to transfer the call? The reservation will expire (usually in 20 seconds). Dialing an expired inbound_number will lead to a dead line.

My calls keep disconnecting after a few minutes. This is almost always an issue with your own dialer or telephone system. Check your system for a “max conference setting” or an incorrect transfer command that is prematurely hanging up the call.

Powered by CookieAdmin