Phonexa Real Time Bidding Integration

The Phonexa Real Time Bidding (RTB) integration enables you to send bid requests to Phonexa's lead marketplace in real-time. This integration allows you to monetize your call traffic by submitting leads to Phonexa buyers who can bid on them dynamically based on contact information, geographic data, and demographic details.

Prerequisites

Before setting up this integration, ensure you have:

• An active Phonexa account with RTB permissions
• Your Phonexa account ID and subdomain information
• Product ID from your Phonexa account
• API password or template password for authentication
• Understanding of your lead generation and monetization strategy

Configuration Steps

Step 1: Obtain Phonexa Account Information

1. Log into your Phonexa account
2. Navigate to your account settings or API configuration
3. Locate your Account ID (numeric identifier)
4. Note your Subdomain (your unique Phonexa identifier)
5. Find the Product ID for the product/vertical you want to submit leads to
6. Generate or locate your API password (template password)

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

Required Configuration Fields

ID (Required)

• Enter your Phonexa account ID
• This is your numeric account identifier in the Phonexa system
• Example: 123456

Subdomain (Required)

• Enter your Phonexa subdomain
• This is your unique identifier for your Phonexa instance
• Example: yourcompany (if your Phonexa URL is yourcompany.phonexa.com)

Product ID (Required)

• Enter the Product ID from your Phonexa account
• This identifies which product/vertical will receive your leads
• Example: 789012

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

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

https://Subdomain.phonexa.com/lead/

HTTP Method

• Method: POST (automatically configured)
• Content-Type: application/x-www-form-urlencoded (automatically configured)
• Timeout: 10 seconds (default, adjustable)

Form Body Parameters The integration automatically includes these form parameters with dynamic values:

apiID=ID&apiPassword=TEMPLATE_PASSWORD&productId=ID&price=0&firstName=[[tag:ContactFirstName]]&lastName=[[tag:ContactLastName]]&email=[[tag:ContactEmail]]&zip=[[tag:InboundZip]]&dob=[[tag:ContactDOB]]&state=[[tag:InboundState]]&phoneNumber=[[tag:InboundNumber]]

Dynamic Parameters Included:

• ContactFirstName: Lead's first name
• ContactLastName: Lead's last name
• ContactEmail: Lead's email address
• InboundZip: Lead's zip code
• ContactDOB: Lead's date of birth
• InboundState: Lead's state
• InboundNumber: Lead's phone number

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 bid amounts using the bid field:

• Field: bid
• Condition: Greater Than
• Value: 0

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

Bid Response Handling

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

• Property Path: Enter the JSON path to the bid data
• Common Fields:
• • bid - The bid amount offered for the lead
  • status - Response status indicating bid acceptance
  • leadId - The Phonexa lead ID if accepted
  • message - Additional information about the bid

Testing Your Configuration

To test your integration:

1. Fill in your ID, Subdomain, and Product ID
2. In the webhook testing section, provide test values for all contact fields:
3. • tag:ContactFirstName: Enter a test first name (e.g., John)
   • tag:ContactLastName: Enter a test last name (e.g., Smith)
   • tag:ContactEmail: Enter a test email (e.g., test@example.com)
   • tag:InboundZip: Enter a test zip code (e.g., 90210)
   • tag:ContactDOB: Enter a test date of birth (e.g., 1980-01-01)
   • tag:InboundState: Enter a test state (e.g., CA)
   • tag:InboundNumber: 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 Phonexa
5. Confirm the acceptance parsing works correctly with the response

The built-in webhook test will send a test lead to Phonexa and show you whether bids would be accepted based on their response.

How It Works

Real-Time Lead Submission Process

The integration facilitates real-time lead submission through Phonexa's Lead API:

1. Lead Submission: CallGrid sends complete lead information to Phonexa's lead endpoint
2. Lead Evaluation: Phonexa evaluates the lead against buyer criteria and requirements
3. Bid Response: Phonexa responds with bid information and acceptance status
4. Acceptance Decision: Your system evaluates the bid response against your criteria
5. Lead Processing: If accepted, the lead is processed and routed to the winning buyer

