# Ringba Real Time Bidding Integration

> The Ringba Real Time Bidding (RTB) integration enables you to send bid requests to Ringba's marketplace in real-time. 

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

The Ringba Real Time Bidding (RTB) integration enables you to send bid requests to Ringba's marketplace in real-time. This integration allows you to monetize your call traffic by submitting calls to Ringba buyers who can bid on them dynamically based on call characteristics, geographic data, and caller information.  
  
**Other Helpful Ringba Articles:**

1. [Posting Bids from Ringba to CallGrid using RTB](https://callgrid.com/knowledge-base/posting-bids-from-ringba-to-callgrid-using-rtb)
2. [Posting Conversions to Ringba from CallGrid](https://callgrid.com/knowledge-base/posting-conversions-to-ringba-from-callgrid)
3. [Receiving Conversion Events from CallGrid in Ringba](https://callgrid.com/knowledge-base/receiving-conversion-events-from-callgrid-in-ringba)
4. [Receiving Bids from Ringba in CallGrid](https://callgrid.com/knowledge-base/receiving-bids-from-ringba-in-callgrid)

![](https://callgrid.com/api/media/file/RingbaTemplate-1.png)

## Prerequisites

Before setting up this integration, ensure you have:

- An active Ringba account with RTB permissions
- Your Ringba RTB identifier from your account
- Understanding of your call routing and monetization strategy
- Knowledge of your target geographic markets

## Configuration Steps

### Step 1: Obtain Ringba RTB Information

1. Log into your Ringba account
2. Navigate to your RTB or marketplace settings
3. Locate your **RTB ID** (your unique identifier for RTB campaigns)
4. Ensure your account has RTB access and appropriate permissions
5. Verify that your RTB campaigns are active and accepting bids

### 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 **Ringba** from the Real Time Bidding templates
7. Fill in the required field:

##### Required Configuration Fields

**RTB ID** _(Required)_

- Enter your Ringba RTB identifier
- This is your unique identifier for RTB campaigns in Ringba
- Example: rtb123456

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.

##### Request Configuration

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

**URL Structure** The webhook URL is automatically generated based on your configuration:

https://rtb.ringba.com/v1/production/RTBID.json?CID=[[tag:CallerId]]&State=[[tag:VisitorStateCode|tag:InboundStateCode]]&ZipCode=[[tag:VisitorZipCode|tag:InboundZipCode]]&exposeCallerId=yes

**HTTP Method**

- **Method**: GET (automatically configured)
- **Timeout**: 10 seconds (default, adjustable)

**URL Parameters** The integration automatically includes these query parameters with dynamic values:

- **CID**: Caller ID from [[tag:CallerId]]
- **State**: State code with fallback logic - uses VisitorStateCode if available, otherwise InboundStateCode
- **ZipCode**: Zip code with fallback logic - uses VisitorZipCode if available, otherwise InboundZipCode
- **exposeCallerId**: Set to "yes" to expose caller ID to buyers

##### Dynamic Parameter Logic

The integration uses intelligent fallback logic for geographic parameters:

- **State Parameter**: [[tag:VisitorStateCode|tag:InboundStateCode]] - Uses visitor state if available, falls back to inbound state
- **ZipCode Parameter**: [[tag:VisitorZipCode|tag:InboundZipCode]] - Uses visitor zip if available, falls back to inbound zip

This ensures the most accurate geographic targeting for your calls.

##### Acceptance Parsing

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

![](https://callgrid.com/api/media/file/RingbaAP.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 bid amounts using the bidAmount field:

- **Field**: bidAmount
- **Condition**: Greater Than
- **Value**: 0

This configuration accepts bids when Ringba responds with a bid amount greater than 0.

##### Bid Response Handling

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

- **Property Path**: Enter the JSON path to the bid data
- **Common Fields**:
  - bidAmount - The bid amount offered for the call
  - targetNumber - Phone number where the call should be routed
  - campaignId - ID of the campaign that won the bid
  - buyerId - ID of the buyer making the offer

##### Testing Your Configuration

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

To test your integration:

1. Fill in your **RTB ID**
2. In the webhook testing section, provide test values for geographic targeting:
  - **tag:CallerId**: Enter a test phone number (e.g., 5551234567)
  - **tag:VisitorStateCode|tag:InboundStateCode**: Enter a test state code (e.g., CA)
  - **tag:VisitorZipCode|tag:InboundZipCode**: Enter a test zip code (e.g., 90210)
3. Click **Run Webhook** to test the connection
4. Verify the test passes and shows a proper bid response from Ringba
5. Confirm the acceptance parsing works correctly with the response

The built-in webhook test will send a test bid request to Ringba 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 Ringba's RTB API:

1. **Bid Request**: CallGrid sends call and geographic information to Ringba's RTB endpoint
2. **Campaign Evaluation**: Ringba evaluates the call against available campaigns and buyers
3. **Bid Response**: Ringba responds with the highest bid and routing information
4. **Acceptance Decision**: Your system evaluates the bid response against your criteria
5. **Call Routing**: If accepted, the call is routed to the winning buyer's target number

### Bid Response Structure

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

{

"bidAmount": 25.50,

"targetNumber": "18005551234",

"campaignId": "camp123456",

"buyerId": "buyer789",

"callerId": "5551234567",

"state": "CA",

"zipCode": "90210",

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

}

## Advanced Configuration Examples

### Example 1: Basic Bid Acceptance

**Acceptance Criteria:**

- Field: bidAmount
- Condition: Greater Than
- Value: 0

This configuration accepts calls when Ringba offers any bid amount.

### Example 2: Minimum Bid Threshold

**Acceptance Criteria:**

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

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

### Example 3: Campaign Validation

**Acceptance Criteria:**

- Field: campaignId
- Condition: Not Equals
- Value: null

This configuration ensures calls are only accepted when a valid campaign is matched.

### Example 4: Multiple Acceptance Criteria

You can add multiple criteria to ensure both valid campaigns and minimum bids:

**Criteria 1:**

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

**Criteria 2:**

- Field: targetNumber
- Condition: Not Equals
- Value: null

## Geographic Targeting

### State and Zip Code Optimization

Ringba's RTB system uses geographic data for intelligent targeting:

- **State-Level Targeting**: Campaigns can target specific states for regional optimization
- **Zip Code Precision**: Fine-grained targeting based on caller's zip code location
- **Fallback Logic**: Automatic fallback ensures geographic data is always provided

### Data Quality Best Practices

- Ensure accurate state code formatting (2-letter codes: CA, NY, FL, etc.)
- Use 5-digit zip codes for precise targeting
- Monitor geographic data quality to maximize bid responses

## Advanced Use Cases

### Multi-RTB Strategy

Configure multiple CallGrid destinations, each targeting different Ringba RTB campaigns to maximize coverage and competition.

### Geographic Optimization

Leverage Ringba's geographic targeting to route calls to buyers optimized for specific regions and markets.

### Performance-Based Routing

Use bid amount data to route calls to the highest-paying campaigns and optimize revenue.

## Troubleshooting

### Common Issues

**Invalid RTB ID**

- Verify your RTB ID is correct and matches your Ringba account
- Ensure your RTB campaigns are active and accepting bids
- Check that the RTB ID format is correct

**No Bid Responses**

- Ensure there are active campaigns in your Ringba RTB setup
- Verify campaign targeting criteria match your call characteristics
- Check that campaigns have available budget and capacity

**Geographic Data Issues**

- Verify state codes are in correct 2-letter format
- Ensure zip codes are valid 5-digit codes
- Check that geographic tags are being populated correctly

**Low Bid Amounts**

- Review call quality to ensure it meets buyer standards
- Check that geographic targeting aligns with high-value campaigns
- Verify that call characteristics match buyer preferences

### Testing the Integration

**Template Configuration Test**:

1. After entering RTB ID, click **Save Webhook**
2. Review the auto-generated URL and parameters

**Built-in Webhook Test**:

1. In the advanced configuration screen, provide test values:
  - **tag:CallerId**: Enter a test phone number (e.g., 5551234567)
  - **tag:VisitorStateCode|tag:InboundStateCode**: Enter a test state code (e.g., CA)
  - **tag:VisitorZipCode|tag:InboundZipCode**: Enter a test zip code (e.g., 90210)
2. Click **Run Webhook** to test the connection
3. Verify the bid response contains expected campaign 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 amount acceptance conditions

## Best Practices

### Campaign Optimization

- Monitor bid performance across different geographic markets
- Track campaign success rates and optimize targeting accordingly
- Ensure call quality standards meet buyer requirements

### Revenue Maximization

- Set competitive but realistic bid thresholds
- Monitor market rates and adjust expectations accordingly
- Track performance metrics across different RTB campaigns

### Geographic Strategy

- Test different geographic markets to identify high-value areas
- Monitor state and zip code performance for optimization opportunities
- Adjust geographic targeting based on campaign 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 the integration using the built-in webhook test feature
4. Contact CallGrid support with integration details