REST-style JSON Role-scoped

API reference.

One endpoint, an action parameter, JSON back. The AgentTech Dialer API covers users, queues, skills, states, dispositions, scripts, call caps, operating hours, and call detail, plus a partner-facing availability check that lead vendors call before they send a call.

Open the dialer Talk to us about an integration

Everything the dialer can do, your systems can do too. Same data, same permissions, no exports.

How requests work

There is one endpoint. The action parameter names the operation, the rest of the parameters are its arguments, and every response is JSON.

Endpoint

All actions live at /api.php on your dialer host, for example https://dialer.agenttech.io/api.php. Pass action in the query string or the request body.

Request format

Send form-encoded parameters (application/x-www-form-urlencoded) or a JSON body (application/json). Batch actions that take nested lists use JSON.

Authentication and roles

Open a session with authenticate using dialer credentials, or send an API key on the partner-facing availability check. Permissions follow the user's role: agent, supervisor, agency admin, superadmin.

Ask a question. Get JSON back.

Every response carries a success flag. Failures add an error string that says what was wrong.

curl "https://dialer.agenttech.io/api.php" \
  -G -d action=get_queue_availability \
  -d queue=publisher-acme \
  -d callerid=2125551234 \
  -H "X-API-Key: $AGENTTECH_API_KEY"

{
  "success": true,
  "queue": "publisher-acme",
  "total_agents": 25,
  "publisher_acme_available_agents": 18,
  "unavailable_agents": 7,
  "availability_percentage": 72.0,
  "data": {
    "queue_info": { "id": 1, "name": "Acme" },
    "status_breakdown": {
      "Available": 15, "On A Call": 3, ...
    },
    "agents": [ ... ],
    "requirements": {
      "skills": [ ... ], "states": [ ... ]
    },
    "timestamp": "2026-01-15T14:23:45-05:00"
  }
}

Queue availability

The one action built for people outside your account. Lead vendors and call networks such as Retreaver and Ringba call it before routing, so a call only arrives when a licensed agent is free to take it.

GET /api.php?action=get_queue_availability

Accepts a dialer session or an X-API-Key header, and returns CORS headers so it can be called from a partner's browser or server. Works for standard, global, and publisher queues.

What comes back

Top-level counts. total_agents, unavailable_agents, availability_percentage, and an available-agents count whose field name is the queue identifier with hyphens replaced by underscores (publisher_acme_available_agents for publisher-acme).
status_breakdown. Agent count per status: Available, On A Call, Break, Lunch, Training, Offline.
agents. Each agent's status, priority, and, unless you turn them off, their skills with proficiency and their licensed states.
requirements. The skills (with minimum proficiency) and states the queue requires.
state_breakdown. With show_all_states=true, total and available agents for every US state.

Keep it fast

If you only need the counts, send skills=false&states=false. Use skill, state, or callerid to narrow the agent list instead of filtering on your side, and only ask for show_all_states when you need it.

Parameter	Required	Description
`queue`	Yes	The queue identifier shown on the queue's settings page. Works for standard, global, and publisher queues.
`callerid`	No	The caller's number, 10 or 11 digits, punctuation allowed. The caller's state is detected from the area code and agents are filtered to those licensed there. `state` takes precedence if both are sent.
`state`	No	Two-letter state code, for example `CA`. Returns only agents licensed in that state.
`skill`	No	Skill name, for example `Spanish`. Returns only agents with that skill.
`skills`	No	Include each agent's skills in the response. Default `true`.
`states`	No	Include each agent's states in the response. Default `true`.
`show_all_states`	No	Add a `state_breakdown` with total and available agents for every US state. Default `false`.

# Only agents licensed where the caller lives
curl ".../api.php" -G -d action=get_queue_availability \
  -d queue=publisher-acme \
  --data-urlencode "callerid=(212) 555-1234"

# Spanish-speaking agents licensed in California
curl ".../api.php" -G -d action=get_queue_availability \
  -d queue=publisher-acme -d skill=Spanish -d state=CA

# Counts only
curl ".../api.php" -G -d action=get_queue_availability \
  -d queue=publisher-acme -d skills=false -d states=false

Actions

Every customer-facing action, what it does, and who can call it. Full request and response samples for each are in the API Documentation page inside the dialer.

Sessions

Open a session with the same credentials you use in the dialer. Every other action runs with that user's role.

