CallGrid Bid API - Advanced RTB Integration Guide

• Posting Bids from Ringba to CallGrid using RTB
• Posting Bids from Retreaver to CallGrid using RTB

Overview

The CallGrid Bid API allows custom platforms and developers to send real-time bid requests to CallGrid campaigns. This guide provides the technical specifications for integrating directly with the CallGrid RTB (Real-Time Bidding) system.

Key Features:

• RESTful JSON API
• Real-time bid responses (< 10 ms response times without pings)
• Flexible acceptance criteria
• Support for geographic targeting
• Detailed response codes for handling various scenarios

API Endpoint#

Base URL#

POST or GET https://bid.callgrid.com/api/bid/{Grid-ID}

Parameters:

• {Grid-ID}: The unique Grid identifier provided by your CallGrid buyer

Example:

https://bid.callgrid.com/api/bid/cm97s8hmv000ijt06r4djmije
* Note that you must use the correct Grid ID provided by your buyer.

Request Format#

You can use either GET or POST when sending to the CallGrid Bid API.

If sending through GET simply send the required parameters as URL parameters.

If sending through POST simply send the required data as post data via json or www/url-encoded.

HTTP Headers#

Headers for POST request

Content-Type: application/jsonAccept: application/json

Required Request Parameters#

CallerId (Required) - The caller's phone number (10-digit format recommended)

• Example: "3035551234"

InboundStateCode (Optional) - Two-letter state code of the incoming call

• Example: "CO"

Request Body Structure#

Data for post request

{  "CallerId": "+15551234567",  "InboundStateCode": "CO"}

Note: you can also send this data as URL parameters if sending via the GET method ie:

?CallerId=15551234567&InboundStateCode=CA

Note: If you cannot send the call over SIP you can pass the "pstn" flag to get a dynamic phone number to which you can send the call. Set { "pstn": true } in the post data or &pstn=true in the url parameters if using GET to request a dynamic phone number instead of a dynamic sip address. When sending a call over ptsn the caller ID must match the one specified in the bid, or the call will be rejected.

Optional Request Parameters#

You can include additional custom parameters based on your buyer's requirements:

