openapi: 3.0.3
info:
  title: 'VerifiedGlobalSms API Documentation'
  description: 'Welcome to VerifiedGlobalSms API Documentation. This API is designed to help you get started with using VerifiedGlobalSms services.'
  version: 1.0.0
servers:
  -
    url: 'https://verifiedglobalsms.com'
tags:
  -
    name: 'User API'
    description: "\nAPIs for managing SMS activations programmatically via Smspool.net integration."
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 in Naira (₦).'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  balance: 5000.0
                  currency: NGN
                properties:
                  status:
                    type: string
                    example: success
                  balance:
                    type: number
                    example: 5000.0
                  currency:
                    type: string
                    example: NGN
      tags:
        - 'User API'
  /api/v1/activations/countries:
    get:
      summary: 'List Countries'
      operationId: listCountries
      description: 'Returns a list of all Smspool countries and their codes.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  countries:
                    -
                      ID: '1'
                      name: Afghanistan
                    -
                      ID: '2'
                      name: Albania
                properties:
                  status:
                    type: string
                    example: success
                  countries:
                    type: array
                    example:
                      -
                        ID: '1'
                        name: Afghanistan
                      -
                        ID: '2'
                        name: Albania
                    items:
                      type: object
                      properties:
                        ID:
                          type: string
                          example: '1'
                        name:
                          type: string
                          example: Afghanistan
      tags:
        - 'User API'
  /api/v1/activations/services:
    get:
      summary: 'List Services'
      operationId: listServices
      description: 'Returns available services for a specific country with Naira prices.'
      parameters:
        -
          in: query
          name: country
          description: 'The country code or ID.'
          example: '1'
          required: true
          schema:
            type: string
            description: 'The country code or ID.'
            example: '1'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  services:
                    -
                      name: WhatsApp
                      ID: whatsapp
                      price: 250.0
                      currency: NGN
                properties:
                  status:
                    type: string
                    example: success
                  services:
                    type: array
                    example:
                      -
                        name: WhatsApp
                        ID: whatsapp
                        price: 250
                        currency: NGN
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: WhatsApp
                        ID:
                          type: string
                          example: whatsapp
                        price:
                          type: number
                          example: 250.0
                        currency:
                          type: string
                          example: NGN
      tags:
        - 'User API'
  /api/v1/activations/prices:
    get:
      summary: 'Get Price'
      operationId: getPrice
      description: 'Get price for a specific service in a country in Naira (₦).'
      parameters:
        -
          in: query
          name: country
          description: 'The country ID.'
          example: '1'
          required: true
          schema:
            type: string
            description: 'The country ID.'
            example: '1'
        -
          in: query
          name: service
          description: 'The service ID.'
          example: google
          required: true
          schema:
            type: string
            description: 'The service ID.'
            example: google
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  price: 350.0
                  currency: NGN
                properties:
                  status:
                    type: string
                    example: success
                  price:
                    type: number
                    example: 350.0
                  currency:
                    type: string
                    example: NGN
      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 via Smspool.'
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  message: 'Number purchased successfully'
                  activation:
                    id: 123
                    order_id: ABC123
                    phone_number: '+2348012345678'
                    service: google
                    country: '1'
                    cost: 350.0
                    status: active
                    expires_at: '2024-02-07T19:20:46Z'
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: 'Number purchased successfully'
                  activation:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 123
                      order_id:
                        type: string
                        example: ABC123
                      phone_number:
                        type: string
                        example: '+2348012345678'
                      service:
                        type: string
                        example: google
                      country:
                        type: string
                        example: '1'
                      cost:
                        type: number
                        example: 350.0
                      status:
                        type: string
                        example: active
                      expires_at:
                        type: string
                        example: '2024-02-07T19:20:46Z'
      tags:
        - 'User API'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                service:
                  type: string
                  description: "The service ID (e.g., 'google')."
                  example: google
                country:
                  type: string
                  description: "The country ID (e.g., '1')."
                  example: '1'
              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
                    order_id: ABC123
                    status: completed
                    sms_code: '123456'
                    phone_number: '+2348012345678'
                    expires_at: '2024-02-07T19:20:46Z'
                    updated_at: '2024-02-07 19:15:46'
                properties:
                  status:
                    type: string
                    example: success
                  activation:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 123
                      order_id:
                        type: string
                        example: ABC123
                      status:
                        type: string
                        example: completed
                      sms_code:
                        type: string
                        example: '123456'
                      phone_number:
                        type: string
                        example: '+2348012345678'
                      expires_at:
                        type: string
                        example: '2024-02-07T19:20:46Z'
                      updated_at:
                        type: string
                        example: '2024-02-07 19:15:46'
      tags:
        - 'User API'
    parameters:
      -
        in: path
        name: id
        description: 'The internal 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.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  status: success
                  message: 'Activation cancelled successfully'
                  new_balance: 5350.0
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: 'Activation cancelled successfully'
                  new_balance:
                    type: number
                    example: 5350.0
      tags:
        - 'User API'
    parameters:
      -
        in: path
        name: id
        description: 'The internal activation ID.'
        example: 123
        required: true
        schema:
          type: integer