Action	Method	What it does	Who can call it
`authenticate`	POST	Open a session with a dialer username and password. Returns the user, role, agency, and current status.	Any user
`status`	GET	Check whether the session is valid and which user and role it belongs to.	Any user
`logout`	POST	End the session.	Any user

Users

Agents, supervisors, and admins, with the filters supervisors use to find them.

Action	Method	What it does	Who can call it
`get_users`	GET	List users. Filter by `agency_id`, `queue_id`, `department_id`, `role`, `status`, `skill_id`, or `state_id`.	Supervisor, agency admin, superadmin
`create_user`	POST	Create a user: `name`, `email`, `password`, `role`, `phone`, `notification_preference`.	Superadmin
`update_user`	PUT	Update a user's details, role, or password by `user_id`.	Superadmin
`delete_user`	DELETE	Remove a user by `user_id`.	Superadmin
`get_user_status`	GET	The current user's status and whether it allows calls.	Any user
`update_user_status`	PUT	Set the current user's status by `status_id`.	Any user
`get_user_states`	GET	States assigned to a user (`user_id`, defaults to the current user).	Any user
`save_settings`	POST	Save the current user's preferences.	Any user
`load_settings`	GET	Load the current user's preferences.	Any user

Agencies and departments

The organizational tree that queues, dispositions, and scripts are scoped to.

Action	Method	What it does	Who can call it
`get_agencies`	GET	List agencies.	Any user
`create_agency`	POST	Create an agency: `agency_name`, `is_active`.	Superadmin
`update_agency`	PUT	Rename or activate/deactivate an agency by `agency_id`.	Superadmin
`delete_agency`	DELETE	Delete an agency. Fails while it still has departments or users.	Superadmin
`get_agency_departments`	GET	Departments in an agency by `agency_id`.	Any user
`get_departments`	GET	List departments.	Any user
`create_department`	POST	Create a department: `department_name`, `agency_id`.	Supervisor, superadmin
`update_department`	POST	Rename a department by `department_id`.	Supervisor, superadmin
`delete_department`	POST	Delete a department by `department_id`.	Supervisor, superadmin
`update_department_assignments`	POST	Batch assign or unassign users to departments.	Supervisor, superadmin

Skills

Skills with proficiency levels. Queues can require a minimum proficiency before an agent is eligible.

Action	Method	What it does	Who can call it
`get_skills`	GET	List skills.	Any user
`create_skill`	POST	Create a skill: `skill_name`, `skill_type`, `agency_id`.	Superadmin
`update_skill`	PUT	Update a skill by `skill_id`.	Superadmin
`delete_skill`	DELETE	Delete a skill and remove it from every user.	Superadmin
`update_skill_assignments`	PUT	Assign, update, or unassign one skill across many users with a proficiency per user (JSON body).	Superadmin

States

Which states each agent is licensed to take calls from. Routing uses these to match a caller's state to a qualified agent.

Action	Method	What it does	Who can call it
`get_states`	GET	All US states with codes.	Any user
`get_user_state_assignments`	GET	Which users are qualified for which states. Filter by `user_id` or `state_id`.	Any user
`get_agency_state_assignments`	POST	State assignments for every user in an agency.	Agency admin (own agency), superadmin
`update_state_assignments`	PUT	Assign or unassign states across many users (JSON body).	Superadmin

Queues

