# Retreaver Real Time Bidding Integration

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

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

The Retreaver Real Time Bidding (RTB) integration enables you to send bid requests to Retreaver's marketplace in real-time. This integration allows you to monetize your call traffic by submitting calls to Retreaver buyers who can bid on them dynamically based on call characteristics and campaign requirements.

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

## Prerequisites

Before setting up this integration, ensure you have:

- An active Retreaver account with RTB permissions
- Your Retreaver RTB authentication key
- Publisher ID from your Retreaver account
- Understanding of your call routing and monetization strategy

## Configuration Steps

### Step 1: Obtain Retreaver Account Information

1. Log into your Retreaver account
2. Navigate to your RTB or publisher settings
3. Locate your **RTB Key** (authentication key for RTB requests)
4. Find your **Publisher ID** (your unique identifier for the routing service)
5. Ensure your account has RTB access and appropriate permissions

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

##### Required Configuration Fields

**RTB Key** _(Required)_

- Enter your Retreaver RTB authentication key
- This key authenticates your requests to Retreaver's RTB system
- Example: abc123def456ghi789jkl012

**Publisher ID** _(Required)_

- Enter your Publisher ID from Retreaver
- This is your unique identifier for the routing service
- Example: pub123456

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/RetreaverConfig.png)

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

https://rtb.retreaver.com/rtbs.json?key=Key&publisher_id=ID&caller_number=[[tag:CallerId]]

**HTTP Method**

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

**URL Parameters** The integration automatically includes these query parameters:

- **key**: Your Retreaver RTB authentication key
- **publisher_id**: Your Publisher ID
- **caller_number**: Dynamic caller ID from [[tag:CallerId]]

**JSON Request Body** The integration sends an empty JSON object {} in the request body as required by Retreaver's RTB API.

##### Acceptance Parsing

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

![](https://callgrid.com/api/media/file/RetreaverAP.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 campaign reservation status using the status field:

- **Field**: status
- **Condition**: Equals
- **Value**: reserved

This configuration accepts bids when Retreaver responds with a "reserved" status, indicating a successful campaign reservation.

##### Bid Response Handling

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

- **Property Path**: Enter the JSON path to the bid data
- **Common Fields**:
  - status - Response status indicating bid acceptance
  - campaign_id - ID of the campaign that accepted the bid
  - target_number - Phone number where the call should be routed
  - payout - The payout amount for the call

##### Testing Your Configuration

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

To test your integration:

1. Fill in your **RTB Key** and **Publisher ID**
2. In the webhook testing section, provide test values:
  - **tag:CallerId**: Enter a test phone number (e.g., 5551234567)
3. Click **Run Webhook** to test the connection
4. Verify the test passes and shows a proper bid response from Retreaver
5. Confirm the acceptance parsing works correctly with the response

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

1. **Bid Request**: CallGrid sends call information to Retreaver's RTB endpoint
2. **Campaign Evaluation**: Retreaver evaluates the call against available campaigns
3. **Bid Response**: Retreaver responds with campaign reservation status 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 campaign's target number

### Bid Response Structure

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

{

"status": "reserved",

"campaign_id": "12345",

"target_number": "18005551234",

"payout": 25.50,

"caller_number": "5551234567",

"publisher_id": "pub123456",

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

}

## Response Status Values

### Common Status Responses

- **reserved**: Campaign successfully reserved - call should be routed
- **no_match**: No matching campaigns available for this call
- **rejected**: Call rejected due to campaign criteria
- **error**: System error occurred during bid processing

## Advanced Configuration Examples

### Example 1: Basic Status Acceptance

**Acceptance Criteria:**

- Field: status
- Condition: Equals
- Value: reserved

This configuration accepts calls only when Retreaver reserves a campaign.

### Example 2: Minimum Payout Threshold

**Acceptance Criteria:**

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

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

### Example 3: Campaign Validation

**Acceptance Criteria:**

- Field: campaign_id
- 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 successful status and minimum payout:

**Criteria 1:**

- Field: status
- Condition: Equals
- Value: reserved

**Criteria 2:**

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

## Advanced Use Cases

### Multi-Publisher Strategy

Configure multiple CallGrid destinations, each targeting different Retreaver publisher IDs to maximize coverage and revenue optimization.

### Campaign Performance Tracking

Use campaign ID data to track performance across different Retreaver campaigns and optimize routing strategies.

### Payout Optimization

Leverage payout information to route calls to campaigns offering the best revenue potential.

## Troubleshooting

### Common Issues

**Authentication Failures**

- Verify your RTB Key is correct and current
- Ensure your Retreaver account has RTB permissions
- Check that the RTB Key has not expired

**Invalid Publisher ID**

- Confirm your Publisher ID exists in your Retreaver account
- Verify the Publisher ID is active and properly configured
- Check that the ID format matches Retreaver's requirements

**No Campaign Matches**

- Ensure there are active campaigns in your Retreaver account
- Verify campaign criteria match your call characteristics
- Check that campaigns have available capacity and budget

**Status Response Issues**

- Monitor response status values to understand bid outcomes
- Check campaign targeting settings in Retreaver
- Verify call quality meets campaign requirements

### Testing the Integration

**Template Configuration Test**:

1. After entering RTB Key and Publisher 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)
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 status acceptance conditions

## Best Practices

### Campaign Optimization

- Monitor campaign performance metrics to optimize targeting
- Ensure call quality standards meet campaign requirements
- Track conversion rates across different campaigns

### Revenue Maximization

- Set competitive but realistic payout thresholds
- Monitor campaign availability and adjust routing accordingly
- Track performance metrics to identify high-value campaigns

### Call Quality Management

- Maintain high call quality standards to ensure campaign approval
- Monitor call completion rates and campaign feedback
- Implement quality controls to protect campaign relationships

### 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