• 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 seconds)
• Flexible acceptance criteria
• Support for geographic targeting
• Detailed response codes for handling various scenarios

API Endpoint

Base URL

POST 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

Request Format

HTTP Headers

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

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

Optional Request Parameters

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

1{
2  "CallerId": "3035551234",
3  "InboundStateCode": "CO",
4  "InboundZipCode": "80301",
5  "CallQualityScore": "95",
6  "CampaignType": "insurance",
7  "PublisherId": "pub123"
8}
Copy

Complete Request Example

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": "3035551234",
6    "InboundStateCode": "CO"
7  }'
Copy

Response Format

Success Response Structure

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

1{
2  "code": 1000,
3  "message": "Bid accepted",
4  "bid_amount": 25.50,
5  "destination": "13035551234",
6  "caller_id": "15551234567",
7  "state_code": "CO",
8  "timestamp": "2025-09-30T15:30:00Z"
9}
Copy

Response Fields

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

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

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

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

caller_id (string) - The caller ID to display (optional)

state_code (string) - State code of the call

timestamp (string) - ISO 8601 timestamp of the bid response

Response Codes

The code field in the response indicates the bid status. Your system should handle these codes appropriately:

1000 - Bid Accepted

• Status: Call should be routed to the bidder
• Action: Route call to destination number

2000 - Bid Declined

• Status: Bidder does not want this call
• Action: Try next buyer or fallback routing

3000 - No Capacity

• Status: Bidder cannot handle calls at this time
• Action: Try next buyer or retry later

4000 - Invalid Request

• Status: Problem with the bid request format
• Action: Check request parameters and format

5000 - System Error

• Status: Technical issue with the bidder's system
• Action: Implement fallback routing

Response Code Examples

Code 1000 - Accepted:

1{
2  "code": 1000,
3  "message": "Bid accepted",
4  "bid_amount": 25.50,
5  "destination": "13035551234"
6}
Copy

Code 2000 - Declined:

1{
2  "code": 2000,
3  "message": "Bid declined - call type not accepted",
4  "bid_amount": 0
5}
Copy

Code 3000 - No Capacity:

1{
2  "code": 3000,
3  "message": "No capacity available",
4  "bid_amount": 0
5}
Copy

Code 4000 - Invalid Request:

1{
2  "code": 4000,
3  "message": "Invalid request - missing required CallerId parameter",
4  "bid_amount": 0
5}
Copy

Code 5000 - System Error:

1{
2  "code": 5000,
3  "message": "System error - please try again",
4  "bid_amount": 0
5}
Copy

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: Implement Request Logic

Create a function to send bid requests:

1async function sendCallGridBidRequest(gridId, callData) {
2  const endpoint = `https://bid.callgrid.com/api/bid/${gridId}`;
3  
4  const requestBody = {
5    CallerId: callData.phoneNumber,
6    InboundStateCode: callData.state
7  };
8  
9  try {
10    const response = await fetch(endpoint, {
11      method: 'POST',
12      headers: {
13        'Content-Type': 'application/json',
14        'Accept': 'application/json'
15      },
16      body: JSON.stringify(requestBody),
17      timeout: 10000 // 10 second timeout
18    });
19    
20    const data = await response.json();
21    return data;
22  } catch (error) {
23    console.error('CallGrid bid request failed:', error);
24    return { code: 5000, message: 'Request timeout or network error' };
25  }
26}
Copy

Step 3: Handle Bid Responses

Implement logic to handle different response codes:

1function handleBidResponse(bidResponse, call) {
2  switch (bidResponse.code) {
3    case 1000:
4      // Bid accepted - route call
5      console.log(`Bid accepted: $${bidResponse.bid_amount}`);
6      routeCall(call, bidResponse.destination);
7      break;
8      
9    case 2000:
10      // Bid declined - try next buyer
11      console.log('Bid declined, trying next buyer');
12      tryNextBuyer(call);
13      break;
14      
15    case 3000:
16      // No capacity - try next buyer
17      console.log('Buyer has no capacity, trying next buyer');
18      tryNextBuyer(call);
19      break;
20      
21    case 4000:
22      // Invalid request - log error and fix
23      console.error('Invalid request format:', bidResponse.message);
24      logError(bidResponse);
25      break;
26      
27    case 5000:
28      // System error - implement fallback
29      console.error('System error:', bidResponse.message);
30      useFallbackRouting(call);
31      break;
32      
33    default:
34      console.error('Unknown response code:', bidResponse.code);
35      useFallbackRouting(call);
36  }
37}
Copy

Step 4: Implement Timeout Handling

Always implement timeout handling for bid requests:

1const BID_TIMEOUT = 10000; // 10 seconds
2
3async function sendBidRequestWithTimeout(gridId, callData) {
4  const timeoutPromise = new Promise((_, reject) =>
5    setTimeout(() => reject(new Error('Bid request timeout')), BID_TIMEOUT)
6  );
7  
8  const bidPromise = sendCallGridBidRequest(gridId, callData);
9  
10  try {
11    const result = await Promise.race([bidPromise, timeoutPromise]);
12    return result;
13  } catch (error) {
14    console.error('Bid request timeout:', error);
15    return { code: 3000, message: 'Timeout - no response from buyer' };
16  }
17}
Copy

Best Practices

Request Optimization

Send Complete Data:

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

Implement Caching:

• Cache buyer responses for similar calls
• Reduce redundant API calls
• Respect buyer capacity signals (code 3000)

Handle Timeouts Gracefully:

• Set reasonable timeout (10 seconds recommended)
• Implement fallback routing for timeouts
• Log timeout occurrences for monitoring

Response Handling

Accept Only Profitable Bids:

1function shouldAcceptBid(bidResponse, minimumBid = 15.00) {
2  return bidResponse.code === 1000 && 
3         bidResponse.bid_amount >= minimumBid;
4}
Copy

Implement Retry Logic for System Errors:

1async function bidWithRetry(gridId, callData, maxRetries = 2) {
2  for (let attempt = 0; attempt <= maxRetries; attempt++) {
3    const response = await sendCallGridBidRequest(gridId, callData);
4    
5    if (response.code !== 5000) {
6      return response;
7    }
8    
9    // Wait before retry (exponential backoff)
10    await sleep(Math.pow(2, attempt) * 1000);
11  }
12  
13  return { code: 5000, message: 'Max retries exceeded' };
14}
Copy

Multi-Buyer Strategy

Implement waterfall logic to maximize revenue:

1async function waterfallBidding(call, buyers) {
2  for (const buyer of buyers) {
3    const response = await sendCallGridBidRequest(buyer.gridId, call);
4    
5    if (response.code === 1000 && response.bid_amount >= buyer.minBid) {
6      console.log(`Accepted bid from ${buyer.name}: $${response.bid_amount}`);
7      return { buyer, response };
8    }
9  }
10  
11  console.log('No buyers accepted the call');
12  return null;
13}
Copy

Testing Your Integration

Test Request

Use this test request to verify your integration:

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

Expected Test Response

1{
2  "code": 1000,
3  "message": "Bid accepted",
4  "bid_amount": 25.50,
5  "destination": "13035551234",
6  "timestamp": "2025-09-30T15:30:00Z"
7}
Copy

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)

✓ Implement fallback routing for declined bids

✓ Log all bid requests and responses for debugging

✓ Monitor bid acceptance rates and revenue

Troubleshooting

Common Issues

Issue: 4000 - Invalid Request

Cause: Missing or improperly formatted CallerId parameter

Solution: Ensure CallerId is included and formatted correctly (10-digit number)

Example: Use "3035551234" not "(303) 555-1234"

Issue: 5000 - System Error

Cause: Network issues, buyer system downtime, or timeout

Solution: Implement retry logic and fallback routing

Action: Check buyer system status and contact support if persistent

Issue: Consistent 2000 - Bid Declined

Cause: Calls don't match buyer's acceptance criteria

Solution: Verify with buyer their geographic, quality, or call type requirements

Action: Review and adjust the calls you're sending to this buyer

Issue: Timeout (No Response)

Cause: Network latency or buyer system performance issues

Solution: Implement proper timeout handling (10 seconds)

Action: Use fallback routing and log for monitoring

Debugging Tips

Enable Request/Response Logging:

1function logBidRequest(gridId, request, response) {
2  console.log({
3    timestamp: new Date().toISOString(),
4    gridId: gridId,
5    request: request,
6    response: response,
7    duration: response.duration + 'ms'
8  });
9}
Copy

Monitor Key Metrics:

• Bid acceptance rate (code 1000)
• Average response time
• Timeout rate
• Revenue per call
• Buyer-specific performance

Test in Stages:

1. Test with single buyer first
2. Verify all response codes work correctly
3. Add timeout handling
4. Implement multi-buyer logic
5. Deploy to production with monitoring

Rate Limits and Performance

Rate Limits

CallGrid does not impose strict rate limits on bid requests, but best practices include:

• Maximum 100 simultaneous requests per Grid ID
• Implement connection pooling for high volume
• Use reasonable timeout values (10 seconds)
• Don't retry more than 2-3 times for errors

Performance Expectations

Average Response Time: 200-500ms

Maximum Response Time: 10 seconds (timeout)

Recommended Timeout: 10 seconds

Concurrent Requests: Up to 100 per Grid ID

Security Considerations

Request Security

• Always use HTTPS for all API requests
• Validate Grid IDs before making requests
• Implement request logging for audit trails
• Don't expose Grid IDs in client-side code

Data Privacy

• Only send required call data parameters
• Don't include PII beyond what's necessary
• Follow TCPA and data privacy regulations
• Implement data retention policies

API Reference Summary

Endpoint

1POST https://bid.callgrid.com/api/bid/{Grid-ID}
Copy

Request Headers

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

Request Body

1{
2  "CallerId": "string (required)",
3  "InboundStateCode": "string (optional)"
4}
Copy

Response Body

1{
2  "code": "integer",
3  "message": "string",
4  "bid_amount": "float",
5  "destination": "string",
6  "timestamp": "string (ISO 8601)"
7}
Copy

Response Codes

• 1000 - Bid Accepted
• 2000 - Bid Declined
• 3000 - No Capacity
• 4000 - Invalid Request
• 5000 - System Error

Additional Resources

API Documentation:

• CallGrid API Documentation
• CallGrid API Reference

Platform-Specific Guides:

• 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
• Live Chat: Available in CallGrid dashboard

Support

For technical assistance with the CallGrid Bid API:

1. Review this documentation and test your integration
2. Check the API documentation for updates
3. Contact your CallGrid buyer to verify Grid ID and requirements
4. 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