> ## 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 a new agent

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



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

````