# Phonexa Real Time Bidding Integration

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

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

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.

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

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

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

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

[https://Subdomain.phonexa.com/lead/](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.

![](https://callgrid.com/api/media/file/PhonexaAP.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 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

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

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:
  - **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:
  - **tag:ContactFirstName**: John
  - **tag:ContactLastName**: Smith
  - **tag:ContactEmail**: [test@example.com](mailto: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

##