CallGrid Real Time Call Bidding Integration

What this article covers#

How a CallGrid customer sells calls to another CallGrid customer (or a partner running a CallGrid bidding campaign) in real time. The seller builds a destination whose Ping sends a bid request to the buyer's CallGrid bidding campaign; the buyer's response decides whether the seller's destination is considered and what it pays.

• Seller: owns the calls. Configures a destination with a CallGrid bid Ping.
• Buyer: runs a CallGrid bidding campaign and gives the seller a source Grid ID (shown in the buyer's campaign Sources tab).

Prerequisites#

Buyer (receiving account)

• A bidding campaign with a source created for this seller. The Sources table shows the source's Grid ID; bidding sources are Dynamic (no static numbers).
• Bid Settings reviewed: Require Caller ID, Require Confirmation Ping, Bid On Duplicates, Passthrough or Cost Plus.
• Bid Rate Limits set for the expected ping volume (Max Requests per Minute, Hour or Day; Expired Bid Action; Bid Expiration). Per-source overrides are on the Sources tab.

Seller (sending account)

• The buyer's Grid ID.
• A campaign whose routing plan will include the new destination.

Step 1: Create the destination#

1. Go to Buyers (Destinations) > New Destination.
2. On Settings: Name, Buyer, Timezone, Business Hours.
3. Call Settings > Phone Type: Variable (the number to dial comes from the bid response).
4. Revenue Settings: Revenue Type Variable; set Min Revenue Amount if you will not sell below a floor. It overrides the campaign and routing group Minimum Revenue for this destination.
5. Set caps and Max Pings Per Minute to stay inside the buyer's Bid Rate Limits.
6. Save the destination. The Ping tab is enabled after the first save.

Step 2: Build the Ping#

1. Open the destination's Ping tab.
2. Ping Template: choose CallGrid and enter the Grid ID. Otherwise configure manually.
3. Request Data:
   • Method POST, Content Type JSON.
   • URL: the buyer's bid endpoint for the Grid ID, for example https://bid.callgrid.com/api/bid/<GridID>.
   • Timeout: keep it short. A slow buyer delays routing and shows under Timeout in the Pings report.
4. Body: send the caller ID and any tags the buyer filters on, for example:

1{2  "CallerId": "[[tag:InboundNumber]]",3  "InboundStateCode": "[[tag:InboundStateCode]]",4  "InboundZipCode": "[[tag:InboundZipCode]]"5}

5. Use Static IP: only if the buyer restricts by IP. Requests then come from 3.232.249.88 and 54.160.65.103.

Step 3: Parse the response#

The CallGrid Ping Template sets up parsing for you. It accepts the bid when the response's code is 1000, and maps the routing target, the bid and the required duration from the response. If you configure the Ping by hand, use the same settings:

1. Acceptance Parsing: code Equals 1000. (Operators are Equals, Not Equal To, Greater Than and Less Than.)
2. Field Mapping:
   • Variable Phone/SIP: dynamicSipAddress.
   • Variable Revenue/Bid: dynamicBid.
   • Variable Duration: dynamicDuration.
3. Value Extraction (optional): map the bid id or reject reason to custom tags, or to PingResponseId / PingResponseCode, for reporting and troubleshooting.
4. Click Run Ping with test variables (a real-looking caller ID and state), check the response and acceptance result, then Save Ping.

Use the destination's Min Revenue Amount for bid floors rather than acceptance rules on the amount; below-floor pings then appear under Min Rev in the Pings report.

Step 4: If the buyer requires a confirmation ping#

When the buyer's campaign (or a bid rule) has Require Confirmation Ping on, the bid response does not include the routing target. The seller must confirm to receive the routing number.

1. On the Ping tab, open Confirmation Ping/Post.
2. Variable Ping ID: select the response parameter holding the bid id. It is stored in [[tag:PingId]].
3. Confirmation URL: https://bid.callgrid.com/api/bid/confirmation/[[tag:PingId]], adding CallerId as a query parameter for PSTN (dynamic number) bids. A PSTN confirmation with no CallerId is rejected.
4. Acceptance (confirmation): parse the confirmation response. The number comes back as dynamicPhoneNumber (or dynamicSipAddress); map it in Field Mapping.
5. When Use Static IP for requests is checked, confirmation requests also come from 3.232.249.88 and 54.160.65.103. If live confirmations fail with Forbidden while tests pass, check that Use Static IP is checked on this destination and that the buyer allows both IPs.

The buyer's Send Confirmation On setting (Auction Won or Call Won) controls when the buyer's own downstream confirmations fire; it does not change what the seller sends.

SIP vs phone number: important for CallGrid to CallGrid#

CallGrid returns a SIP address by default in most cases. To get a phone number instead, send pstn=true on the bid request (in the query string for GET or the body for POST) and map dynamicPhoneNumber to Variable Phone/SIP. CallGrid-to-CallGrid SIP works, both to a static source's SIP DID and to a SIP address returned on a CallGrid bid response when the seller is another CallGrid organization.

How it works on a live call#

1. A call (or an upstream bid) reaches the seller's campaign.
2. Routing pings eligible destinations, including this one, with the call's tags.
3. The buyer's campaign evaluates its bid settings, bid rules, duplicates, rate limits and its own buyers, and responds.
4. The seller's Acceptance Parsing and Min Revenue Amount decide whether this destination competes; the routing method (Priority, Revenue, Average RPC, Dynamic RPC or AI Routing (beta)) picks the winner.
5. If this destination wins, CallGrid dials the returned number within the buyer's Bid Expiration. A call arriving after expiration follows the buyer's Expired Bid Action (Reject or Route).

Troubleshooting#

Best practices#

• Send every tag the buyer filters on; missing tags cause Tag Rules rejections.
• Agree Bid Expiration and rate limits with the buyer before launch.
• Start with one test source and watch the buyer's Bids tab and the seller's Pings tab together for the first day.
• Use Ping Guard on the seller's bidding campaigns when several publishers ping the same callers.

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "What was the accept rate on my CallGrid bid destinations this week?" Claude and ChatGPT need the CallGrid connector turned on (setup guides for Claude and ChatGPT).

The connector is read only. It looks things up and reads your data. You make the changes in CallGrid.