Bid Response Structure

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

{

  "bid": 25.50,

  "status": "accepted",

  "leadId": "PX123456789",

  "message": "Lead accepted successfully",

  "productId": "789012",

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

}

Advanced Configuration Examples

Example 1: Basic Bid Acceptance

Acceptance Criteria:

• Field: bid
• Condition: Greater Than
• Value: 0

This configuration accepts leads when Phonexa offers any bid amount.

Example 2: Minimum Bid Threshold

Acceptance Criteria:

• Field: bid
• Condition: Greater Than
• Value: 20.00

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

Example 3: Status-Based Acceptance

Acceptance Criteria:

• Field: status
• Condition: Equals
• Value: accepted

This configuration accepts bids based on Phonexa's status response.

Example 4: Multiple Acceptance Criteria

You can add multiple criteria to ensure both successful status and minimum bid:

Criteria 1:

• Field: status
• Condition: Equals
• Value: accepted

Criteria 2:

• Field: bid
• Condition: Greater Than
• Value: 15.00

Lead Data Requirements

Required Fields

All the following fields are automatically included in the form submission:

• firstName: Lead's first name
• lastName: Lead's last name
• email: Lead's email address
• zip: Lead's zip code
• dob: Lead's date of birth
• state: Lead's state
• phoneNumber: Lead's phone number

Data Format Requirements

• Date of Birth: Use YYYY-MM-DD format (e.g., 1980-01-01)
• Phone Number: Use 10-digit format without formatting (e.g., 5551234567)
• State: Use 2-letter state codes (e.g., CA, NY, FL)
• Zip Code: Use 5-digit zip codes (e.g., 90210)

Advanced Use Cases

Multi-Product Strategy

Configure multiple CallGrid destinations, each targeting different Phonexa products to maximize coverage across various verticals.

Lead Quality Optimization

Ensure lead data quality meets Phonexa buyer requirements for better acceptance rates and higher bids.

Geographic Targeting

Leverage geographic data (zip code and state) to route leads to buyers optimized for specific regions.

Troubleshooting

Common Issues

Authentication Failures

• Verify your API ID and password are correct
• Ensure your Phonexa account is active and has API access
• Check that the API password has not expired

Invalid Product ID

• Confirm your Product ID exists in your Phonexa account
• Verify the Product ID is active and accepting leads
• Check that the product is properly configured for your account

Lead Rejection Issues

• Verify all required lead fields are being populated correctly
• Check that lead data meets Phonexa quality requirements
• Ensure date formats and field formats are correct

Low Bid Issues

• Review lead quality to ensure it meets buyer standards
• Check that geographic targeting aligns with buyer preferences
• Verify that lead data is complete and accurate

Testing the Integration

Template Configuration Test:

1. After entering all required fields, click Save Webhook
2. Review the auto-generated URL and form parameters

Built-in Webhook Test:

1. In the advanced configuration screen, provide test values for all contact fields:
2. • tag:ContactFirstName: John
   • tag:ContactLastName: Smith
   • tag:ContactEmail: test@example.com
   • tag:InboundZip: 90210
   • tag:ContactDOB: 1980-01-01
   • tag:InboundState: CA
   • tag:InboundNumber: 5551234567
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 lead submissions
2. Verify bid responses are being parsed correctly
3. Test lead routing based on bid acceptance conditions

Best Practices

Lead Quality Management

• Ensure all required fields are populated with accurate data
• Validate email addresses and phone numbers before submission
• Use consistent data formatting across all leads

Revenue Optimization

• Set competitive but realistic bid thresholds
• Track performance metrics across different products
• Monitor lead acceptance rates and adjust quality controls

Data Privacy and Compliance

• Ensure compliance with data privacy regulations (GDPR, CCPA, etc.)
• Implement proper consent mechanisms for lead data collection
• Maintain secure handling of personal information

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