⚠️ ADVANCED GUIDE: This article is intended for developers integrating with CallGrid from custom platforms or building their own RTB integrations. If you're using Ringba, Retreaver, or another supported platform, please see the platform-specific articles instead:

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

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}

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

1?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 SIP
10}

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:

1curl "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}
11

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

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:

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

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

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

Step 3: Implementation.

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:

Platform-Specific Guides:

Support:

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

Support

For technical assistance with the CallGrid Bid API:

Review this documentation and test your integration
Contact your CallGrid buyer to verify Grid ID and requirements
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

CallGrid Bid API - Advanced RTB Integration Guide