Skip to main content

​
Get Voice Agent API

This documentation explains how to retrieve details of voice agents using the API.

​
Endpoint

GET /api/v1/global/agents/get or POST /api/v1/global/agents/get

​
Authentication

Include your API token in the request header: 
token: <your_api_token>
or 
api_access_token: <your_api_token>

​
Request Body (for POST)

​
Get Specific Agent

{
  "agent_id": 123
}

​
Get All Agents

{}

​
Get Agents by Type

{
  "agent_type": 3
}

​
Get Specific Agent with Type Filter

{
  "agent_id": 123,
  "agent_type": 3
}

​
Query Parameters (for GET)

​
Get Specific Agent

?agent_id=123

​
Get All Agents

(no parameters)

​
Get Agents by Type

?agent_type=3

​
Get Specific Agent with Type Filter

?agent_id=123&agent_type=3

​
Optional Fields

FieldTypeDescription
agent_idintegerID of the agent to retrieve. If not provided, returns all agents
agent_typeintegerFilter by agent type. See Agent Types below

​
Agent Types

IDTypeDescription
2ChatChat-based agents
3TelephonyVoice/telephony agents (for making calls)
4GeneralGeneral purpose agents
Note: For voice/telephony agents that can make calls, use agent_type: 3.

​
Calling Types

Important: The calling_type field in the response indicates whether the agent is configured for outbound or inbound calls.
IDTypeDescription
1OutboundAgent makes calls to customers. The agent initiates calls to phone numbers.
2InboundAgent receives calls from customers. Customers call your phone numbers and the agent answers.
nullNot SetCalling type is not configured for this agent.
Note:
  • calling_type: 1 means the agent is configured for outbound calling (making calls)
  • calling_type: 2 means the agent is configured for inbound calling (receiving calls)
  • calling_type: null means the calling type is not configured

​
Success Response

​
Single Agent Response (when agent_id is provided)

Status Code: 200 OK 
{
  "error": false,
  "code": 200,
  "message": "Voice agent retrieved successfully",
  "timestamp": 1767638299411,
  "data": {
    "success": true,
    "message": "Voice agent retrieved successfully",
    "data": {
      "agent_id": 1048,
      "agent_name": "Test Agent",
      "description": "Test description",
      "status": 3,
      "agent_type": 3,
      "voice_id": "KYiVPerWcenyBTIvWbfY",
      "voice_provider": 1,
      "transcriber_provider": null,
      "calling_type": null,
      "created_on": "2026-01-01T07:44:46.000Z",
      "updated_on": "2026-01-01T07:44:46.000Z"
    }
  }
}

​
Multiple Agents Response (when agent_id is not provided)

Status Code: 200 OK 
{
  "error": false,
  "code": 200,
  "message": "Voice agents retrieved successfully",
  "timestamp": 1767638262719,
  "data": {
    "success": true,
    "total": 35,
    "data": [
      {
        "agent_id": 1049,
        "agent_name": "Flow Test",
        "description": "",
        "status": 3,
        "agent_type": 3,
        "voice_id": "KYiVPerWcenyBTIvWbfY",
        "voice_provider": 1,
        "transcriber_provider": null,
        "calling_type": null,
        "created_on": "2026-01-02T14:13:19.000Z",
        "updated_on": "2026-01-02T14:13:19.000Z"
      },
      {
        "agent_id": 1048,
        "agent_name": "Test Agent",
        "description": "",
        "status": 3,
        "agent_type": 3,
        "voice_id": "KYiVPerWcenyBTIvWbfY",
        "voice_provider": 1,
        "transcriber_provider": null,
        "calling_type": null,
        "created_on": "2026-01-01T07:44:46.000Z",
        "updated_on": "2026-01-01T07:44:46.000Z"
      }
    ]
  }
}

​
Response Fields

FieldTypeDescription
agent_idintegerUnique identifier for the agent
agent_namestringName of the agent
descriptionstringDescription of the agent (can be empty string)
statusintegerAgent status: 1 = Active, 3 = Inactive, 2 = Deleted
agent_typeintegerType of agent: 2 = Chat, 3 = Telephony, 4 = General
voice_idstringVoice ID being used (can be a string identifier)
voice_providerintegerVoice provider ID (see Create Agent docs for options)
transcriber_providerinteger | nullSpeech-to-text provider ID (can be null)
calling_typeinteger | nullCalling type (see Calling Types below). Can be null if not configured
created_onstringCreation timestamp (ISO 8601 format)
updated_onstringLast update timestamp (ISO 8601 format)
Note:
  • transcriber_provider and calling_type can be null if not configured
  • voice_id is typically a string identifier, not an integer
  • Timestamps are in ISO 8601 format (e.g., “2026-01-01T07:44:46.000Z”)

​
Error Responses

​
400 Bad Request

{
  "error": true,
  "message": "Agent ID is required"
}

​
401 Unauthorized

{
  "error": true,
  "message": "Invalid Auth Key or Session Expired"
}

​
404 Not Found

{
  "error": true,
  "message": "Agent not found"
}

​
Example Requests

​
Get Specific Agent (GET)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/get?agent_id=123" \
  -H "token: your_api_token_here"

​
Get Specific Agent (POST)

curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_id": 123
  }'

​
Get All Agents (GET)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/get" \
  -H "token: your_api_token_here"

​
Get All Agents (POST)

curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{}'

​
Get All Telephony Agents (GET)

curl -X GET "https://www.tryunleashx.com/api/v1/global/agents/get?agent_type=3" \
  -H "token: your_api_token_here"

​
Get All Telephony Agents (POST)

curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_type": 3
  }'

​
Get All Chat Agents (POST)

curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_type": 2
  }'

​
Get All General Agents (POST)

curl -X POST https://www.tryunleashx.com/api/v1/global/agents/get \
  -H "Content-Type: application/json" \
  -H "token: your_api_token_here" \
  -d '{
    "agent_type": 4
  }'

​
Notes

  • If agent_id is provided, returns details of that specific agent.
  • If agent_id is not provided, returns a list of all agents.
  • If agent_type is provided, filters agents by type (2 = Chat, 3 = Telephony, 4 = General).
  • The agent_type filter only applies when getting all agents (not when getting a specific agent by ID).
  • The agents must belong to your workspace.
  • Deleted agents (status = 2) will not be returned.
  • Use the status field to check if the agent is active before making calls.
  • For making calls, use agents with agent_type: 3 (Telephony).
  • Response includes a wrapper with error, code, message, timestamp, and data fields.
  • The actual agent data is nested in data.data for single agent, or data.data array for multiple agents.