Agents

An agent is one person who takes calls, from the browser, a mobile app or a SIP phone. Agents in a pool share answered calls from one dial session. A disconnected agent gets no calls, and their dial session pauses until they reconnect. agent.connected and agent.disconnected report each change.

Guide: Agent calling.

Endpoints

POST	`/v1/agents`	Create an agent
GET	`/v1/agents/{id}`	Retrieve an agent
GET	`/v1/agents`	List agents
PATCH	`/v1/agents/{id}`	Update an agent
DELETE	`/v1/agents/{id}`	Delete an agent
POST	`/v1/agents/{id}/tokens`	Create an agent token
POST	`/v1/agents/{id}/sip_credentials`	Create SIP credentials
POST	`/v1/agent_pools`	Create an agent pool
GET	`/v1/agent_pools`	List agent pools

The agent object

Field	Type	Description
`id`	string	Unique ID, starts with agt_.
`name`	string	Shown in the dashboard and on call records.
`email`	string \| null	The agent's work email.
`agent_pool_id`	string \| null	The pool the agent shares calls in.
`status`	string	offline, connected or on_call.
`connected_via`	string \| null	browser, ios, android or sip while connected.
`dial_session_id`	string \| null	The dial session the agent is in.
`current_call_id`	string \| null	The call the agent is on.
`sip`	object \| null	address, transport, port, media, codecs and username for agents created with sip=true. The password is returned only when credentials are created.
`metadata`	object	Up to 20 keys. Returned on events about the agent.
`created_at`	string	When the agent was created, ISO 8601.

Create an agent

Creates one agent per seat. With sip=true the response includes the SIP password. It is shown once.

POST/v1/agents

Body parameters	Type	Description
`name`required	string	Shown in the dashboard and on call records.
`agent_pool_id`	string	The pool the agent shares calls in. Created if it does not exist.
`sip`	boolean	Give the agent a SIP address and credentials. Default false.
`email`	string	The agent's work email.
`metadata`	object	Up to 20 keys.

POST/v1/agents

curl https://api.liveleg.dev/v1/agents \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan Pike",
    "agent_pool_id": "pool_closers",
    "sip": true
  }'

const res = await fetch('https://api.liveleg.dev/v1/agents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: "Jordan Pike",
    agent_pool_id: "pool_closers",
    sip: true
  }),
});
const data = await res.json();

import os, requests

data = requests.post(
    "https://api.liveleg.dev/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={
        "name": "Jordan Pike",
        "agent_pool_id": "pool_closers",
        "sip": True,
    },
).json()

Response

{
  "id": "agt_114",
  "object": "agent",
  "name": "Jordan Pike",
  "email": null,
  "agent_pool_id": "pool_closers",
  "status": "offline",
  "connected_via": null,
  "dial_session_id": null,
  "current_call_id": null,
  "sip": {
    "address": "sip:agt_114@sip.liveleg.dev",
    "transport": "tls",
    "port": 5061,
    "media": "srtp",
    "codecs": [
      "opus",
      "g722",
      "pcmu",
      "pcma"
    ],
    "username": "agt_114",
    "password": "Vt8qLm2xR4pZ9wKd"
  },
  "metadata": {},
  "created_at": "2026-11-02T18:04:51Z"
}

Retrieve an agent

Returns the agent with their connection status and current call.

GET/v1/agents/{id}

GET/v1/agents/{id}

curl https://api.liveleg.dev/v1/agents/agt_114 \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/agents/agt_114', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

data = requests.get(
    "https://api.liveleg.dev/v1/agents/agt_114",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
).json()

Response

{
  "id": "agt_114",
  "object": "agent",
  "name": "Jordan Pike",
  "email": "jordan@ridgelineroofing.example",
  "agent_pool_id": "pool_closers",
  "status": "connected",
  "connected_via": "browser",
  "dial_session_id": "dls_31Ka9",
  "current_call_id": null,
  "sip": null,
  "metadata": {},
  "created_at": "2026-11-02T18:04:51Z"
}

List agents

Returns your agents, newest first.

GET/v1/agents

Query parameters	Type	Description
`agent_pool_id`	string	Only agents in this pool.
`status`	string	offline, connected or on_call.
`limit`	integer	1 to 100. Default 20.
`starting_after`	string	The last ID from the previous page.

GET/v1/agents

curl "https://api.liveleg.dev/v1/agents?agent_pool_id=pool_closers&status=connected" \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/agents?agent_pool_id=pool_closers&status=connected', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

data = requests.get(
    "https://api.liveleg.dev/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    params={
        "agent_pool_id": "pool_closers",
        "status": "connected",
    },
).json()

Response

{
  "object": "list",
  "data": [
    {
      "id": "agt_114",
      "object": "agent",
      "name": "Jordan Pike",
      "email": "jordan@ridgelineroofing.example",
      "agent_pool_id": "pool_closers",
      "status": "connected",
      "connected_via": "browser",
      "dial_session_id": "dls_31Ka9",
      "current_call_id": null,
      "sip": null,
      "metadata": {},
      "created_at": "2026-11-02T18:04:51Z"
    }
  ],
  "has_more": false
}

Update an agent

Changes the fields you send. Moving an agent to another pool takes effect on their next call.

PATCH/v1/agents/{id}

Body parameters	Type	Description
`name`	string	Shown in the dashboard and on call records.
`agent_pool_id`	string	The pool the agent shares calls in.
`email`	string	The agent's work email.
`sip`	boolean	true adds a SIP address and returns new credentials. false removes it.
`metadata`	object	Up to 20 keys. Send an empty string to remove a key.