Standard queues (an agency's agents), global queues (availability aggregated across teams), master queues with children, and external queues that hand calls to another platform.

Action	Method	What it does	Who can call it
`get_queues`	GET	List queues with routing strategy, overflow settings, and live agent counts. Filter by `role` (standard or global), `agency_id`, or `department_id`.	Supervisor, agency admin, superadmin
`get_user_queues`	GET	Active queues assigned to the current user.	Any user
`create_queue`	POST	Create a queue: `queue_name`, `department_id`, `description`, `is_active`, `priority`.	Supervisor, superadmin
`update_queue`	PUT	Update a queue by `queue_id`.	Supervisor, superadmin
`delete_queue`	DELETE	Delete a queue by `queue_id`.	Supervisor, superadmin
`assign_user_to_queue`	POST	Add a user to a queue with an optional `priority`.	Supervisor, superadmin
`remove_user_from_queue`	DELETE	Remove a user from a queue.	Supervisor, superadmin
`update_user_queues`	PUT	Replace all of a user's queue assignments and priorities in one call (JSON body).	Supervisor, superadmin
`get_queue_agents`	GET	Agents assigned to a queue and agents available to add.	Superadmin
`update_queue_agents`	PUT	Batch assign or unassign agents on a queue with priorities (JSON body).	Superadmin
`get_queue_skills`	GET	Skill requirements on a queue, with minimum proficiency and whether each is optional.	Superadmin
`update_queue_skills`	PUT	Batch change a queue's skill requirements (JSON body).	Superadmin
`get_queue_states`	GET	State requirements on a queue.	Superadmin
`update_queue_states`	PUT	Batch change a queue's state requirements (JSON body).	Superadmin
`get_master_queue_children`	GET	Child queues of a master queue.	Superadmin
`update_master_queue_children`	POST	Set which queues roll up under a master queue.	Superadmin
`update_master_queue_settings`	POST	Update a master queue's configuration.	Superadmin
`get_external_queues`	GET	External queues that hand calls to another dialer or platform.	Superadmin
`create_external_queue`	POST	Create an external queue.	Superadmin
`update_external_queue`	POST	Update an external queue.	Superadmin
`delete_external_queue`	POST	Delete an external queue.	Superadmin

Publisher queues

The entry points call sources route into. Each publisher queue targets one or more internal queues, so a partner can send calls without knowing how your floor is organized.

Action	Method	What it does	Who can call it
`get_publisher_queues`	GET	List publisher queues with their targets and status.	Agency admin, superadmin
`get_target_queues`	GET	Queues available as targets for a publisher queue.	Agency admin, superadmin
`create_publisher_queue`	POST	Create a publisher queue: `queue_name`, `description`, `agency_id`, `target_queue_ids[]`, `is_active`.	Agency admin, superadmin
`update_publisher_queue`	POST	Update a publisher queue's name, description, targets, or status.	Agency admin, superadmin
`delete_publisher_queue`	POST	Delete a publisher queue.	Agency admin, superadmin
`get_publisher_targets`	GET	Current target assignments for one publisher queue.	Agency admin, superadmin

Call caps

Concurrent, daily, weekly, and monthly limits on a queue, publisher, or agent.

Action	Method	What it does	Who can call it
`create_call_cap`	POST	Create a cap: `cap_name`, `target_type`, `target_id`, `max_concurrent_calls`, `daily_call_limit`, `weekly_call_limit`, `monthly_call_limit`, `is_active`.	Superadmin
`update_call_cap`	PUT	Update a cap by `cap_id`.	Superadmin
`delete_call_cap`	DELETE	Delete a cap by `cap_id`.	Superadmin
`get_call_cap_usage`	GET	Usage against a cap for a `date` (defaults to today).	Superadmin

Dispositions

Call outcomes, scoped to all agencies, one agency, a department, or a single queue.

Action	Method	What it does	Who can call it
`get_dispositions`	GET	All dispositions with their scope, category, and whether notes are required.	Any user
`get_disposition`	GET	One disposition by `disposition_id`.	Any user
`create_disposition`	POST	Create a disposition: `disposition_name`, `category` (positive, negative, follow_up, neutral), `description`, `requires_notes`, `is_active`, and optional `agency_id`, `department_id`, `queue_id` scope.	Superadmin
`update_disposition`	PUT	Update a disposition by `disposition_id`.	Superadmin
`delete_disposition`	DELETE	Delete a disposition. Blocked once it has been used on a call.	Superadmin
`get_agent_dispositions`	GET	Dispositions available to an agent for the current call.	Any user
`save_call_disposition`	POST	Record the disposition for a completed call.	Any user

Agent status

The status set your floor uses (Available, On A Call, Break, Training, and so on), whether each allows calls, and who is in which state right now.

Action	Method	What it does	Who can call it
`get_statuses`	GET	All statuses with color, icon, and whether the status allows calls.	Any user
`create_status`	POST	Create a status: `status_name`, `status_color`, `status_icon`, `status_description`, `allows_calls`.	Superadmin
`update_status`	PUT	Update a status by `status_id`.	Superadmin
`delete_status`	DELETE	Delete a status and clear it from every user.	Superadmin
`update_status_assignments`	PUT	Set the status of many users at once (JSON body).	Superadmin
`change_agent_status`	POST	Change an agent's current status.	Supervisor, superadmin
`get_next_available_agent`	GET	The next agent eligible to take a call under the queue's routing rules.	Supervisor, superadmin
`get_agent_current_call`	GET	The call an agent is on right now.	Supervisor, superadmin
`get_supervisor_agents`	GET	Every agent with live status, time in status, and current call, for supervisor dashboards.	Supervisor, superadmin

Scripts

Dynamic scripts that change by queue, call source, and agent, with the caller's details merged in.

Action	Method	What it does	Who can call it
`get_scripts`	GET	Scripts available to the current user.	Any user
`get_script`	GET	One script with its content and targeting.	Any user
`get_script_for_call`	GET	The script that applies to a given call's queue, source, and agent.	Any user
`create_script`	POST	Create a script.	Supervisor, superadmin
`update_script`	POST	Update a script.	Supervisor, superadmin
`duplicate_script`	POST	Copy a script as a starting point for a new one.	Supervisor, superadmin
`delete_script`	POST	Delete a script.	Supervisor, superadmin
`get_script_usage`	GET	How often each script is used.	Supervisor, superadmin

Phone numbers

Numbers on the account and which users or queues they are assigned to.

Action	Method	What it does	Who can call it
`get_phone_numbers`	GET	All numbers configured on the account.	Any user
`get_user_phone_numbers`	GET	Numbers assigned to users.	Any user
`get_queue_phone_numbers`	GET	Numbers assigned to queues.	Any user
`create_phone_number`	POST	Assign a number to a user or queue.	Superadmin
`update_phone_number`	POST	Change a number's assignment or settings.	Superadmin
`delete_phone_number`	POST	Remove a number assignment.	Superadmin

Operating hours

Calling windows per agency, queue, department, or agent, by day of week and time zone.

Action	Method	What it does	Who can call it
`get_operating_hours`	GET	Hours for an entity: `entity_type` (agency, queue, department, agent) and `entity_id`.	Any user
`update_operating_hours`	POST	Replace an entity's hours with a list of `day_of_week`, `is_active`, `open_time`, `close_time`, `timezone` (JSON body).	Agents for their own hours; superadmin for agency, queue, department

Calls

Detail for a single call. Recordings, transcripts, and compliance scores are on the contact timeline in the dialer.

Action	Method	What it does	Who can call it
`get_call_details`	GET	One call by `call_id`: direction, caller ID, called number, agent, queue, start, answer, and end times, total, talk, and ring durations, status, and recording.	Any user

Response codes

HTTP status tells you whether the request was accepted. The JSON body tells you what happened.

Code	Meaning
`200`	Success. Check the `success` field for the outcome of the action.
`400`	Bad request. A required parameter is missing or invalid; `error` says which.
`401`	Unauthorized. No session, or the credentials were wrong.
`403`	Forbidden. The session's role cannot perform this action.
`500`	Server error.

What teams build with it.

Most agencies start with an availability check for their lead vendors, then move floor administration and reporting onto the API.

Smarter call buying. Vendors ping get_queue_availability with the caller's number and only send calls a licensed agent can take.
Floor provisioning. Create users, assign skills and states, and place agents on queues from your HR or onboarding system.
Live wallboards. Poll get_supervisor_agents and get_queues for the same status and availability numbers the dialer shows.
Outcome sync. Read dispositions and call detail into your agency management system or data warehouse.

Included with every account

One endpoint: Every action at /api.php, form-encoded or JSON.
Role-scoped: Sessions carry the same permissions as your users.
No integration tier: API access is part of the $50 seat.

FAQs

API questions

How do I authenticate?

Sign in with your dialer credentials through the authenticate action to open a session, then send that session with every request. The API applies the same role permissions as the dialer itself: agent, supervisor, agency admin, and superadmin. The queue availability action also accepts an API key so partners can call it without a dialer login.

Is the API included in the $50 seat?

Yes. API access is included with every account. There is no separate integration tier.

Where are the full request and response examples?

This page lists every customer-facing action with its parameters and required role. Complete request and response samples for each one are in the API Documentation page inside the dialer, available to signed-in admins.

Can a lead vendor check our availability without an account?

Yes. The get_queue_availability action is built for that. Give the partner an API key and the identifier of the publisher queue they route into, and they can check live agent availability, skill coverage, and state licensing before sending a call.

Why are some endpoints not listed here?

Actions used by the platform's own telephony layer, such as writing call log records, routing telemetry, carrier balances, and live call monitoring, are not part of the customer API and are documented only inside the product.

Do you support webhooks and automations?

Yes. Outcomes such as call completed or appointment set can trigger automations and outbound webhooks from the dialer without writing code. See the integrations page for what is available.

Something else? Contact us

Ready to build?

Schedule demo See integrations