curl -X POST "https://demo.api.vultlocal.com/api/v1/agents" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "super_agent",
"business_name": "ABC Money Services",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+23277123456",
"email": "john@abcmoney.sl",
"location": "Freetown CBD",
"commission_tier": "premium"
}'
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "sub_agent",
"business_name": "Corner Shop",
"first_name": "Jane",
"last_name": "Smith",
"phone_number": "+23276654321",
"email": "jane@corner.sl",
"location": "Kissy Road",
"parent_agent_id": "agent_abc123"
}'
{
"success": true,
"message": "Agent registered successfully",
"agent_id": "agent_xyz789",
"user_id": "user_abc123",
"agent": {
"id": "agent_xyz789",
"type": "sub_agent",
"business_name": "Corner Shop",
"status": "active",
"parent_agent_id": "agent_abc123",
"created_at": "2025-01-15T10:30:00Z"
}
}
{
"error": "Only system administrators can register super-agents",
"code": "FORBIDDEN"
}
Agents
Register Agent
Register a new super-agent or sub-agent
POST
/
agents
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "super_agent",
"business_name": "ABC Money Services",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+23277123456",
"email": "john@abcmoney.sl",
"location": "Freetown CBD",
"commission_tier": "premium"
}'
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "sub_agent",
"business_name": "Corner Shop",
"first_name": "Jane",
"last_name": "Smith",
"phone_number": "+23276654321",
"email": "jane@corner.sl",
"location": "Kissy Road",
"parent_agent_id": "agent_abc123"
}'
{
"success": true,
"message": "Agent registered successfully",
"agent_id": "agent_xyz789",
"user_id": "user_abc123",
"agent": {
"id": "agent_xyz789",
"type": "sub_agent",
"business_name": "Corner Shop",
"status": "active",
"parent_agent_id": "agent_abc123",
"created_at": "2025-01-15T10:30:00Z"
}
}
{
"error": "Only system administrators can register super-agents",
"code": "FORBIDDEN"
}
Registers a new agent in the network. Super-agents can only be created by system admins. Sub-agents can be created by admins or their parent super-agent.
Request
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)Body Parameters
string
required
Agent type:
super_agent or sub_agentstring
required
Registered business name
string
required
Agent’s first name
string
required
Agent’s last name
string
required
Phone number for login and notifications
string
required
Email address
string
Operating location/address
string
Parent super-agent ID (required for sub-agents)
string
default:"standard"
Commission tier:
standard, premium, customstring
default:"instant"
Settlement mode:
instant, daily, weeklyResponse
boolean
Whether registration succeeded
string
Unique agent UUID
string
Associated user account ID
string
Result message
Examples
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "super_agent",
"business_name": "ABC Money Services",
"first_name": "John",
"last_name": "Doe",
"phone_number": "+23277123456",
"email": "john@abcmoney.sl",
"location": "Freetown CBD",
"commission_tier": "premium"
}'
curl -X POST "https://demo.api.vultlocal.com/api/v1/agents" \
-H "Authorization: Bearer olive_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "sub_agent",
"business_name": "Corner Shop",
"first_name": "Jane",
"last_name": "Smith",
"phone_number": "+23276654321",
"email": "jane@corner.sl",
"location": "Kissy Road",
"parent_agent_id": "agent_abc123"
}'
{
"success": true,
"message": "Agent registered successfully",
"agent_id": "agent_xyz789",
"user_id": "user_abc123",
"agent": {
"id": "agent_xyz789",
"type": "sub_agent",
"business_name": "Corner Shop",
"status": "active",
"parent_agent_id": "agent_abc123",
"created_at": "2025-01-15T10:30:00Z"
}
}
{
"error": "Only system administrators can register super-agents",
"code": "FORBIDDEN"
}
Permissions
| User Role | Can Create Super-Agent | Can Create Sub-Agent |
|---|---|---|
| System Admin | Yes | Yes |
| Super-Agent | No | Yes (own network) |
| Sub-Agent | No | No |
Credential Delivery
After registration, the agent receives login credentials via WhatsApp to their registered phone number.
Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Missing required fields |
| 400 | MISSING_PARENT | parent_agent_id required for sub-agents |
| 401 | UNAUTHORIZED | Invalid API key |
| 403 | FORBIDDEN | Not authorized to create this agent type |
| 409 | DUPLICATE_PHONE | Phone already registered |
| 409 | DUPLICATE_EMAIL | Email already registered |
| 500 | INTERNAL_ERROR | Server error |
Authorizations
ApiKeyAuthApiKeyAuthBearerAuth
API Key for third-party integrations (WhatsApp, Smart PAY, VULT). Format: 'Bearer olive_live_xxxxxxxxxxxxx'
Body
application/json
Agent registration details
Example:
"1234"
Required fields
Available options:
super_agent, sub_agent Example:
"super_agent"
Example:
"45 Business Road"
Example:
"ABC Money Transfer"
Example:
"Michael Smith"
Example:
"Western Urban"
Example:
["[\"https://s3.amazonaws.com/doc1.pdf\"]"]
Example:
"0778888888"
Default = 1
Required range:
1 <= x <= 3Example:
1
Optional fields
Example:
"michael@abc.com"
Conditionally required
Example:
""
Default = instant
Available options:
instant, weekly, monthly Example:
"instant"
⌘I