• 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

1Content-Type: application/json
2Accept: application/json
Copy

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

1{
2  "CallerId": "+15551234567",
3  "InboundStateCode": "CO"
4}
Copy

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

1?CallerId=15551234567&InboundStateCode=CA
Copy

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 SIP
10}
Copy

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  }'
Copy

Example with curl using GET:

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

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}
11
Copy

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}
11
Copy

Response Fields

id (string) - The bid id.

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.

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

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