openapi: 3.0.3
info:
  title: 'KuriSmsverify API Documentation'
  description: 'Welcome to KuriSmsVerify API Documentation. This API is designed to help you get started with using KuriSmsVerify services.'
  version: 1.0.0
servers:
  -
    url: 'https://kurismsverify.com'
tags:
  -
    name: 'User API'
    description: "\nAPIs for managing SMS activations programmatically."
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: "<p>This API uses API key authentication.</p>\n<p>Include your API key in the <code>Authorization</code> header when making requests.</p>\n<p>To obtain an API key:</p>\n<ol>\n    <li>Log in to your account on our website.</li>\n    <li>Navigate to your user profile or dashboard.</li>\n    <li>Copy the <code>API key</code> provided there.</li>\n    <li>Use this key in all authenticated requests.</li>\n</ol>\n<p>For example:<br>\n<code>Authorization: Bearer your-api-key-here</code></p>\n<p>You do not need to register or log in through this API. Each user manages their own authentication on their platform; our API only requires the API key for access.</p>\n"
security:
  -
    default: []
paths:
  /api/v1/user/balance:
    get:
      summary: 'Get Balance'
      operationId: getBalance
      description: 'Returns the current wallet balance of the user.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  balance: 150.5
                  currency: USD
                properties:
                  status:
                    type: string
                    example: success
                  balance:
                    type: number
                    example: 150.5
                  currency:
                    type: string
                    example: USD
      tags:
        - 'User API'
  /api/v1/activations/countries:
    get:
      summary: 'List Countries'
      operationId: listCountries
      description: 'Returns a list of all enabled countries and their codes.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  countries:
                    nigeria: Nigeria
                    russia: Russia
                    usa: USA
                properties:
                  status:
                    type: string
                    example: success
                  countries:
                    type: object
                    properties:
                      nigeria:
                        type: string
                        example: Nigeria
                      russia:
                        type: string
                        example: Russia
                      usa:
                        type: string
                        example: USA
      tags:
        - 'User API'
  /api/v1/activations/services:
    get:
      summary: 'List Services'
      operationId: listServices
      description: 'Returns available services. If country is provided, it returns services available in that specific country.'
      parameters:
        -
          in: query
          name: country
          description: "The country code (e.g., 'nigeria')."
          example: nigeria
          required: false
          schema:
            type: string
            description: "The country code (e.g., 'nigeria')."
            example: nigeria
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  services:
                    google: Google
                    facebook: Facebook
                    whatsapp: WhatsApp
                properties:
                  status:
                    type: string
                    example: success
                  services:
                    type: object
                    properties:
                      google:
                        type: string
                        example: Google
                      facebook:
                        type: string
                        example: Facebook
                      whatsapp:
                        type: string
                        example: WhatsApp
      tags:
        - 'User API'
  /api/v1/activations/prices:
    get:
      summary: 'Get Prices'
      operationId: getPrices
      description: 'Get prices for a country or a specific service in a country.'
      parameters:
        -
          in: query
          name: country
          description: 'The country code.'
          example: nigeria
          required: true
          schema:
            type: string
            description: 'The country code.'
            example: nigeria
        -
          in: query
          name: service
          description: 'The service code.'
          example: google
          required: false
          schema:
            type: string
            description: 'The service code.'
            example: google
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  price: 0.5
                properties:
                  status:
                    type: string
                    example: success
                  price:
                    type: number
                    example: 0.5
      tags:
        - 'User API'
      security: []
  /api/v1/activations/purchase:
    post:
      summary: 'Purchase Number'
      operationId: purchaseNumber
      description: 'Requests a new phone number for a specific service and country.'
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  message: 'Number purchased successfully'
                  activation:
                    id: 123
                    phone_number: '+2348012345678'
                    service: google
                    country: nigeria
                    cost: 0.5
                    status: pending
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: 'Number purchased successfully'
                  activation:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 123
                      phone_number:
                        type: string
                        example: '+2348012345678'
                      service:
                        type: string
                        example: google
                      country:
                        type: string
                        example: nigeria
                      cost:
                        type: number
                        example: 0.5
                      status:
                        type: string
                        example: pending
        400:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: error
                  message: 'Insufficient balance'
                properties:
                  status:
                    type: string
                    example: error
                  message:
                    type: string
                    example: 'Insufficient balance'
      tags:
        - 'User API'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                service:
                  type: string
                  description: "The service code (e.g., 'google')."
                  example: google
                country:
                  type: string
                  description: "The country code (e.g., 'nigeria')."
                  example: nigeria
              required:
                - service
                - country
  '/api/v1/activations/{id}':
    get:
      summary: 'Get Activation Status'
      operationId: getActivationStatus
      description: 'Retrieves the current status of an activation, including the SMS code if received.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  activation:
                    id: 123
                    status: received
                    sms_code: '123456'
                    phone_number: '+2348012345678'
                    updated_at: '2024-02-07 19:15:46'
                properties:
                  status:
                    type: string
                    example: success
                  activation:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 123
                      status:
                        type: string
                        example: received
                      sms_code:
                        type: string
                        example: '123456'
                      phone_number:
                        type: string
                        example: '+2348012345678'
                      updated_at:
                        type: string
                        example: '2024-02-07 19:15:46'
      tags:
        - 'User API'
    parameters:
      -
        in: path
        name: id
        description: 'The activation ID.'
        example: 123
        required: true
        schema:
          type: integer
  '/api/v1/activations/{id}/cancel':
    post:
      summary: 'Cancel Activation'
      operationId: cancelActivation
      description: "Cancels a pending activation and refunds the cost to the user's wallet."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  message: 'Activation cancelled successfully'
                  new_balance: 150.5
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: 'Activation cancelled successfully'
                  new_balance:
                    type: number
                    example: 150.5
      tags:
        - 'User API'
    parameters:
      -
        in: path
        name: id
        description: 'The activation ID.'
        example: 123
        required: true
        schema:
          type: integer