Register Agent - OLIVE Payment Platform

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

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_agent

string

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, custom

string

default:"instant"

Settlement mode: instant, daily, weekly

Response

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

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

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

instructions

string

message

string

password

string

success

boolean

Agents

Get Agent

​Request

​Body Parameters

​Response

​Examples

​Permissions

​Credential Delivery

​Errors

Authorizations

Body

Response

Request

Body Parameters

Response

Examples

Permissions

Credential Delivery

Errors