Skip to main content
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"
  }'

{
  "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"
  }
}
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

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

​
Body Parameters

​
agent_type
string
required
Agent type: super_agent or sub_agent
​
business_name
string
required
Registered business name
​
first_name
string
required
Agent’s first name
​
last_name
string
required
Agent’s last name
​
phone_number
string
required
Phone number for login and notifications
​
email
string
required
Email address
​
location
string
Operating location/address
​
parent_agent_id
string
Parent super-agent ID (required for sub-agents)
​
commission_tier
string
default:"standard"
Commission tier: standard, premium, custom
​
settlement_mode
string
default:"instant"
Settlement mode: instant, daily, weekly

​
Response

​
success
boolean
Whether registration succeeded
​
agent_id
string
Unique agent UUID
​
user_id
string
Associated user account ID
​
message
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"
  }'

{
  "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"
  }
}

​
Permissions

User RoleCan Create Super-AgentCan Create Sub-Agent
System AdminYesYes
Super-AgentNoYes (own network)
Sub-AgentNoNo

​
Credential Delivery

After registration, the agent receives login credentials via WhatsApp to their registered phone number.

​
Errors

StatusCodeDescription
400INVALID_REQUESTMissing required fields
400MISSING_PARENTparent_agent_id required for sub-agents
401UNAUTHORIZEDInvalid API key
403FORBIDDENNot authorized to create this agent type
409DUPLICATE_PHONEPhone already registered
409DUPLICATE_EMAILEmail already registered
500INTERNAL_ERRORServer error

Authorizations

​
Authorization
string
header
required

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

Body

application/json

Agent registration details

​
agent_pin
string
required
Example:

"1234"

​
agent_type
enum<string>
required

Required fields

Available options:
super_agent,
sub_agent
Example:

"super_agent"

​
business_address
string
required
Example:

"45 Business Road"

​
business_name
string
required
Example:

"ABC Money Transfer"

​
contact_person
string
required
Example:

"Michael Smith"

​
district
string
required
Example:

"Western Urban"

​
kyc_documents
string[]
required
Example:
["[\"https://s3.amazonaws.com/doc1.pdf\"]"]
​
phone_number
string
required
Example:

"0778888888"

​
commission_tier
integer

Default = 1

Required range: 1 <= x <= 3
Example:

1

​
email
string

Optional fields

Example:

"michael@abc.com"

​
parent_agent_id
string

Conditionally required

Example:

""

​
settlement_mode
enum<string>

Default = instant

Available options:
instant,
weekly,
monthly
Example:

"instant"

Response

Agent registered successfully

​
agent_id
string
​
email
string
​
instructions
string
​
login_url
string
​
message
string
​
password
string
​
success
boolean