# CallGrid Real Time Call Bidding Integration

> The CallGrid Real Time Call Bidding (RTB) integration enables you to send bid requests to other CallGrid customers or partners in real-time.

Source: https://callgrid.com/knowledge-base/callgrid-real-time-call-bidding-integration
Last updated: 2025-09-23
Topics: Integrations, Real Time Bidding

The CallGrid Real Time Call Bidding (RTB) integration enables you to send bid requests to other CallGrid customers or partners in real-time. This integration allows you to monetize your call traffic by sending calls to buyers who can bid on them dynamically based on call characteristics and current market conditions.

![](https://callgrid.com/api/media/file/CallGridTemplate.png)

## Prerequisites

Before setting up this integration, ensure you have:

- An active CallGrid account with real-time bidding permissions
- The Grid ID of the CallGrid customer you want to send bids to
- Understanding of your call routing and monetization strategy
- Appropriate call volume and quality metrics

## Configuration Steps

### Step 1: Obtain Grid ID from Buyer

1. Contact the CallGrid customer you want to send bid requests to
2. Request their Grid ID for real-time bidding integration
3. Verify that they are set up to receive and process bid requests
4. Confirm the types of calls they are interested in purchasing

### Step 2: Configure CallGrid Integration

#### Phase 1: Basic Template Setup

1. Navigate to your CallGrid destination settings
2. Click the **Webhook** tab
3. Enable **Webhook Integration**
4. Enable **Template Mode**
5. Switch to **Real Time Bidding** template type
6. Select **CallGrid** from the Real Time Bidding templates
7. Fill in the required field:

##### Required Configuration Fields

**Grid ID** _(Required)_

- Enter the Grid ID of the CallGrid customer you want to send bids to
- This identifies which CallGrid account will receive your bid requests
- Example: abc123-def456-ghi789

1. Click **Save Webhook** to proceed to advanced configuration

#### Phase 2: Advanced Configuration (Optional)

After saving your basic template configuration, you'll be taken to the advanced configuration screen. The system automatically builds the webhook URL and request structure for you.

##### 

![](https://callgrid.com/api/media/file/CallgridConfigpng.png)

##### Request Configuration

**URL Structure** The webhook URL is automatically generated based on the Grid ID:

[https://bid.callgrid.com/api/bid/GridID](https://bid.callgrid.com/api/bid/GridID)

**HTTP Method**

- **Method**: POST (automatically configured)
- **Content-Type**: application/json (automatically configured)
- **Timeout**: 10 seconds (default, adjustable)

##### JSON Request Body

The integration automatically includes dynamic call parameters in the POST body:

{

"CallerId": "[[tag:CallerId]]",

"InboundStateCode": "[[tag:InboundStateCode]]"

}

These parameters provide essential call information to the receiving CallGrid customer for bid evaluation.

##### Acceptance Parsing

The most important setting is the acceptance criteria, which determines when bids are accepted.

![](https://callgrid.com/api/media/file/CallGridAP.png)

**Parsing Type**

- **Parse Type**: JSON (automatically configured)
- **Parse Field**: Configure which field from the bid response to evaluate

**Default Acceptance Criteria** The system is pre-configured to check for successful bid responses using the code field:

- **Field**: code
- **Condition**: Equals
- **Value**: 1000

This configuration accepts bids when the receiving CallGrid customer responds with a successful bid code (1000).

##### Bid Response Handling

**Response Field Options** Configure which fields from the CallGrid bid response to use for acceptance:

- **Property Path**: Enter the JSON path to the bid data
- **Common Fields**:
  - code - Response code indicating bid status
  - bid_amount - The bid amount offered for the call
  - destination - Where the call should be routed if accepted
  - message - Additional information about the bid

##### Testing Your Configuration

![](https://callgrid.com/api/media/file/CallGridTesting.png)

To test your integration:

1. Fill in the **Grid ID** in the configuration box
2. Provide test values for **tag:CallerId** and **tag:InboundStateCode**
3. Click **Run Webhook** button to test the connection
4. Verify the test passes and shows a proper bid response
5. Confirm the acceptance parsing works correctly with the response

The webhook test will send a test bid request to the specified CallGrid customer and show you whether bids would be accepted based on their response.

## How It Works

### Real-Time Bid Process

The integration facilitates real-time bidding through CallGrid's RTB system:

1. **Bid Request**: CallGrid sends call information to the specified Grid ID
2. **Bid Evaluation**: The receiving customer evaluates the call and responds with a bid
3. **Acceptance Decision**: Your system evaluates the bid response against your criteria
4. **Call Routing**: If accepted, the call is routed to the winning bidder's destination

### Bid Response Structure

CallGrid's RTB API returns bid responses in the following format:

{

"code": 1000,

"message": "Bid accepted",

"bid_amount": 25.50,

"destination": "12125551234",

"caller_id": "15551234567",

"state_code": "CA",

"timestamp": "2025-09-23T15:30:00Z"

}

## Response Codes

### Common Response Codes

- **1000**: Bid accepted - Call should be routed to the bidder
- **2000**: Bid declined - Bidder does not want this call
- **3000**: No capacity - Bidder cannot handle calls at this time
- **4000**: Invalid request - Problem with the bid request format
- **5000**: System error - Technical issue with the bidder's system

## Advanced Configuration Examples

### Example 1: Basic Bid Acceptance

**Acceptance Criteria:**

- Field: code
- Condition: Equals
- Value: 1000

This configuration accepts calls only when the bidder responds with a successful bid code.

### Example 2: Minimum Bid Amount

**Acceptance Criteria:**

- Field: bid_amount
- Condition: Greater Than
- Value: 20.00

This setup ensures calls are only accepted when the bid amount exceeds $20.00.

### Example 3: Multiple Acceptance Criteria

You can add multiple criteria to ensure both successful bids and minimum amounts:

**Criteria 1:**

- Field: code
- Condition: Equals
- Value: 1000

**Criteria 2:**

- Field: bid_amount
- Condition: Greater Than
- Value: 15.00

### Example 4: Message-Based Filtering

**Acceptance Criteria:**

- Field: message
- Condition: Contains
- Value: accepted

This configuration accepts bids based on message content confirmation.

## Advanced Use Cases

### Multi-Buyer Strategy

Configure multiple CallGrid destinations, each targeting different Grid IDs to maximize bid competition and revenue.

### Call Quality Optimization

Use bid responses to route high-quality calls to premium buyers who offer better rates.

### Geographic Targeting

Leverage the automatic state code parameter to route calls to buyers specialized in specific geographic regions.

## Troubleshooting

### Common Issues

**Invalid Grid ID**

- Verify the Grid ID is correct and belongs to an active CallGrid customer
- Confirm the receiving customer has RTB enabled and configured
- Check that the Grid ID format matches CallGrid's requirements

**No Bid Responses**

- Ensure the receiving CallGrid customer is actively accepting bids
- Verify their system is properly configured to handle bid requests
- Check that your call types match their buying criteria

**Bid Rejection Issues**

- Review your acceptance criteria to ensure they're not too restrictive
- Check the bid response codes to understand why bids are being declined
- Verify that bid amounts meet your minimum requirements

**Connection Timeouts**

- Check network connectivity to CallGrid's bidding platform
- Verify the receiving customer's system is responding within timeout limits
- Consider adjusting timeout settings if needed

### Testing the Integration

**Template Configuration Test**:

1. After entering Grid ID, click **Save Webhook**
2. Review the auto-generated URL and request structure

**Built-in Webhook Test**:

1. In the advanced configuration screen, provide test values for variables:
  - **tag:CallerId**: Enter a test phone number (e.g., 5551234567)
  - **tag:InboundStateCode**: Enter a test state code (e.g., CA)
2. Click **Run Webhook** to test the connection
3. Verify the bid response contains expected data
4. Test different acceptance criteria using the webhook test feature

**Live Integration Test**:

1. Monitor CallGrid logs for successful bid requests
2. Verify bid responses are being parsed correctly
3. Test call routing based on bid acceptance conditions

## Best Practices

### Bid Request Optimization

- Include relevant call metadata to help buyers make informed decisions
- Ensure call quality metrics are accurate and up-to-date
- Provide consistent call volume to maintain buyer relationships

### Response Handling

- Set appropriate timeout values for bid responses
- Implement fallback routing for declined bids
- Monitor bid acceptance rates and adjust criteria as needed

### Revenue Optimization

- Test different minimum bid amounts to optimize revenue
- Track performance metrics for different buyers
- Adjust routing strategies based on buyer response patterns

### CallGrid Support

If you need assistance with this integration:

1. Check the CallGrid logs for error messages
2. Verify all configuration parameters
3. Test API connectivity using provided curl commands
4. Contact CallGrid support with integration details