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

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

8. 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://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.

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

To test your integration:

1. Fill in your Partner ID, Search Term, and Search Type
2. In the webhook testing section, provide test values:
3. • 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:
2. • 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