Skip to main content
GET
/
agents
curl -X GET "https://demo.api.vultlocal.com/api/v1/agents" \
  -H "Authorization: Bearer olive_live_xxx"
{
  "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
}

Request

Authorization
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

type
string
Filter by type: super_agent or sub_agent
status
string
Filter by status: active, suspended, terminated
parent_agent_id
string
Filter by parent agent (for sub-agents)
Search by name, business name, or phone
limit
integer
default:"50"
Results per page (max 100)
offset
integer
default:"0"
Pagination offset

Response

agents
array
Array of agent objects
total_count
integer
Total matching agents

Examples

curl -X GET "https://demo.api.vultlocal.com/api/v1/agents" \
  -H "Authorization: Bearer olive_live_xxx"
{
  "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 CaseQuery
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

StatusCodeDescription
401UNAUTHORIZEDInvalid API key
403FORBIDDENInsufficient permissions
500INTERNAL_ERRORServer error

Authorizations

Authorization
string
header
required

API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'

Query Parameters

agent_type
string

Filter by agent type (super_agent or sub_agent)

parent_agent_id
string

Filter by parent agent ID

limit
integer
default:50

Number of results to return

offset
integer
default:0

Offset for pagination

Response

OK

The response is of type object.