PATCH/v1/agents/{id}

curl -X PATCH https://api.liveleg.dev/v1/agents/agt_114 \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_pool_id": "pool_setters"
  }'

const res = await fetch('https://api.liveleg.dev/v1/agents/agt_114', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_pool_id: "pool_setters"
  }),
});
const data = await res.json();

import os, requests

data = requests.patch(
    "https://api.liveleg.dev/v1/agents/agt_114",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={
        "agent_pool_id": "pool_setters",
    },
).json()

Response

{
  "id": "agt_114",
  "object": "agent",
  "name": "Jordan Pike",
  "email": "jordan@ridgelineroofing.example",
  "agent_pool_id": "pool_setters",
  "status": "connected",
  "connected_via": "browser",
  "dial_session_id": "dls_31Ka9",
  "current_call_id": null,
  "sip": null,
  "metadata": {},
  "created_at": "2026-11-02T18:04:51Z"
}

Delete an agent

Disconnects the agent, stops their dial session and removes their SIP address. Call records and recordings stay.

DELETE/v1/agents/{id}

DELETE/v1/agents/{id}

curl -X DELETE https://api.liveleg.dev/v1/agents/agt_114 \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/agents/agt_114', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

data = requests.delete(
    "https://api.liveleg.dev/v1/agents/agt_114",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
).json()

Response

{
  "id": "agt_114",
  "object": "agent",
  "deleted": true
}

Create an agent token

Mints a short-lived token that the browser SDK or a mobile library uses to connect as this agent. Mint it on your server and never put an API key in the browser. The token is checked when the connection opens, and an open connection stays up for the whole shift. Reconnecting needs a new token.

POST/v1/agents/{id}/tokens

Body parameters	Type	Description
`ttl_seconds`	integer	How long the token can be used to connect. 60 to 3600, default 3600.

POST/v1/agents/{id}/tokens

curl https://api.liveleg.dev/v1/agents/agt_114/tokens \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_seconds": 3600
  }'

const res = await fetch('https://api.liveleg.dev/v1/agents/agt_114/tokens', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    ttl_seconds: 3600
  }),
});
const data = await res.json();

import os, requests

data = requests.post(
    "https://api.liveleg.dev/v1/agents/agt_114/tokens",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={
        "ttl_seconds": 3600,
    },
).json()

Response

{
  "token": "eyJhbGciOiJFUzI1NiJ9.eyJhZ3QiOiJhZ3RfMTE0In0.Xq9...",
  "agent_id": "agt_114",
  "expires_at": "2026-11-03T15:00:02Z"
}

Create SIP credentials

Issues a new SIP password for the agent. The old password stops working right away and the phone has to register again. The password is shown once.

POST/v1/agents/{id}/sip_credentials

POST/v1/agents/{id}/sip_credentials

curl -X POST https://api.liveleg.dev/v1/agents/agt_114/sip_credentials \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/agents/agt_114/sip_credentials', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

data = requests.post(
    "https://api.liveleg.dev/v1/agents/agt_114/sip_credentials",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
).json()

Response

{
  "agent_id": "agt_114",
  "sip": {
    "address": "sip:agt_114@sip.liveleg.dev",
    "transport": "tls",
    "port": 5061,
    "media": "srtp",
    "codecs": [
      "opus",
      "g722",
      "pcmu",
      "pcma"
    ],
    "username": "agt_114",
    "password": "Np3rKw7dT1xQ5mYb"
  },
  "created_at": "2026-11-03T17:22:08Z"
}

Create an agent pool

A pool shares answered calls from one dial session. A second live person goes to the next free agent. Pools are also created when you set a new agent_pool_id on an agent.

POST/v1/agent_pools

Body parameters	Type	Description
`name`required	string	Shown in the dashboard.
`id`	string	Your own ID, starting with pool_. Generated if you leave it out.

POST/v1/agent_pools

curl https://api.liveleg.dev/v1/agent_pools \
  -H "Authorization: Bearer $LIVELEG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pool_closers",
    "name": "Closers"
  }'

const res = await fetch('https://api.liveleg.dev/v1/agent_pools', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id: "pool_closers",
    name: "Closers"
  }),
});
const data = await res.json();

import os, requests

data = requests.post(
    "https://api.liveleg.dev/v1/agent_pools",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
    json={
        "id": "pool_closers",
        "name": "Closers",
    },
).json()

Response

{
  "id": "pool_closers",
  "object": "agent_pool",
  "name": "Closers",
  "agent_count": 0,
  "connected_count": 0,
  "created_at": "2026-11-02T18:01:12Z"
}

List agent pools

Returns your agent pools with the number of agents in each and how many are connected.

GET/v1/agent_pools

Query parameters	Type	Description
`limit`	integer	1 to 100. Default 20.
`starting_after`	string	The last ID from the previous page.

GET/v1/agent_pools

curl https://api.liveleg.dev/v1/agent_pools \
  -H "Authorization: Bearer $LIVELEG_API_KEY"

const res = await fetch('https://api.liveleg.dev/v1/agent_pools', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.LIVELEG_API_KEY}`,
  },
});
const data = await res.json();

import os, requests

data = requests.get(
    "https://api.liveleg.dev/v1/agent_pools",
    headers={"Authorization": f"Bearer {os.environ['LIVELEG_API_KEY']}"},
).json()

Response

{
  "object": "list",
  "data": [
    {
      "id": "pool_closers",
      "object": "agent_pool",
      "name": "Closers",
      "agent_count": 6,
      "connected_count": 4,
      "created_at": "2026-11-02T18:01:12Z"
    }
  ],
  "has_more": false
}