The Queue Availability API: Let External Partners Check Your Capacity in Real Time
Every wasted call costs money. When a publisher routes a call to your center and no agents are available, the caller waits on hold, gets frustrated, and hangs up. The publisher paid to generate that lead. You paid to receive it. Nobody wins. The Queue Availability API eliminates this problem by giving publishers, networks like Retreaver and Ringba, and affiliate partners a real-time window into your actual agent capacity—before they ever route a call your way.
The Core Idea
Instead of blindly sending calls and hoping someone picks up, external partners query a public API endpoint to check how many agents are available in your queues right now. If agents are ready, they route the call. If not, they hold the lead until capacity opens up. The result: higher answer rates, lower abandonment, and zero wasted ad spend on calls that never connect.
What Is the Queue Availability API?
The Queue Availability API is a public, unauthenticated REST endpoint that returns the real-time availability status of any Publisher Queue in your AgentTech account. It was designed for one purpose: letting external systems make intelligent routing decisions based on your live agent capacity.
When a publisher or call network queries the endpoint, they receive a JSON response that tells them exactly how many agents are assigned to the target queues, how many are currently available to take a call, and a percentage-based availability score. No authentication tokens, no OAuth flows, no API keys to manage—just a simple GET request with the queue name and an optional caller ID.
GET /api.php?action=get_queue_availability&queue=publisher-name
GET /api.php?action=get_queue_availability&queue=publisher-name&callerid=6075551234
The endpoint is intentionally simple. Publishers and networks integrate with dozens of call centers; the last thing they want is a complex authentication scheme for a read-only availability check. By keeping it unauthenticated and GET-based, AgentTech makes integration a five-minute task instead of a multi-day project.
Why Real-Time Availability Matters for Inbound Call Centers
Inbound call centers that work with external publishers face a fundamental coordination problem. The publisher controls when calls arrive. The call center controls how many agents are staffed. Without a feedback loop between these two sides, you get predictable chaos:
Without the API
- Calls arrive when no agents are free
- Callers wait on hold for minutes
- Abandonment rates spike to 30%+
- Publisher pays for leads that never convert
- You pay for calls that never connect
With the API
- Calls only route when agents are ready
- Hold times drop to near zero
- Abandonment rates fall below 5%
- Publisher leads connect and convert
- Every dollar spent produces a conversation
The math is straightforward. If you're paying $15–$40 per inbound call from a publisher, and 25% of those calls abandon because no agent was available, you're burning a quarter of your media budget on dead calls. For a center taking 500 publisher calls a day at $25 each, that's $3,125 wasted daily—nearly $100,000 a month. The availability API eliminates this waste at the source.
Beyond Cost Savings
The benefits extend past budget. Caller experience improves dramatically when every call is answered promptly. Agent utilization stays high because calls arrive when they're actually ready. And publisher relationships strengthen because their leads convert at higher rates—making them more willing to send you their best traffic.
API Response Fields Explained
The API returns a compact JSON response with everything a publisher needs to make a routing decision. Here's a complete example response and what each field means:
{ "status": "success", "queue": "publisher-42-mediaco", "total_agents": 18, "available_agents": 7, "availability_percentage": 38.89, "status_breakdown": { "available": 7, "busy": 9, "away": 1, "offline": 1 }, "callerid": "6075551234", "area_code": "607", "state": "NY"}
Field Reference
Total number of agents assigned to the target queues for this Publisher Queue. Includes all statuses.
Agents currently in "Available" status and ready to accept the next inbound call right now.
Percentage of total agents that are currently available. Useful for threshold-based routing decisions.
Detailed count by agent status: available, busy (on a call), away (break/lunch), and offline.
When a caller ID is provided, the API extracts the area code and maps it to a U.S. state for geographic filtering.
Request status: "success" when the queue exists and data is returned, or "error" with a message if the queue is not found.
How Publishers Use the API
For direct publishers—media buyers who run their own ads and route calls via SIP—the integration is dead simple. Before initiating the SIP transfer, their system pings the availability endpoint. If available_agents is greater than zero, they send the call. If not, they either hold the caller in their own IVR, route to a backup buyer, or pause the ad campaign until capacity returns.
function shouldRouteCall(queueName, callerPhone) { response = httpGet( "https://dialer.agenttech.io/api.php" + "?action=get_queue_availability" + "&queue=" + queueName + "&callerid=" + callerPhone ); if (response.available_agents > 0) { // Agents are ready — route the call return true; } else { // No capacity — hold or redirect return false; }}
Smart publishers take it further. They use the availability_percentage field to throttle their ad spend dynamically. When availability is above 50%, they bid aggressively. When it drops below 20%, they scale back campaigns. When it hits zero, they pause entirely. This feedback loop keeps their cost-per-acquisition predictable and your queues properly loaded.
Integration with Retreaver and Ringba
Most large-scale inbound call operations don't work with publishers directly—they use call tracking and routing platforms like Retreaver and Ringba as intermediaries. These platforms sit between publishers and call buyers, handling number provisioning, call attribution, and real-time routing decisions.
Both Retreaver and Ringba support pre-call "ping" integrations, where they query a buyer's availability before routing a call. AgentTech's Queue Availability API plugs directly into this workflow:
The Ping Flow: Network → API → Route
A publisher-generated call hits Retreaver or Ringba. The platform needs to decide which buyer should receive it.
The network sends a GET request to your Queue Availability endpoint, including the caller's phone number for geographic filtering.
AgentTech responds with total agents, available agents, status breakdown, and the caller's detected state.
If agents are available, the call routes to your SIP address. If not, the network tries the next buyer in the waterfall or holds the call.
In Retreaver, you configure a "Ping URL" on your buyer target. In Ringba, it's set up as a "Ping Tree" node. Both platforms evaluate the JSON response and use the available_agents field to determine if your target is eligible for the call. This all happens in milliseconds—callers never notice.
Pro Tip: Waterfall Priority
Networks route calls through a "waterfall" of buyers ranked by payout. By responding accurately to pings, you only receive calls you can handle. This keeps your answer rate high, which in turn boosts your waterfall ranking—meaning networks send you more calls over time. Accurate availability data creates a positive feedback loop for your business.
Filtering by Skills, States, and Caller ID
Not all agents can handle all calls. A Medicare Supplement specialist shouldn't receive Medicare Advantage calls, and an agent licensed only in Florida can't help a caller from Texas. The Queue Availability API supports granular filtering so the availability count reflects agents who can actually serve the specific caller.
Filtering Capabilities
Caller ID & State Detection
Pass the callerid parameter and the API automatically extracts the area code, maps it to a U.S. state, and filters availability to agents licensed or assigned to that state. A call from a 607 area code shows only agents who can serve New York.
Skill-Based Routing
The availability count respects your queue's skill requirements. If a Publisher Queue targets an internal queue with "Medicare Advantage" as a required skill, only agents with that skill appear in the count—even if other agents in the same queue are idle.
Ping Delay Enforcement
The API respects each Publisher Queue's configured ping delay. If a publisher has a 15-second ping delay, the API only reports agents who have been idle for at least 15 seconds as "available." This ensures the tiering system described in the publisher scaling architecture works correctly at the API level.
{ "status": "success", "queue": "publisher-42-mediaco", "total_agents": 6, "available_agents": 3, "availability_percentage": 50.00, "status_breakdown": { "available": 3, "busy": 2, "away": 1, "offline": 0 }, "callerid": "6075551234", "area_code": "607", "state": "NY"}
Rate Limiting and Responsible Usage
Because the API is public and unauthenticated, AgentTech applies rate limiting to prevent abuse and ensure consistent response times for all customers. Rate limits are applied per Publisher Queue, not per IP address, so legitimate multi-server publisher setups aren't penalized.
For most integrations, the per-call pattern works best: the publisher pings the API once when a call comes in, makes the routing decision, and doesn't poll again until the next call. For publishers with extremely high call volume (hundreds per minute), we recommend caching the response for 2–5 seconds to avoid hitting rate limits while still maintaining near-real-time accuracy.
Global Queue Support
AgentTech supports two types of queues: Internal Queues (scoped to a single agency) and Global Queues (shared across multiple agencies). The Queue Availability API works with both.
When a Publisher Queue is configured to route to both internal and global queues, the API aggregates availability across all target queues. This means the total_agents and available_agents fields reflect the combined capacity of every queue the publisher can route to, regardless of whether those queues belong to one agency or five.
Multi-Queue Aggregation Example
total_agents: 20, available_agents: 8, availability_percentage: 40.00
This aggregation is critical for large operations where agents span multiple teams and agencies. The publisher doesn't need to know your internal queue structure—they just see a single availability number that reflects your total capacity to handle their calls.
Practical Integration: Step by Step
Whether you're a call center sharing the API with your publishers or a publisher integrating with an AgentTech-powered buyer, here's the complete setup process:
Create the Publisher Queue in AgentTech
Set up a Publisher Queue with a descriptive name (e.g., "premium-leads-inc"). Assign target queues, configure ping delay for tiering, and set billing parameters. The system generates the SIP address and API endpoint automatically.
Export the Integration Template
Click "Export to PDF" on the Publisher Queue to generate a complete integration document. It includes the SIP address, the ping API URL, expected response fields, and a sample JSON response. Send this directly to the publisher or network.
Publisher Configures Their Ping Integration
The publisher adds the API URL to their routing logic. For Retreaver, this goes into the "Ping URL" field on the buyer target. For Ringba, it's a node in their Ping Tree. For custom setups, they add an HTTP GET call before the SIP transfer.
Set the Routing Condition
The publisher sets a condition on the response: route the call if available_agents > 0. Some publishers use more sophisticated logic, like only routing when availability_percentage > 20 to ensure calls aren't queued behind other callers.
Test and Go Live
Run a few test pings to confirm the response looks correct and the routing condition works. Then activate the publisher queue and start receiving calls. Monitor the publisher performance metrics to validate that answer rates improve immediately.
Reducing Wasted Ad Spend with Availability-Aware Routing
The most impactful use of the Queue Availability API isn't just routing decisions—it's ad spend optimization. When publishers tie their campaign bidding to your real-time capacity, the entire economics of your inbound operation change.
The Availability-Aware Ad Spend Model
Publisher bids aggressively on Google/Facebook. Maximum ad spend. Every call connects immediately.
Publisher reduces bid amounts. Moderate spend. Most calls still connect within seconds.
Publisher drops bids to minimum. Minimal spend. Only high-intent clicks generate calls.
Publisher pauses campaigns entirely. Zero wasted spend. Ads resume when agents return.
This model is a game-changer for call centers that use click-to-call campaigns with number pooling. Instead of running ads 24/7 and hoping agents are available when calls come in, publishers synchronize their spend with your staffing. The result is near-perfect alignment between ad spend and agent capacity.
Real Impact Numbers
Call centers using availability-aware publisher integrations typically report 15–30% reductions in wasted ad spend, 20–40% improvements in answer rates, and measurably higher publisher satisfaction scores. When publishers see their leads converting because agents actually pick up, they send you more volume and better traffic.
Affiliate Network Integration Patterns
Beyond direct publishers and platforms like Retreaver and Ringba, affiliate networks also benefit from the Queue Availability API. Networks that aggregate multiple publishers under a single buyer relationship can use the API to manage call flow across their entire publisher base.
Centralized Ping
The network pings AgentTech once and distributes the availability status to all their publishers. Reduces API calls while keeping all publishers informed.
Per-Publisher Ping
Each publisher within the network pings independently using their own Publisher Queue. Best for networks where publishers have different priority levels.
Threshold Gating
Networks set minimum availability thresholds (e.g., 3+ agents available) before enabling any publisher in the group. Prevents oversaturation during low-capacity periods.
Dynamic Caps
Networks adjust per-publisher call caps in real time based on availability. High availability = higher caps. Low availability = tighter caps.
Key Takeaways
- The Queue Availability API gives publishers and networks real-time visibility into your agent capacity via a simple GET endpoint
- Response fields include total_agents, available_agents, availability_percentage, and a full status_breakdown—everything needed for routing decisions
- Caller ID filtering automatically maps area codes to states, ensuring availability reflects agents who can actually serve the caller
- Retreaver and Ringba integrate natively via their ping URL and ping tree features—setup takes minutes
- Rate limiting is per-queue and designed for production workloads—ping once per call or cache for high-volume scenarios
- Global queue support aggregates availability across multiple internal and shared queues for a single unified capacity number
- Availability-aware ad spend reduces waste by 15–30% when publishers tie bidding to your real-time capacity
The Queue Availability API turns your call center from a black box into a transparent, queryable service. Publishers stop guessing. Networks stop wasting calls. And your agents spend their time talking to callers instead of watching empty queues while calls pile up elsewhere. It's a simple endpoint that solves a billion-dollar industry problem: the disconnect between the people generating calls and the people answering them.
Ready to Open Your Availability to Partners?
AgentTech Dialer includes the Queue Availability API with every Publisher Queue—no add-ons, no per-request fees. Set up your first publisher integration in minutes.
Try AgentTech Dialer Now