Phonexa Real Time Bidding Integration

Overview#

This integration sends a real-time ping from a CallGrid destination to Phonexa's lead API. Phonexa evaluates the call's data against its buyers and returns a bid; CallGrid uses the response to accept or reject that destination for the call or bid, and can read the bid amount as variable revenue.

In CallGrid the destination's outbound request is its Ping, configured on the destination's Ping tab. It is not an integration webhook, which lives under Integrations > Webhooks and fires on call events.

Prerequisites#

• A Phonexa account with API access for the product you are selling into.
• From Phonexa: the product's API documentation, which lists the posting URL, credential fields, required fields and response samples. Phonexa generates it per product under Publisher Management > Setup > Publisher Products API and can export it as a PDF; ask the Phonexa account owner to send it. The CallGrid Phonexa template asks for the ID, Subdomain and Product ID.
• A CallGrid buyer for Phonexa and a campaign (static or bidding) that will route to the destination.
• If Phonexa restricts inbound IPs, the CallGrid static IPs (Step 2).

Step 1: Create the destination#

1. Buyers > Destinations > New Destination.
2. Settings > Basic Information: Name (for example "Phonexa - Auto Insurance"), Sub ID, Buyer, Timezone, Business Hours.
3. Call Settings > Phone Type: Phone or SIP with the number Phonexa gives you, or Variable if the product's sold response sample (in its API documentation) includes a routing number per call. Set Dial Attempts and Dial Timeout.
4. Revenue Settings: Revenue Type Variable to take the price from the ping response, or Fixed for a flat rate. Set Billable Type and duration to the Phonexa buyer's terms. Optional Min Revenue Amount sets a floor for this destination and overrides the campaign or routing group Minimum Revenue.
5. Ask the Phonexa account owner whether their call routing answers and plays ringback before connecting an agent. If it does, turn on Match Connect Duration under Call Settings > Advanced.
6. Save Destination. The Ping tab is enabled only after the destination is saved.

Step 2: Configure the Ping#

Open the destination's Ping tab.

Template#

Turn on the Ping integration and open the Ping Template picker. Select Phonexa and fill in its fields (ID, Subdomain, Product ID). To build the request by hand instead, set Method POST and URL https://<Subdomain>.phonexa.com/lead/ (the template's URL), and copy the body fields from your Phonexa product API spec. Either way, review the request before saving.

The template has no password field. If your product API spec lists a credential field, such as a password, add it to the body by hand.

Request Data#

Body: copy the field names from your Phonexa product API spec, and fill each value with a CallGrid tag, for example [[tag:InboundNumber]] for the caller's number or [[tag:InboundStateCode]] for the state.

Tag notes:

• Use real tag names. InboundNumber and InboundStateCode are default tags. The zip default tag is InboundZipCode; there is no InboundZip tag.
• For a zip field, you can create an alias such as ZipCode in Integrations > Tags (Alias Of tag:VisitorZipCode|tag:InboundZipCode), so the ping sends visitor zip when present and falls back to inbound zip.
• Contact fields (first name, last name, email, date of birth) only exist if a publisher posts them or an IVR, AI Agent or enrichment step fills them. Create them as custom tags with the exact casing publishers send; tag names are case sensitive. Use your account's own tag names.
• Macros: [[tag:Name]] string, [[number:Name]] number, [[hash:Name]] SHA-256, [[lchash:Name]] SHA-256 of the lowercased value, [[b64:value]] base64. Click the code icon in the URL bar or body editor to insert tags.
• Put credentials in the body or Headers as your product API spec requires. For OAuth-style token endpoints use Authorization instead.

Ping Testing#

Enter Test Variables for each tag used (for example InboundNumber 5551234567, ZipCode 90210, InboundStateCode CA) and click Run Ping. Check the raw response before building acceptance rules.

Acceptance Parsing#

Decides whether this destination is considered for the call or bid.

• Parsing Type: JSON (also Split, Regex, XML).
• Operators: Equals, Not Equal To, Greater Than, Less Than.
• Typical rule: bid Greater Than 0.
• For a floor, prefer the destination's Min Revenue Amount over a hard-coded Greater Than, so the floor also shows under Min Rev in the Pings report.

Turn on Rejection Protection only if you want a non-200 HTTP status not to reject the destination.

Field Mapping#

• Variable Revenue/Bid: price (the Phonexa template's mapping; acceptance still checks bid). If your Run Ping response carries the amount under a different name, map that field instead. If Phonexa returns cents, use Adjust Revenue.
• Variable Phone/SIP: the routing number field shown in the product's sold response sample, if Phonexa returns one.
• Variable Duration: the billable duration field, if returned.

Value Extraction#

Map Phonexa's lead id to PingResponseId and a rejection message to PingResponseCode, or to custom tags. Extracted values show on the ping record and can be used in a confirmation request.

Confirmation Ping/Post (if Phonexa requires a post step)#

Set Variable Ping ID to the lead id field so it is stored in [[tag:PingId]], then use it in the confirmation URL or body and set confirmation Acceptance. On bidding campaigns, Send Confirmation On (Auction Won or Call Won) controls when it fires. Whether this Phonexa product needs a post step depends on the product; check its API documentation or ask the Phonexa account owner.

Click Save Ping.

Step 3: Add the destination to routing#

1. Open the campaign > Routing tab and add the destination with a priority and weight, or add it to a routing group.
2. With variable pricing, Revenue, Average RPC or Dynamic RPC routing lets Phonexa's bid compete with other buyers. Dynamic RPC uses billable rate x live bid and is not Turbo compatible.
3. On bidding campaigns, Bid Settings (Passthrough margin, Max Bid) turn the Phonexa bid into the bid returned to your source.

Expected response shape#

Phonexa's response format varies by product. The product's API documentation includes sold, reject and error response samples; use them with a Run Ping to set the acceptance, mapping and value extraction paths. The CallGrid Phonexa template accepts on bid Greater Than 0 and maps revenue from price. Run Ping and check the field names in the response; if they differ, update the acceptance and mapping paths.

Timeouts#

• The Ping Timeout applies to this destination.
• Campaign > Sources > Configure source overrides > Webhook Timeout overrides destination ping timeouts for calls or bids from that source (the label still says Webhook). To exempt Phonexa, turn on Override Timeout on the Phonexa destination's Ping so it keeps its own timeout.
• The Webhook Timeout override's minimum is 1 second.

Troubleshooting#

Per-call ping requests and responses are visible on the call timeline and in the Pings report detail log (Ping ID, Code, Accepted, Ping ms, Bid $).

Compliance#

Before you send names, emails or dates of birth to a buyer, check with your own counsel that the consent you collect covers sharing that data with Phonexa's buyers. This is general information, not legal advice.

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "What was the average bid on my Phonexa destination over the last 7 days?" Claude and ChatGPT need the CallGrid connector turned on (setup guides for Claude and ChatGPT).

The connector is read only. It looks things up and reads your data. You make the changes in CallGrid.