List Agents

GET/agentsOpen in the API playground →

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

typestringquery

Filter by type: super_agent or sub_agent

statusstringquery

Filter by status: active, suspended, terminated

parent_agent_idstringquery

Filter by parent agent (for sub-agents)

searchstringquery

Search by name, business name, or phone

limitintegerquerydefault: 50

Results per page (max 100)

offsetintegerquerydefault: 0

Pagination offset

---

Response

agentsarray

Array of agent objects

total_countinteger

Total matching agents

---

Examples

Request

cURL - All Agents

curl -X GET "https://demo.api.vultlocal.com/api/v1/agents" \
  -H "Authorization: Bearer olive_live_xxx"

cURL - Super-Agents Only

curl -X GET "https://demo.api.vultlocal.com/api/v1/agents?type=super_agent" \
  -H "Authorization: Bearer olive_live_xxx"

cURL - Sub-Agents of Parent

curl -X GET "https://demo.api.vultlocal.com/api/v1/agents?parent_agent_id=agent_abc123" \
  -H "Authorization: Bearer olive_live_xxx"

Response

200 OK

{
  "agents": [
    {
      "id": "agent_abc123",
      "type": "super_agent",
      "business_name": "ABC Money Services",
      "first_name": "John",
      "last_name": "Doe",
      "status": "active",
      "float_balance_formatted": "5,000,000.00 SLE",
      "sub_agent_count": 12
    },
    {
      "id": "agent_xyz789",
      "type": "sub_agent",
      "business_name": "Corner Shop",
      "first_name": "Jane",
      "last_name": "Smith",
      "status": "active",
      "float_balance_formatted": "500,000.00 SLE",
      "parent_agent_id": "agent_abc123"
    }
  ],
  "total_count": 150,
  "limit": 50,
  "offset": 0
}

---

Common Filters

Use Case	Query
All super-agents	?type=super_agent
Active sub-agents	?type=sub_agent&status=active
My sub-agents	?parent_agent_id={my_agent_id}
Search by name	?search=John

---

Errors

Status	Code	Description
401	UNAUTHORIZED	Invalid API key
403	FORBIDDEN	Insufficient permissions
500	INTERNAL_ERROR	Server error