> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Agent

> Register a new super-agent or sub-agent

<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.
</Info>

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer olive_live_xxx` or `Bearer eyJ...` (JWT)
</ParamField>

### Body Parameters

<ParamField body="agent_type" type="string" required>
  Agent type: `super_agent` or `sub_agent`
</ParamField>

<ParamField body="business_name" type="string" required>
  Registered business name
</ParamField>

<ParamField body="first_name" type="string" required>
  Agent's first name
</ParamField>

<ParamField body="last_name" type="string" required>
  Agent's last name
</ParamField>

<ParamField body="phone_number" type="string" required>
  Phone number for login and notifications
</ParamField>

<ParamField body="email" type="string" required>
  Email address
</ParamField>

<ParamField body="location" type="string">
  Operating location/address
</ParamField>

<ParamField body="parent_agent_id" type="string">
  Parent super-agent ID (required for sub-agents)
</ParamField>

<ParamField body="commission_tier" type="string" default="standard">
  Commission tier: `standard`, `premium`, `custom`
</ParamField>

<ParamField body="settlement_mode" type="string" default="instant">
  Settlement mode: `instant`, `daily`, `weekly`
</ParamField>

***

## Response

<ResponseField name="success" type="boolean">
  Whether registration succeeded
</ResponseField>

<ResponseField name="agent_id" type="string">
  Unique agent UUID
</ResponseField>

<ResponseField name="user_id" type="string">
  Associated user account ID
</ResponseField>

<ResponseField name="message" type="string">
  Result message
</ResponseField>

***

## Examples

<RequestExample>
  ```bash cURL - Super-Agent theme={null}
  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"
    }'
  ```

  ```bash cURL - Sub-Agent theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "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"
    }
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Only system administrators can register super-agents",
    "code": "FORBIDDEN"
  }
  ```
</ResponseExample>

***

## 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.
</Info>

***

## 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                              |


## OpenAPI

````yaml olive-openapi.json POST /agents
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Register a new agent
      description: >-
        Register a super-agent or sub-agent for the system. Only admins can
        register super-agents. Both admins and super-agents can register
        sub-agents.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/handler.RegisterAgentRequest'
        description: Agent registration details
        required: true
      responses:
        '201':
          description: Agent registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.RegisterAgentResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      security:
        - ApiKeyAuth: []
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    handler.RegisterAgentRequest:
      type: object
      required:
        - agent_pin
        - agent_type
        - business_address
        - business_name
        - contact_person
        - district
        - kyc_documents
        - phone_number
      properties:
        agent_pin:
          type: string
          example: '1234'
        agent_type:
          description: Required fields
          type: string
          enum:
            - super_agent
            - sub_agent
          example: super_agent
        business_address:
          type: string
          example: 45 Business Road
        business_name:
          type: string
          example: ABC Money Transfer
        commission_tier:
          description: Default = 1
          type: integer
          maximum: 3
          minimum: 1
          example: 1
        contact_person:
          type: string
          example: Michael Smith
        district:
          type: string
          example: Western Urban
        email:
          description: Optional fields
          type: string
          example: michael@abc.com
        kyc_documents:
          type: array
          items:
            type: string
          example:
            - '["https://s3.amazonaws.com/doc1.pdf"]'
        parent_agent_id:
          description: Conditionally required
          type: string
          example: ''
        phone_number:
          type: string
          example: '0778888888'
        settlement_mode:
          description: Default = instant
          type: string
          enum:
            - instant
            - weekly
            - monthly
          example: instant
    handler.RegisterAgentResponse:
      type: object
      properties:
        agent_id:
          type: string
        email:
          type: string
        instructions:
          type: string
        login_url:
          type: string
        message:
          type: string
        password:
          type: string
        success:
          type: boolean
  securitySchemes:
    ApiKeyAuth:
      description: >-
        API Key for third-party integrations (WhatsApp, Smart PAY, VULT).
        Format: 'Bearer olive_live_xxxxxxxxxxxxx'
      type: apiKey
      name: Authorization
      in: header
    BearerAuth:
      description: >-
        JWT token from admin login for administrative operations. Format:
        'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
      type: apiKey
      name: Authorization
      in: header

````