Register Agent

POST/agentsOpen in the API playground →

Info

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

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Body Parameters

agent_typestringbodyrequired

Agent type: super_agent or sub_agent

business_namestringbodyrequired

Registered business name

first_namestringbodyrequired

Agent's first name

last_namestringbodyrequired

Agent's last name

phone_numberstringbodyrequired

Phone number for login and notifications

emailstringbodyrequired

Email address

locationstringbody

Operating location/address

parent_agent_idstringbody

Parent super-agent ID (required for sub-agents)

commission_tierstringbodydefault: standard

Commission tier: standard, premium, custom

settlement_modestringbodydefault: instant

Settlement mode: instant, daily, weekly

---

Response

successboolean

Whether registration succeeded

agent_idstring

Unique agent UUID

user_idstring

Associated user account ID

messagestring

Result message

---

Examples

Request

cURL - Super-Agent

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 - Sub-Agent

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

Response

201 Created

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

403 Forbidden

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

Info

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