1{2  "CallerId": "+15551234567",3  "InboundStateCode": "CO",4  "InboundZipCode": "80301",5  "age": 38,6  "CallQualityScore": "95",7  "CampaignType": "insurance",8  "PublisherId": "pub123"9  "pstn": false, // set to true if you cannot send via SIP10}

Note: To push a Tag through with the bid the Tag must exist in the receiving party's CallGrid account.

Complete Request Example#

Example with curl using POST:

1curl -X POST https://bid.callgrid.com/api/bid/cm97s8hmv000ijt06r4djmije \2  -H "Content-Type: application/json" \3  -H "Accept: application/json" \4  -d '{5    "CallerId": "+15551234567",6    "InboundStateCode": "CO"7  }'

Example with curl using GET:

curl "https://bid.callgrid.com/api/bid/cm97s8hmv000ijt06r4djmije?CallerId=+15551234567&InboundStateCode=CO"

Response Format#

Success Response Structure#

When a bid is accepted, CallGrid returns a JSON response with the following structure:

1{2  "id":"cmbidlwefyn02316t3nkxnelxz",3  "code":"1000",4  "message": "Success",5  "dynamicBid":"1.00",6  "dynamicDuration":"10",7  "expirationSeconds":"100",8  "payOnDuplicates":false,9  "dynamicSipAddress":"sip:cmbidlwefyn02316t3nkxnelxz@somewhere.sip.callgrid.com"10}

1{2  "id":"cmbidlwefyn02316t3nkxnelxz",3  "code":"1000",4  "message": "Success",5  "dynamicBid":"1.00",6  "dynamicDuration":"10",7  "expirationSeconds":"100",8  "payOnDuplicates":false,9  "dynamicPhoneNumber":"+1234567890"10}

Response Fields#

id (string) - The bid id. You will need to capture this if sending a Confirmation request.

code (integer) - Response status code (see Response Codes below)

message (string) - Human-readable message describing the response

dynamicBid (float) - The bid amount offered for the call in USD

dynamicDuration (string) - Phone number where the call should be routed

expirationSeconds (string) - The number of seconds until the bid expires. You must send the call within this time limit.

payOnDuplicates (boolean) - If this call will pay on a duplicate or not.

dynamicSipAddress (string) - The SIP address where the call should be routed.

dynamicPhoneNumber (string) - The Phone Number where the call should be routed. *If using pstn=true.

confirmationRequired (boolean) - If a confirmation step is required.

Response Codes#

Your CallGrid buyer will respond with one of these codes:

• 1000: Bid success - Bid received and created
• 4000 and above: Bid rejected - see the API Error Codes article for more details.
• 5001: Bid Rate Limits

Confirmation Step (Usually not Required)#

Note: Most CallGrid pings do NOT require a Confirmation Step. However, certain Grid IDs can be configured for your buyer to require a confirmation step.

If the response indicates a confirmation step is required (confirmationRequired: true), then you must send a Confirmation request or you will not receive a dynamicSipAddress or dynamicPhoneNumber. You may send additional tags through with the confirmation step. Your buyer might require you to post the CallerId or additional tags on the confirmation step.

Confirmation Step URL#

POST or GET https://bid.callgrid.com/api/bid/confirmation/{Bid-ID}

Parameters:

• {Bid-ID}: The unique Bid "id" returned from the "id" of the Bid Request above.

Example:

https://bid.callgrid.com/api/bid/confirmation/cm42x8hbv109ixtz64jdqmzof
* Note that you must use the correct Bid "id" field returned from the original bid request.

Confirmation Step Parameters #

To send through additional tag data on the confirmation step you can pass the parameters through a GET URL or a POST Body same as described above in the Request Format section. If you already sent certain parameters through on the initial request, you do not need to include them on the confirmation step. CallerId is not required but should be specified if it was not sent in the original request.

Confirmation Step Response#

The response codes and data sent on the confirmation reply are the same as the initial request step.

See the Response Format section above to see the response shape. A successful confirmation step will include a dynamicSipAddress or dynamicPhoneNumber and a code: 1000.

Implementation Guide#

Step 1: Obtain Grid ID#

Before integrating, obtain the Grid ID from your CallGrid buyer:

1. Contact your CallGrid buyer/partner
2. Request their Grid ID for RTB integration
3. Confirm which parameters they expect in bid requests
4. Verify their acceptance criteria (minimum bid amounts, geographic restrictions, etc.)

Step 2: Test Bid URL in browser or with curl.#

1. Construct your bid URL using the Grid ID provided by buyer
2. Test the URL using your browser or CURL using the GET request method.

Step 3: Implementation.#

1. Check for code 1000 and map the dynamicSipAddress, dynamicBid, and dynamicDuration to the correct variables in your application.

Best Practices#

Request Optimization#

Send Complete Data:

• Always include CallerId (required)
• Include InboundStateCode or InboundZipCode when available
• Add custom parameters your buyer expects
  

Testing Checklist#

✓ Verify Grid ID is correct and active

✓ Confirm request includes required CallerId parameter

✓ Test with valid phone numbers (10-digit format)

✓ Verify timeout handling (10 second limit)

✓ Test response code handling (1000, 2000, 3000, 4000, 5000)

✓ Log all bid requests and responses for debugging

Additional Resources#

API Reference:

• CallGrid Bid API Response Codes
• CallGrid API Reference

Platform-Specific Guides:

• Posting Bids from CallGrid to CallGrid
• Posting Bids from Ringba to CallGrid
• Posting Bids from Retreaver to CallGrid
• Receiving Bids in CallGrid

Support:

• Email: support@callgrid.com
• Documentation: callgrid.com/knowledge-base

Support#

For technical assistance with the CallGrid Bid API:

1. Review this documentation and test your integration
2. Contact your CallGrid buyer to verify Grid ID and requirements
3. Reach out to CallGrid support with your integration details and logs

Need Help?

• Technical questions: support@callgrid.com
• Integration assistance: Include your Grid ID and sample requests
• Bug reports: Provide full request/response logs and error messages.