# CallGrid Bid API - Advanced RTB Integration Guide

> The CallGrid Bid API allows custom platforms and developers to send real-time bid requests to CallGrid campaigns.

Source: https://callgrid.com/knowledge-base/bid-api
Last updated: 2026-10-08
Topics: Integrations, Support

> **Note:** **⚠️ 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:

- [Posting Bids from Ringba to CallGrid using RTB](https://callgrid.com/knowledge-base/posting-bids-from-ringba-to-callgrid-using-rtb)
- [Posting Bids from Retreaver to CallGrid using RTB](https://callgrid.com/knowledge-base/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](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

```http
Content-Type: application/json
Accept: 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

```json
{
  "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:

```json
{
  "CallerId": "+15551234567",
  "InboundStateCode": "CO",
  "InboundZipCode": "80301",
  "age": 38,
  "CallQualityScore": "95",
  "CampaignType": "insurance",
  "PublisherId": "pub123"
  "pstn": false, // set to true if you cannot send via SIP
}
```

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:

```bash
curl -X POST https://bid.callgrid.com/api/bid/cm97s8hmv000ijt06r4djmije \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "CallerId": "+15551234567",
    "InboundStateCode": "CO"
  }'
```

Example with curl using GET:

```bash
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:

```json
{
  "id":"cmbidlwefyn02316t3nkxnelxz",
  "code":"1000",
  "message": "Success",
  "dynamicBid":"1.00",
  "dynamicDuration":"10",
  "expirationSeconds":"100",
  "payOnDuplicates":false,
  "dynamicSipAddress":"sip:cmbidlwefyn02316t3nkxnelxz@somewhere.sip.callgrid.com"
}
```

```json
{
  "id":"cmbidlwefyn02316t3nkxnelxz",
  "code":"1000",
  "message": "Success",
  "dynamicBid":"1.00",
  "dynamicDuration":"10",
  "expirationSeconds":"100",
  "payOnDuplicates":false,
  "dynamicPhoneNumber":"+1234567890"
}
```

### 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](https://callgrid.com/knowledge-base/call-bidding-error-codes-explained) 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](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](#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](#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](https://callgrid.com/knowledge-base/call-bidding-error-codes-explained)
- [CallGrid API Reference](https://api.callgrid.com/api/documentation)

**Platform-Specific Guides:**

- [Posting Bids from CallGrid to CallGrid](https://callgrid.com/knowledge-base/posting-bids-from-callgrid-to-callgrid-using-rtb)
- [Posting Bids from Ringba to CallGrid](https://callgrid.com/knowledge-base/posting-bids-from-ringba-to-callgrid-using-rtb)
- [Posting Bids from Retreaver to CallGrid](https://callgrid.com/knowledge-base/posting-bids-from-retreaver-to-callgrid-using-rtb)
- [Receiving Bids in CallGrid](https://callgrid.com/knowledge-base/posting-bids-from-callgrid-to-callgrid-using-rtb)

**Support:**

- Email: [support@callgrid.com](mailto:support@callgrid.com)
- Documentation: [callgrid.com/knowledge-base](https://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](mailto:support@callgrid.com)
- Integration assistance: Include your Grid ID and sample requests
- Bug reports: Provide full request/response logs and error messages.