# Marchex Real Time Bidding Integration

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

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

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

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

## Prerequisites

Before setting up this integration, ensure you have:

- An active Marchex account with RTB permissions
- Your Marchex Partner ID from your account
- Understanding of search terms and types relevant to your call traffic
- Knowledge of your call routing and monetization strategy

## Configuration Steps

### Step 1: Obtain Marchex Account Information

1. Log into your Marchex account
2. Navigate to your partner/publisher settings
3. Locate your **Partner ID** (unique identifier for your account)
4. Identify the **Search Terms** that best describe your call traffic
5. Determine the appropriate **Search Type** for your campaigns

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

##### Required Configuration Fields

**Partner ID** _(Required)_

- Enter your Marchex Partner ID
- This is your unique identifier in the Marchex system
- Example: 123456789

**Search Term** _(Required)_

- Enter the search term that best describes your call traffic
- This helps Marchex match your calls to appropriate buyers
- Example: auto insurance, home loans, legal services

**Search Type** _(Required)_

- Enter the search type category for your calls
- This defines the vertical or industry category
- Example: insurance, finance, legal, healthcare

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

#### Phase 2: Advanced Configuration

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

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

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

https://services.marchex.com/mcm/listings?partnerId=PartnerID&searchType=Type&searchTerm=Term&radius=50&zip=[[tag:InboundZipCode]]

**HTTP Method**

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

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

- **partnerId**: Your Marchex Partner ID
- **searchType**: The search type category
- **searchTerm**: The search term for your calls
- **radius**: Search radius (default 50 miles)
- **zip**: Dynamic zip code from [[tag:InboundZipCode]]

##### Acceptance Parsing

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

![](https://callgrid.com/api/media/file/MarchexAP.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 publisher payouts using the 0.publisherPayout field:

- **Field**: 0.publisherPayout
- **Condition**: Greater Than
- **Value**: 0

This configuration accepts bids when Marchex responds with a publisher payout amount greater than 0.

##### Bid Response Handling

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

- **Property Path**: Enter the JSON path to the bid data
- **Common Fields**:
  - 0.publisherPayout - The payout amount offered for the call
  - 0.phoneNumber - Phone number where the call should be routed
  - 0.listingId - The Marchex listing that accepted the bid
  - 0.businessName - Name of the business receiving the call

##### Testing Your Configuration

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

To test your integration:

1. Fill in your **Partner ID**, **Search Term**, and **Search Type**
2. In the webhook testing section, provide test values:
  - **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 Marchex
5. Confirm the acceptance parsing works correctly with the response

The built-in webhook test will send a test bid request to Marchex 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 Marchex's MCM (Marchex Call Marketplace) system:

1. **Bid Request**: CallGrid sends call information to Marchex's listings API
2. **Marketplace Evaluation**: Marchex evaluates the call against available listings
3. **Bid Response**: Marchex responds with available listings and payout information
4. **Acceptance Decision**: Your system evaluates the bid response against your criteria
5. **Call Routing**: If accepted, the call is routed to the Marchex destination

### Bid Response Structure

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

[

{

"listingId": "abc123def456",

"businessName": "Example Insurance Agency",

"phoneNumber": "18005551234",

"publisherPayout": 25.50,

"searchTerm": "auto insurance",

"searchType": "insurance",

"zipCode": "90210",

"radius": 50

}

]

## Advanced Configuration Examples

### Example 1: Basic Payout Acceptance

**Acceptance Criteria:**

- Field: 0.publisherPayout
- Condition: Greater Than
- Value: 0

This configuration accepts calls when Marchex offers any payout amount.

### Example 2: Minimum Payout Threshold

**Acceptance Criteria:**

- Field: 0.publisherPayout
- Condition: Greater Than
- Value: 20.00

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

### Example 3: Business Name Validation

**Acceptance Criteria:**

- Field: 0.businessName
- Condition: Not Equals
- Value: null

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

### Example 4: Multiple Acceptance Criteria

You can add multiple criteria to ensure both valid listings and minimum payouts:

**Criteria 1:**

- Field: 0.publisherPayout
- Condition: Greater Than
- Value: 15.00

**Criteria 2:**

- Field: 0.phoneNumber
- Condition: Not Equals
- Value: null

## Search Term Optimization

### Popular Search Terms by Vertical

**Insurance:**

- auto insurance
- home insurance
- life insurance
- health insurance

**Finance:**

- personal loans
- mortgage
- debt consolidation
- credit repair

**Legal:**

- personal injury
- divorce lawyer
- criminal defense
- bankruptcy

**Healthcare:**

- weight loss
- addiction treatment
- mental health
- physical therapy

### Search Type Categories

- insurance - All insurance-related calls
- finance - Financial services and lending
- legal - Legal services and attorneys
- healthcare - Medical and wellness services
- home improvement - Contractors and home services
- automotive - Auto services and dealerships

## Advanced Use Cases

### Multi-Vertical Strategy

Configure multiple CallGrid destinations, each targeting different search terms and types to maximize coverage across various verticals.

### Geographic Optimization

Leverage the automatic zip code parameter to route calls to businesses optimized for specific geographic regions.

### Payout Optimization

Use payout thresholds to ensure calls are only routed when they meet your minimum revenue requirements.

## Troubleshooting

### Common Issues

**Invalid Partner ID**

- Verify your Partner ID is correct and matches your Marchex account
- Ensure your Marchex account is active and has RTB permissions
- Check that the Partner ID format is correct

**No Listings Returned**

- Verify your search terms are relevant and commonly searched
- Check that your search type matches your search term category
- Ensure there are active listings in your target geographic area

**Low Payout Issues**

- Review your search terms to ensure they target high-value verticals
- Check that your geographic targeting aligns with high-payout areas
- Verify that your call quality meets Marchex buyer requirements

**Geographic Targeting Problems**

- Ensure zip codes are being passed correctly in the InboundZipCode tag
- Verify the radius setting is appropriate for your market
- Check that there are active listings in your target areas

### Testing the Integration

**Template Configuration Test**:

1. After entering all required fields, 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:InboundZipCode**: Enter a test zip code (e.g., 90210)
2. Click **Run Webhook** to test the connection
3. Verify the bid response contains expected listing 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 payout acceptance conditions

## Best Practices

### Search Term Strategy

- Use specific, high-intent search terms for better payout rates
- Test different search terms to find optimal performance
- Monitor search term performance and adjust based on results

### Geographic Targeting

- Consider population density when setting radius parameters
- Test different geographic markets to maximize revenue
- Monitor geographic performance to identify high-value areas

### Revenue Optimization

- Set competitive but realistic payout thresholds
- Track performance metrics across different verticals
- Adjust search terms and types based on marketplace demand

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