openapi: 3.1.0
info:
  version: 1.0.0
  title: Platfone Retail API
  termsOfService: https://platfone.com/compliance#terms
  contact:
    email: support@platfone.com
    url: https://platfone.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://wl-temp-number.nyc3.cdn.digitaloceanspaces.com/platfone_logo.svg
    href: https://platfone.com
    altText: Platfone API
  description: |
    # About this API

    Retail API allows you to create and manage activations for your users without the need of building complex backend. You can use this API to automate SMS verification for your users. Billing applies only to successfully received SMS messages. We manage user balance and activations storage for you, so you can focus on your app.

    This API was designed with focus on mobile or web apps developers who want to create apps that allows their users to register in their apps, pay them and make activations with minimal backend.

    **What should you implement?**

    1. Users registration and authentication
    2. Accept payments from users and send the payment amount together with unique user identifier to Retail API
    3. Use Retail API to get phone number and receive sms, while sending unique user identifier to Retail API

    **What we provide?**
    Simple API to create and manage activations on behalf of your users, icluding:

    - phone number for SMS verification (activation) backed by numerous suppliers and complex algorithms to ensure high success rate
    - storage of activations history
    - balance billing for your users for successfully received SMS messages

    **How it works?**

    1. Each activation is associated with your user. You send unique user identifier with each activation request. You can use `id` of your user form `users` DB table for example or any other unique user identifier. We will store this identifier with each activation, so you can later match activations with your users.
    2. We will manage balance of your users for you. We will reserve balance, while waiting for activation, release or bill when SMS received. On each purchase send us:

       - unique user identifier
       - amount of funds to be added or deducted to/from user balance
       - unique transaction identifier to prevent double billing

       You can get balance of your user at any time.

    That's it! You can now focus on your app and let us handle the rest.

    **How to start?**

    1. Register an account at [https://platfone.com](https://platfone.com)
    2. Switch to test mode in order to test the API without billing
    3. Check our sample app code at
    4. Need help? Contact us via [Support system](https://platfone.com/) or send us an email at <support@platfone.com>

    ## How to use

    1. Register an account at [https://platfone.com](https://platfone.com)
    2. Add balance to your account
    3. Get your API key from [https://platfone.com/app/api](https://platfone.com/app/api)

    ## API key

    All requests must include an API key in the `X-Api-Key` header. You can get your API key from [https://platfone.com/app/api](https://platfone.com/app/api)

    ## API base URL

    All requests must be made to the following URL:

    ```
    https://temp-number-api.com/api/v1/retail/
    ```

    ## Customer

    **Customer** - is your customer. You can create customers and manage their balance and activations. Each customer has its own balance and activations history.

    ## Standard application flow

    Usually, the application flow is as follows:

    1. Your customer registers in your app -> You create a customer for him `POST retail/m/customer`
    2. Your customer tops up the balance in your app -> You add funds to the customer balance `POST retail/m/customer/<customer_id>/transaction`
    3. Your customer wants to activate a service -> You create an activation for the customer `POST retail/a/<customer_id>/activation` and notice the `activation_id` and `phone` number.
    4. You show the `phone` number to your customer and ask him to send SMS to this number.
    5. You poll the Retail API to get using the `activation_id` at 10-second intervals to receive SMS. Continue this process until the either `expire_at` timestamp is exceeded or `sms_status = smsReceived`. If the status is `smsReceived`, show the code and message from the response and stop polling. If supported you can request one more SMS message from the same number, using retry activation endpoint.
    6. You customer checks his balance -> You get the balance of the customer `GET retail/a/customer/<customer_id>/balance`

    ## API endpoints

    ### Endpoint types

    There are two types of endpoints (going after the base URL `/api/v1/retail/`):

    1. `/m/` - Management. E.g. create customer, get various information and statistics about their usage.
    2. `/a/` - Application. Operations that customer do in your application. E.g. get balance, create activation, get activation history for specific customer. This endpoint requires customer `id` to be included in the URL.

    ### Management endpoints

    This endpoint is used to manage customers. You can create, update, delete customers and get various information and statistics about their usage. These endpoints has prefix `/m/`.

    - `POST retail/m/customer` - create new customer
    - `PUT retail/m/customer/<customer_id>` - change status of customer
    - `POST retail/m/customer/<customer_id>/transaction` - add or deduct credits from customer's balance
    - `GET  retail/m/customers` - list customers and their balance
    - `GET  retail/m/customers/activation/history` - list activation history of customers
    - `GET  retail/m/customers/transactions` - list customers finanicial transactions

    ### Application endpoints

    This endpoint is used to run application operation for single customer. E.g. create and manage activation for customer, get balance, transactions, etc. These endpoints has prefix `/a/`. These endpoints require `customer_id` to be included in the URL.

    - `POST retail/a/customer/<customer_id>/activation` - create new activation
    - `GET  retail/a/customer/<customer_id>/activations` - list active activations of customer
    - `GET  retail/a/customer/<customer_id>/activation/<activation_id>` - get activation details
    - `PUT  retail/a/customer/<customer_id>/activation/{activation_id}/retry` - request one more SMS message from the same phone number
    - `PUT  retail/a/customer/<customer_id>/activation/{activation_id}/cancel` - cancel activation
    - `GET  retail/a/customer/<customer_id>/activation/history` - list activation history of customer
    - `GET  retail/a/customer/<customer_id>/balance` - get customer balance
    - `GET  retail/a/customer/<customer_id>/transactions` - list customer financial transactions

    **Catalog**

    - [Get countries](#tag/Catalog/operation/getCountries) - Get a list of countries where mobile phone numbers are provided.
    - [Get services](#tag/Catalog/operation/getServices) - Get a list of services eligible for activation.

    **Prices**

    - [Get prices by service](#tag/Prices/operation/getPriceByService) - Get a price list organized by service.
    - [Get prices by country](#tag/Prices/operation/getPriceByCountry) - Get a price list organized by country.
    - [Get price for service in country](#tag/Prices/operation/getPrice) - Get a price for specific service and country.

    **Balance**

    - [Get balance](#tag/User/operation/getUserBalance) - Get your account balance.

    ## Activation flow

    1. Request number for specific service and country. In response you will get activation `id` and `phone`.
    2. Ask service to send SMS to `phone`.
    3. Poll the Platfone API using the activation `id` at 10-second intervals to receive SMS. Continue this process until the either `expire_at` timestamp is exceeded or `sms_status = smsReceived`. If the status is `smsReceived`, you can use the code and message from the response and stop polling. If supported you can request one more SMS message from the same number, using retry activation endpoint.

    ![image](https://temp-number.sfo3.cdn.digitaloceanspaces.com/act/docs/diagrams/sms-verification-diagram.svg)

    ## Rate limits

    There are three different types of rate limits you should be aware of:

    - minimum success rate
    - maximum active activations
    - API endpoints maximum requests per time period

    In the event of a block, you will receive a 429 error code, along with information on when your account will be unblocked.

    ### Minimum success rate

    To prevent the scanning of phone numbers, a minimum success rate for receiving SMS messages is required to be maintained. If your success rate falls below 7%, your account will be subjected to a 24-hour block.

    The success rate is calculated within a 24-hour window as follows:

    ![image](https://temp-number.sfo3.cdn.digitaloceanspaces.com/act/docs/diagrams/success_rate.svg)

    Note: The calculation of the success rate starts after the 10th number has been ordered.

    You have the option to unblock your account from within your dashboard 3 times in 24 hours.

    ### Maximum active activations

    To prevent abuse, the maximum number of active activations is limited to **20**. If you reach this limit, you will receive a 429 error code. You can cancel an active activation to free up space for a new one. If you need more than 20 active activations, please contact us.

    ### API methods (rate limiting)

    To ensure optimal performance, the following API methods are subject to these rate limits:

    | Method | Path                                                         | Limit                     |
    | ------ | ------------------------------------------------------------ | ------------------------- |
    | GET    | user/balance                                                 | 300 requests per 1 minute |
    | POST   | activation                                                   | 300 requests per 1 minute |
    | PUT    | activation/:id/retry                                         | 50 requests per 1 minute  |
    | PUT    | activation/:id/cancel                                        | 50 requests per 1 minute  |
    | GET    | activation/history                                           | 6 requests per 1 minute   |
    | GET    | activation/:id                                               | 300 requests per 1 minute |
    | GET    | activation/countries                                         | 15 requests per 1 minute  |
    | GET    | activation/services                                          | 15 requests per 1 minute  |
    | GET    | activation/prices/countries                                  | 6 requests per 1 minute   |
    | GET    | activation/prices/services                                   | 6 requests per 1 minute   |
    | GET    | activation/prices/services/:service_id/countries/:country_id | 60 requests per 1 minute  |

    ## Versioning

    The API is subject to change without notice. We will try to keep the API backwards compatible, but we cannot guarantee it. If we make backwards incompatible changes, we will release a new version of the API. The version will be included in the URL. For example, if the current version is `v1`, the URL will be `https://temp-number-api.com/api/v1`. If we release a new version, the URL will be `https://temp-number-api.com/api/v2`.

    ---
servers:
  - url: https://temp-number-api.com/api/v1/retail
security:
  - apikey_auth: []
tags:
  - name: Management endpoints
    description: |
      This section includes endpoints for managing customers and get general information about retail service usage.
      E.g. create customer, disable customer, get customers list, get activation history of all customers, get all transactions, etc.
      Endpoints have prefix `retail/m/`.
  - name: Application endpoints
    description: |
      This section includes endpoints used by your application to operate on a single customer.
      Examples include creating and managing activation for a customer, retrieving his balance, transactions, etc.
      Endpoints have the prefix `retail/a/`.
  - name: Prices
    description: |
      Endpoints for obtaining activation prices.
      Activation costs vary by service and country. **All prices are in USD cents**.
      You will also get the number of available phone numbers for sale.
      We provide minimum, maximum, and suggested prices per service and country. Use `max_price` to set your price limit.
      Prices reflect the developer's cost for activation. Adjust these prices before displaying them to customers.
  - name: Catalog
    description: |
      The catalog includes endpoints used to retrieve lists of countries and services available for activation.
      The list of services is regularly updated, with new services added to the catalog as they become available.
      These lists contain the IDs of the countries and services, which are utilized in the activation process.
      Before ordering a number, you should first verify the availability of the service and country through the price endpoints.

      You get icons for services and countries in the catalog by calling:
      - `https://temp-number.sfo3.cdn.digitaloceanspaces.com/retail/countries/<country_id>.svg`
      - `https://temp-number.sfo3.cdn.digitaloceanspaces.com/retail/services/<service_id>.png`
  - name: Webhooks 📡
    description: |
      Webhooks provide real-time notifications when significant state changes occur within the system. They enable external systems to react to updates without polling the API.

      For more details on setting up and handling webhooks, refer to the [Webhook Guide](https://platfone.com/docs/api/webhooks/webhooks/).
paths:
  /m/customer:
    post:
      tags:
        - Management endpoints
      summary: Create new customer
      description: |
        Create new customer and set initial balance.
      operationId: createCustomer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: NewCustomer
              required:
                - customer_id
              properties:
                customer_id:
                  type: string
                  example: xDWxt7dd6efro3yWL4qfuEWjvAz1
                  description: ID of customer. Must be unique.
                  format: ^[a-zA-Z0-9]+$
                  minLength: 1
                  maxLength: 80
                balance:
                  type: integer
                  description: Initial customer balance in USD cents. If it is greater than zero, financial transaction will be added with `purchase_id = initial` to customer transactions.
                  example: 90
                  minimum: 0
                  maximum: 100000
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409CustomerExists'
        '429':
          description: Rate limit exceeded error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X POST ${server_base_path}/api/v1/retail/m/customer" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE" \
            -d '{"customer_id": "xDWxt7dd6efro3yWL4qfuEWjvAz1", "balance": 500}'
  /m/customer/{customer_id}:
    put:
      tags:
        - Management endpoints
      summary: Change customer
      description: |
        Change customer status.

        Available statuses:
        - `disabled` - customer is disabled. All customers operations are restricted.
        - `active` - customer is active. All customers operations are allowed.
        - `paused` - customer is paused. New activations are restricted.
        - `markedForDeletion` - customer is marked for deletion. All customers operations are restricted.
      operationId: changeCustomer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: ChangedCustomer
              required:
                - status
              properties:
                status:
                  type: string
                  example: paused
                  description: New customer status. Can be `disabled`, `active`, `paused`, `markedForDeletion`.
                  enum:
                    - disabled
                    - active
                    - paused
                    - markedForDeletion
      responses:
        '200':
          $ref: '#/components/responses/200'
        '202':
          description: Request accepted and the customer is marked for deletion; deletion is not immediate.
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X PUT ${server_base_path}/api/v1/retail/m/customer/${customer_id}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE" \
            -d '{"status": "disabled"}'
  /m/customers:
    get:
      tags:
        - Management endpoints
      summary: Get customers
      description: |
        Get customers list with their statuses and balances. Filter by status, customer_id and creation date.
      operationId: getCustomers
      parameters:
        - name: customer_id
          in: query
          description: ID of customer to get single customer.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            pattern: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
        - name: status
          in: query
          description: Array of customer statuses to filter. If empty, all customers will be returned.
          schema:
            type: array
            items:
              type: string
              enum:
                - disabled
                - active
                - paused
                - markedForDeletion
          style: form
          explode: false
          example:
            - disabled
            - active
        - name: created_from_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only customers created after this timestamp will be returned.
          schema:
            type: integer
            example: 1632400000
        - name: created_to_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only customers created before this timestamp will be returned.
          schema:
            type: integer
            example: 1632486400
        - name: page
          in: query
          description: Selected page number. Default is 1.
          schema:
            type: integer
            example: 3
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Maximum number of customers to return. Default is 100. If not provided, 100 customers will be returned.
          schema:
            type: integer
            example: 10
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          $ref: '#/components/responses/CustomersList'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          description: Rate limit exceeded error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/m/customers?customer_id=${customer_id}&status=${status}&created_from_timestamp=${created_from_timestamp}&created_to_timestamp=${created_to_timestamp}&page=${page}&limit=${limit}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /m/customers/activation/history:
    get:
      tags:
        - Management endpoints
      summary: Get customers activation history
      description: |
        Get customers activation history. Filter by customer_id, status and creation date.
      operationId: getCustomersActivationHistory
      parameters:
        - name: customer_id
          in: query
          description: ID of customer to get single customer.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            pattern: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
        - name: sms_status
          in: query
          description: Array of sms_status to filter. Empty array will return all activations.
          schema:
            type: array
            items:
              type: string
              enum:
                - smsRequested
                - smsReceived
                - retryRequested
                - retryReceived
                - retryReceived
          style: form
          explode: false
          example:
            - smsRequested
            - smsReceived
        - name: activation_status
          in: query
          description: Array of activation_status to filter. Empty array will return all activations.
          schema:
            type: array
            items:
              type: string
              enum:
                - active
                - finalized
                - expired
                - canceled
          style: form
          explode: false
          example:
            - expired
            - canceled
        - name: billing_status
          in: query
          description: Array of billing_status to filter. Empty array will return all activations.
          schema:
            type: array
            items:
              type: string
              enum:
                - reserved
                - released
                - billed
                - refunded
          style: form
          explode: false
          example:
            - released
            - refunded
        - name: created_from_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only activations created after this timestamp will be returned.
          schema:
            type: integer
            example: 1632400000
        - name: created_to_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only activations created before this timestamp will be returned.
          schema:
            type: integer
            example: 1632486400
        - name: page
          in: query
          description: Selected page number. Default is 1.
          schema:
            type: integer
            example: 3
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Maximum number of customers to return per page. Default is 100. If not provided, 100 customers will be returned.
          schema:
            type: integer
            example: 10
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          $ref: '#/components/responses/CustomersActivationHistory'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          description: Rate limit exceeded error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/m/customers/activation/history?customer_id=${customer_id}&status=${status}&created_from_timestamp=${created_from_timestamp}&created_to_timestamp=${created_to_timestamp}&page=${page}&limit=${limit}"
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /m/customers/transactions:
    get:
      tags:
        - Management endpoints
      summary: Get customers transactions
      description: |
        Get customers transactions list. Filter by purchase_id, customer_id and creation date.
      operationId: getCustomersTransactions
      parameters:
        - name: customer_id
          in: query
          description: ID of customer to get single customer.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            pattern: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
        - name: transaction_id
          in: query
          description: ID of transaction to get single transaction.
          schema:
            type: string
            example: 63f4d0dab040a865d80da08a
            pattern: ^[a-zA-Z0-9_]+$
            minLength: 1
            maxLength: 80
        - name: created_from_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only transactions created after this timestamp will be returned.
          schema:
            type: integer
            example: 1632400000
        - name: created_to_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only transactions created before this timestamp will be returned.
          schema:
            type: integer
            example: 1632486400
        - name: page
          in: query
          description: Selected page number. Default is 1.
          schema:
            type: integer
            example: 3
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Maximum number of transactions to return. Default is 100. If not provided, 100 customers will be returned.
          schema:
            type: integer
            example: 10
            default: 100
            minimum: 1
            maximum: 1000
      responses:
        '200':
          $ref: '#/components/responses/CustomersTransactions'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          description: Rate limit exceeded error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/m/customers?customer_id=${customer_id}&transaction_id=${transaction_id}&created_from_timestamp=${created_from_timestamp}&created_to_timestamp=${created_to_timestamp}&page=${page}&limit=${limit}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /m/customer/{customer_id}/transaction:
    post:
      tags:
        - Management endpoints
      summary: Create customer transaction
      description: |
        Create new financial transaction for customer.
      operationId: createCustomerTransaction
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: NewCustomerTransaction
              required:
                - transaction_id
                - amount
              properties:
                transaction_id:
                  type: string
                  example: xDWxt7dd6efro3yWL4qfuEWjvAz1
                  description: ID of financial transaction. Must be unique. If it is not unique, the transaction will be rejected.
                  format: ^[a-zA-Z0-9]+$
                  minLength: 1
                  maxLength: 80
                amount:
                  type: integer
                  description: |
                    Amount in USD cents to add or deduct to/from customer balance.
                    If amount is positive, it will be added to customer balance.
                    If amount is negative, it will be deducted from customer balance.
                    Note: Customer balance may be negative.
                  example: -350
                  minimum: -100000
                  maximum: 100000
                gateway:
                  type: string
                  example: stripe
                  description: Payment gateway used for transaction.
                  minLength: 1
                  maxLength: 50
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '409':
          $ref: '#/components/responses/409CustomerTransactionExists'
        '429':
          description: Rate limit exceeded error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X POST ${server_base_path}/api/v1/retail/m/customer/${customer_id}/transaction" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE" \
            -d '{"purchase_id": "xDWxt7dd6efro3yWL4qfuEWjvAz1", "amount": 950}'
  /m/activation/prices/services/{service_id}/countries/{country_id}:
    get:
      tags:
        - Prices
      summary: Price for a Service in a Country
      description: |
        Retrieve the price and availability for a specific service in a specific country. 
        Use `service_id` and `country_id` to specify the service and country, respectively. 
        These identifiers can be found via the `getServices` and `getCountries` operations.
      operationId: getPrice
      parameters:
        - name: service_id
          in: path
          required: true
          description: Service ID, as returned by `getServices` operation.
          schema:
            type: string
            example: 7eleven
            format: ^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-_]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-_]*[A-Za-z0-9])$
            minLength: 1
            maxLength: 30
        - name: country_id
          in: path
          required: true
          description: Country ID, as returned by the `getCountries` operation.
          schema:
            type: string
            example: uk
            pattern: ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
            minLength: 2
            maxLength: 9
      responses:
        '200':
          $ref: '#/components/responses/Price'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/activation/prices/services/${service_id}/countries/${country_id}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /m/activation/prices/countries:
    get:
      tags:
        - Prices
      summary: Price list organized by country
      description: |
        Retrieve a comprehensive price list, organized by country. 
        This endpoint returns a list of countries, each accompanied by an array of services available within that country, their respective prices, and the amount of available numbers for sale.

        Use optional `country_id` query parameter to get prices in a specific country.
      operationId: getPriceByCountry
      parameters:
        - name: country_id
          in: query
          description: Country ID, as returned by the `getCountries` operation.
          schema:
            type: string
            example: uk
            pattern: ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
            minLength: 2
            maxLength: 9
      responses:
        '200':
          $ref: '#/components/responses/PricesByCountry'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/retial/m/prices/countries" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /m/activation/prices/services:
    get:
      tags:
        - Prices
      summary: Price list organized by service
      description: |
        Retrieve a comprehensive price list, organized by service. This endpoint returns a list of services, each accompanied by an array of countries available for that service, their respective prices, and the amount of available numbers for sale.

        Use optional `service_id` query parameter to get prices for a specific service.
      operationId: getPriceByService
      parameters:
        - name: service_id
          in: query
          description: Service ID, as returned by `getServices` operation.
          schema:
            type: string
            example: 7eleven
            format: ^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$
            minLength: 1
            maxLength: 30
      responses:
        '200':
          $ref: '#/components/responses/PricesByService'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/activation/prices/services" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /m/firebase/project_url:
    put:
      tags:
        - Management endpoints
      summary: Add firebase project url
      description: Add firebase project url
      operationId: addFirebaseProjectUrl
      requestBody:
        content:
          application/json:
            schema:
              title: UserProject
              type: object
              properties:
                url:
                  type: string
                  example: https://us-central1-<project-id>.cloudfunctions.net
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
  /a/customer/{customer_id}/activation:
    post:
      tags:
        - Application endpoints
      summary: Order number for activation
      description: |
        Returns a mobile phone number for service activation and an associated activation ID. Use the activation ID to retrieve the received SMS via `GET /retail/a/customer/:customer_id/activation/:activation_id`.

        ### Basics

        - **Ordering**: Provide `service_id` and `country_id` to order a number. Use `GET /activation/services` and `GET /activation/countries` to fetch available IDs.
        - For unsupported services, use the special `other` service.
        - The `is_retriable` flag in the response indicates whether the number can receive multiple SMS messages.

        ---

        ### Billing Conditions

        - **No SMS, No Charge**: Neither the developer nor customer is billed unless an SMS is received.
        - **First SMS Only**: Billing is triggered only by the **first** SMS received.

        ---

        ### Billing Overview

        - **Developer Cost**: You are billed for the actual activation price (capped by your `max_price`) **only if an SMS is received**.
        - **Customer Cost**: The customer is billed based on your selected billing mode (`fixed` or `dynamic`) **only if an SMS is received**.
        - **Customer Price vs. Customer Cost**:
          - **Customer Price** is the price *you display to your customer*.
          - **Customer Cost** is the *actual amount deducted* from the customer's balance.
          - In **dynamic billing**, **customer cost may be lower than the displayed price** if a cheaper offer is matched.

        ---

        ### Customer Billing Modes (`customer_billing_type`)

        #### 1. `fixed` Mode

        - Price is determined upfront.
        - Two options are available:

          **Option A: Fixed Customer Price**
          - Set `customer_price` directly.
          - This value is billed to the customer if SMS is received.
          - `max_price` affects only the developer's cost.

          **Option B: Fixed Customer Markup**
          - Set `customer_markup` (in %).
          - Customer price is calculated as:
            `customer_price = max_price * (1 + customer_markup / 100)`
          - The calculated price is billed to the customer.

        #### 2. `dynamic` Mode

        - Final price is determined only after a number is matched.
        - Set `customer_markup` (in %); do **not** include `customer_price`.
        - Estimated customer price can be shown using:
          `customer_price = max_price * (1 + customer_markup / 100)`
        - Actual **customer cost** is:
          `customer_cost = activation_price * (1 + customer_markup / 100)`, where `activation_price` is the actual price of the activation and less than or equal to `max_price`.

        ---

        ### Price Control

        **Developer `max_price`:**  
        - Limits your maximum cost for activation (in USD cents).
        - If no number is found within limit, a `409 MaxPriceExceededException` is returned with:
            - `suggestedPrice` - the nearest available price above your current max
            - `order_id` - a unique continuation token to retry the activation attempt


        ### 🔄 Handling Price Changes

        The temporary number market is highly dynamic, with prices shifting minute by minute.

        If no phone number is available within your specified `max_price`, the request will fail with a:

        ```
        409 MaxPriceExceededException
        ```

        The response includes:
        - `suggestedPrice`: the nearest available price above your current max
        - `order_id`: a **unique retry token** that allows you to resume the same activation attempt

        ### 🔁 Retrying an Activation Attempt

        To retry with the same activation context:
        1. Optionally inform the customer of the new price based on `suggestedPrice`
        2. Resubmit the request with:
          - The **same `order_id`**
          - An updated `max_price` (e.g., equal to `suggestedPrice`)

        This ensures a smooth continuation of the original attempt, avoids unnecessary resource consumption, and improves overall success rate.

        ---

        ### Quality Considerations

        We constantly monitor the quality of our phone number suppliers. Since higher quality numbers have a better chance of successfully receiving SMS messages, we recommend taking quality into account when ordering numbers.

        **Quality Factor:** The `quality_factor` parameter allows you to balance quality against price. This parameter is an integer ranging from 0 to 100, with a default value of 50.
        - A value of 0 means you prioritize price, essentially disregarding quality in the number selection process.
        - A value of 50 indicates you value price and quality equally, offering a balanced approach in your selection.
        - A value of 100 indicates a preference for quality, making it the primary criterion for number selection, regardless of price.
      operationId: newActivation
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: NewActivation
              oneOf:
                - $ref: '#/components/schemas/NewActivationFixedCustomerMarkup'
                - $ref: '#/components/schemas/NewActivationFixedCustomerPrice'
                - $ref: '#/components/schemas/NewActivationDynamic'
      responses:
        '200':
          $ref: '#/components/responses/CustomerNewActivation'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402PaymentRequired'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404NoNumbers'
        '409':
          $ref: '#/components/responses/409MaxPriceExeeded'
        '429':
          description: Rate limit exceeded exception
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error429TooManyRequests'
                  - $ref: '#/components/schemas/error429LowSuccessRate'
                  - $ref: '#/components/schemas/error429TooManyActivations'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X POST ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE" \
            -d '{"customer_price": 200, "service_id": "7eleven", "country_id": "us", "max_price": 90, "quality_factor": 90}'
  /a/customer/{customer_id}/activations:
    get:
      tags:
        - Application endpoints
      summary: Get active activations
      description: Fetches active activations IDs. Optionally include activation data.
      operationId: getActiveActivations
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
        - in: query
          name: with_data
          required: false
          description: Include activation data
          schema:
            type: boolean
            example: true
            default: false
      responses:
        '200':
          description: Active activations
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CustomerActiveActivationsIds'
                  - $ref: '#/components/schemas/CustomerActiveActivationsWithData'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activations" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/{activation_id}:
    get:
      tags:
        - Application endpoints
      summary: Get activation state
      description: |
        Retrieve the activation state, including activation status, sms status, billing status, expiration, SMS code and text message, etc.    
        Typically, this endpoint is polled either until the SMS is received or the activation expires.

        ### Statuses

        There are several statuses that an activation can have, each representing a different state of the activation process. The following are the possible statuses:

        #### 💬 sms_status

        - **Description**: Represents the current state of the SMS interaction within the activation process.
        - **Possible Values**:
          - `"smsRequested"`: The initial state when an SMS is requested but not yet received.
          - `"smsReceived"`: The SMS has been received.
          - `"retryRequested"`: The user has requested another SMS.
          - `"retryReceived"`: The user has received a another SMS.

        #### 🔁 activation_status
        - **Description**: Represents the overall state of the activation.
        - **Possible Values**:
          - `"active"`: The activation is currently active and can proceed.
          - `"finalized"`: The user has confirmed the activation, and no further changes are possible.
          - `"expired"`: The activation has expired based on the `expire_at` timestamp.
          - `"canceled"`: The activation was canceled before any SMS was received.

        #### 💳 billing_status
        - **Description**: Indicates the billing state of the activation.
        - **Possible Values**:
          - `"reserved"`: Funds are reserved from the user's available balance upon activation creation.
          - `"released"`: No SMS was received, and reserved funds were returned to the available balance.
          - `"billed"`: An SMS was received, and the reserved funds have been charged.
          - `"refunded"`: A refund was issued after a user report, and the amount was returned to the available balance.

        #### 📝 report_status
        - **Description**: Represents the status of report filed by the user regarding the activation (e.g., reporting a wrong SMS).
        - **Possible Values**:
          - `null`: No report has been made.
          - `"inReview"`: The report is under review.
          - `"declined"`: The report was reviewed, and no refund was granted.
          - `"approved"`: The report was reviewed, and a refund was issued.

        ### Expiration

        Each activation has a limited lifetime. The expiration time of an activation can be determined by the `expire_at` attribute. If the activation is not completed within this timeframe, it will expire, and no further SMS retrievals will be possible.

        ## Usage Notes
        - **Expiration Handling**: Developers should validate the `expire_at` field to ensure the activation is still valid. If the current time is past `expire_at`, consider the activation expired, even if the `activation_status` field has not yet been updated to `"expired"`.
        - **Finalization**: The `activation_status` field includes `"finalized"` to indicate that the activation has been confirmed by the user, and no further changes are allowed. Finalized activations should be removed from the active activations list.
        - **Reporting**: Use the `report_status` field to track the outcome of any user reports regarding issues with the activation. This field is closely related to the `billing_status` if a refund is issued.
        - **Cancellation**: The `cancelable_after` field indicates when an activation can be canceled. If this field is `null`, the activation does not support cancellation. If the current time is past the `cancelable_after` timestamp, the activation can be canceled using `cancel` operation.
        - **Retry Handling**: The `is_retriable` field indicates whether the user can request another SMS. If `true`, the user can request a retry SMS using the `retry` operation. Retry possible after first sms recieved and while `activation_status` is `active`.
        - **Billing**: The `price` field indicates the cost of the activation in USD cents. The amount is reserved from the user's available balance when the activation is created. The `billing_status` field indicates the current billing state of the activation.
      operationId: getActivation
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/CustomerActivation'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/{activation_id}/retry:
    put:
      tags:
        - Application endpoints
      summary: Retry activation
      description: |
        Instructs the server to overwrite the previous SMS with the first one arriving. 
        Both "code" and "text" fields will be updated. 
        This operation is free of charge, as billing occurs upon receipt of the first SMS.

        This operation is only possible if:
          - `sms_status` of the activation is either `smsReceived` or `retryReceived`.
          - `activation_status = active`.
          - Activation attribute `is_retriable = true`.
      operationId: retryActivation
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X PUT ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}/retry" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/{activation_id}/cancel:
    put:
      tags:
        - Application endpoints
      summary: Cancel activation
      description: |
        Typically, you can cancel an active activation as long as no SMS has been received.    
        The `cancelable_after` field indicates when an activation can be canceled:
        - If this field is `null`, the activation does not support cancellation.
        - If the current time is past the `cancelable_after` timestamp, the activation can be canceled using `cancel` operation.

        Cancellation is only possible if:
        - `activation_status = active`.
        - `sms_status = smsRequested`.
        - `cancelable_after` allows cancelation.
      operationId: cancelActivation
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '409':
          description: Can't cancel activation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error409'
                  - $ref: '#/components/schemas/error409EarlyCancelDenied'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X PUT ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}/cancel" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/{activation_id}/finalize:
    put:
      tags:
        - Application endpoints
      summary: Finalize activation
      description: |
        Finalize an activation to prevent further SMS messages from being sent to the phone number and to reduce the number of active numbers.

        Finalize is only possible if:
          - `sms_status` of the activation is either of `smsReceived`, `retryRequested` or `retryReceived`.
          - `activation_status = active`
          - `billing_status = billed`
      operationId: finalizeActivation
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X PUT ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}/finalize" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/history:
    get:
      tags:
        - Application endpoints
      summary: Get activations history
      description: Fetches a history of activations, offering a comprehensive overview of past activation records. Each record includes details such as the activation ID, phone number, country ID, service ID, statuses, SMS code, SMS text, and timestamps for expiration and last update. The response is organized in a paginated format, allowing for efficient navigation through the activation records.
      operationId: getActivationsHistory
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
        - name: exclude_reported
          in: query
          required: false
          description: If true, only activations where `report_status` is `null` will be returned. If set `exclude_active` and `only_expired` are ignored.
          schema:
            type: boolean
            example: true
            default: false
        - name: exclude_active
          in: query
          required: false
          description: If true, only activations where `activation_status` is not `active` will be returned. If set `only_expired` is ignored.
          schema:
            type: boolean
            example: true
            default: false
        - in: query
          name: only_expired
          required: false
          description: If true, only activations where `activation_status` is `expired` will be returned.
          schema:
            type: boolean
            example: true
            default: false
        - in: query
          name: page
          required: false
          description: Selected page number
          schema:
            type: integer
            example: 3
            description: Selected page number
            default: 1
        - in: query
          name: limit
          required: false
          description: Items limit per page
          schema:
            type: integer
            example: 10
            description: Items limit per page
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          $ref: '#/components/responses/CustomersActivationHistory'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/history" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customers/{customer_id}:
    get:
      tags:
        - Application endpoints
      summary: Get customer info
      description: Retrieve information about a specific customer.
      operationId: getCustomerInfo
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
      responses:
        '200':
          $ref: '#/components/responses/CustomerInformation'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/a/customer/${customer_id}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/balance:
    get:
      tags:
        - Application endpoints
      summary: Get balance
      description: |
        Retrieves the current balance of customer, which is provided in USD cents. Note that there may be a slight delay in the balance update.
        - Total: The total available balance, in USD cents.
        - Reserved: The portion of the balance reserved for activations that have not yet been completed, also in USD cents.
      operationId: getUserBalance
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
      responses:
        '200':
          $ref: '#/components/responses/CustomerBalance'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/a/customer/${customer_id}/balance" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/transactions:
    get:
      tags:
        - Application endpoints
      summary: Get transactions
      description: |
        Get transactions list of customer. Filter by creation date.
      operationId: getCustomerTransactions
      parameters:
        - name: customer_id
          in: path
          required: true
          description: ID of customer. Must be unique.
          schema:
            type: string
            example: xDWxt7dd6efro3yWL4qfuEWjvAz1
            format: ^[a-zA-Z0-9]+$
            minLength: 1
            maxLength: 80
        - name: created_from_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only transactions created after this timestamp will be returned.
          schema:
            type: integer
            example: 1632400000
        - name: created_to_timestamp
          in: query
          description: Unix timestamp in seconds. If provided, only transactions created before this timestamp will be returned.
          schema:
            type: integer
            example: 1632486400
        - name: page
          in: query
          description: Selected page number. Default is 1.
          schema:
            type: integer
            example: 3
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Maximum number of transactions to return. Default is 100. If not provided, 100 customers will be returned.
          schema:
            type: integer
            example: 10
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          $ref: '#/components/responses/CustomerTransactions'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '429':
          description: Rate limit exceeded error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/retail/a/customer/${customer_id}/transactions?transaction_id=${transaction_id}&created_from_timestamp=${created_from_timestamp}&created_to_timestamp=${created_to_timestamp}&page=${page}&limit=${limit}" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/activation/countries:
    get:
      tags:
        - Catalog
      summary: Get countries
      description: |
        Returns a list of countries, including each country's unique identifier and name.
        Use the `country_id` to specify the country when creating an activation.
        Countries that has suffix `_v` in their `country_id` are countries that contains only virtual mobile phone numbers. E.g. `us_v` is `United States (Virtual)` containing virtual mobile phone numbers in USA.
      operationId: getCountries
      parameters:
        - in: header
          name: If-None-Match
          description: Optional header for cache validation based on X-ETag.
          required: false
          schema:
            type: string
            example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465
      responses:
        '200':
          $ref: '#/components/responses/Countries'
        '304':
          $ref: '#/components/responses/304NotModified'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/countries" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/activation/services:
    get:
      tags:
        - Catalog
      summary: Get services
      description: |
        Returns a list of services, including each service unique identifier and name. Use the `service_id` to specify the service when creating an activation.

        Service with ID `other` is special service that must be used when you want to get number for service activation that is not listed in the services list. Please note that using the `other` service for activating services that are listed may result in account suspension.
      operationId: getServices
      parameters:
        - in: header
          name: If-None-Match
          description: Optional header for cache validation based on X-ETag.
          required: false
          schema:
            type: string
            example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465
      responses:
        '200':
          $ref: '#/components/responses/Services'
        '304':
          $ref: '#/components/responses/304NotModified'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/retail/services" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/activation/services/popular:
    get:
      tags:
        - Catalog
      summary: Get popular services
      description: |
        Returns a list of popular services. It may be used to show the most popular services to the user to simplify the selection process.

        Service with ID `other` is special service that must be used when you want to get number for service activation that is not listed in the services list. Please note that using the `other` service for activating services that are listed may result in account suspension.
      operationId: getPopularServices
      parameters:
        - in: header
          name: If-None-Match
          description: Optional header for cache validation based on X-ETag.
          required: false
          schema:
            type: string
            example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465
      responses:
        '200':
          $ref: '#/components/responses/Services'
        '304':
          $ref: '#/components/responses/304NotModified'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/retail/a/activation/services/popular" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/{activation_id}/report/reasons:
    get:
      tags:
        - Application endpoints
      summary: Get available report reasons for activation
      description: |
        Returns a list of available report reasons IDs with name and evidence requirements for activation. 
        Reasons list depends on current activation state. 

        **Workflow**:
        1. **Get Available Report Reasons**: Before creating a report, you must first retrieve the available report reasons for the specific activation using the `getActivationReportReasons` endpoint. 
        Along with the list of valid report reason IDs, you will also get if evidence is required.
        2. **Create Report**: Create a report for the same activation by passing one of the available reason IDs along with evidence, if required.

          Use IDs from response to create report for the same activation you got reasons for.

        **Full list of Report Reasons:**

        | ID | Reason name              |
        |----|--------------------------|
        | 1  | SMS is not coming        |
        | 2  | Wrong SMS received       |
        | 3  | Service not accepting the number |
        | 4  | Number has been used before |
        | 5  | Blocked after activation |
        | 6  | SMS received too late    |
        | 7  | Other reason             |
      operationId: getActivationReportReasons
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/ReportReasons'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '409':
          description: Can't report activation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error409'
                  - $ref: '#/components/schemas/error409ReportCreationDeadline'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET ${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}/report/reasons" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/{activation_id}/report:
    post:
      tags:
        - Application endpoints
      summary: Report activation
      description: |
        This endpoint allows you to create a report for a specific activation.

        **Important**: _Only one report can be created per activation.  Submitting invalid or incomplete data may result in the report being declined._

        **Declined Report Response Details**:

        If the report is not accepted, you will receive a response with a `decline_id`. Below are the possible reasons corresponding to each `decline_id`:

        | **Decline ID** | **Reason**                      |
        |----------------|---------------------------------|
        | 1              | Try another number              |
        | 2              | Retry using the same number     |

        **Workflow**:

        1. **Retrieve Available Report Reasons**: Before creating a report, you must first retrieve the available report reasons for the specific activation using the `getActivationReportReasons` endpoint. 
           This will return a list of valid report reason IDs based on the current state of the activation, along with any evidence requirements.

        2. **Submit a Report**: Once you have obtained the list of valid report reasons, you can create a report by selecting an appropriate reason ID and including any required evidence. 
           If required, the evidence parameter must be provided in `base64` format, following the guidelines outlined in the request body specification.

        Ensure that the reason ID and any accompanying evidence match the list returned by the `getActivationReportReasons` endpoint.
      operationId: reportActivation
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ActivationReportRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/200Report'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '409':
          description: Can't report activation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error409'
                  - $ref: '#/components/schemas/error409ReportCreationDeadline'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X POST "${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}/report" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE" \
            -d '{"reason_id": 4, "message": "2FA enabled here"}'
    get:
      tags:
        - Application endpoints
      summary: Get report
      description: Return a report object by Activation Id
      operationId: getReport
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/CustomerReport'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Resource not found exception
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/error404CustomerNotFound'
                  - $ref: '#/components/schemas/error404'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/${activation_id}/report" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/customer/{customer_id}/activation/reports:
    get:
      tags:
        - Application endpoints
      summary: Get reports
      description: Returns a list of reports with pagination
      operationId: getReports
      parameters:
        - $ref: '#/components/parameters/customer_id'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          $ref: '#/components/responses/CustomerReports'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404CustomerNotFound'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "${server_base_path}/api/v1/retail/a/customer/${customer_id}/activation/reports" \
            -H "Content-Type: application/json" \
            -H "x-api-key: YOUR_API_KEY_HERE"
  /a/currency-rate:
    get:
      tags:
        - Catalog
      summary: Get currency rate
      description: |
        Returns the current currency exchange rate used for conversions on the platform
      operationId: getCurrencyRate
      parameters:
        - in: query
          name: currency
          required: true
          description: Currency code to get the exchange rate for
          schema:
            type: string
            enum:
              - USD
              - EUR
              - CNY
              - RUB
            example: USD
      responses:
        '200':
          $ref: '#/components/responses/CurrencyRate'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429TooManyRequests'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -G "${server_base_path}/api/v1/retail/a/currency-rate?currency=USD" \
            -H "x-api-key: YOUR_API_KEY_HERE" \
            -H "Accept: application/json"
webhooks:
  customerActivationUpdated:
    post:
      tags:
        - Webhooks 📡
      summary: Customer activation updated webhook
      description: |
        Issued when an activation's `sms_status` changes to either:
        - `smsReceived`
        - `retryReceived`

        This event can be used to notify the customer when sms is received.
      operationId: activationUpdatedWebhook
      security: []
      parameters:
        - $ref: '#/components/parameters/x-webhook-id'
        - $ref: '#/components/parameters/x-timestamp'
        - $ref: '#/components/parameters/x-signature'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RetailWebhook'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/CustomerActivation'
      responses:
        '200':
          $ref: '#/components/responses/200'
  customerActivationReportUpdated:
    post:
      tags:
        - Webhooks 📡
      summary: Activation report status updated webhook
      description: |
        Issues a webhook when the activation report status is updated.
      operationId: activationReportUpdatedWebhook
      security: []
      parameters:
        - $ref: '#/components/parameters/x-webhook-id'
        - $ref: '#/components/parameters/x-timestamp'
        - $ref: '#/components/parameters/x-signature'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RetailWebhook'
                - type: object
                  properties:
                    data:
                      type: object
                      title: ActivationReportUpdated
                      properties:
                        customer_id:
                          $ref: '#/components/schemas/customer_id'
                        activation_id:
                          $ref: '#/components/schemas/activation_id'
                        report_status:
                          $ref: '#/components/schemas/report_status'
      responses:
        '200':
          $ref: '#/components/responses/200'
  customerlowBalance:
    post:
      tags:
        - Webhooks 📡
      summary: Customer low balance webhook
      description: |
        Issues a webhook when the customer's balance is low.
      operationId: customerLowBalanceWebhook
      security: []
      parameters:
        - $ref: '#/components/parameters/x-webhook-id'
        - $ref: '#/components/parameters/x-timestamp'
        - $ref: '#/components/parameters/x-signature'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RetailWebhook'
                - type: object
                  properties:
                    data:
                      type: object
                      title: CustomerBalance
                      properties:
                        customer_id:
                          $ref: '#/components/schemas/properties-customer_id'
                        balance:
                          $ref: '#/components/schemas/balance'
      responses:
        '200':
          $ref: '#/components/responses/200'
  customerUpdated:
    post:
      tags:
        - Webhooks 📡
      summary: Customer status updated webhook
      description: |
        Issues a webhook when the customer's status is updated.
      operationId: customerUpdatedWebhook
      security: []
      parameters:
        - $ref: '#/components/parameters/x-webhook-id'
        - $ref: '#/components/parameters/x-timestamp'
        - $ref: '#/components/parameters/x-signature'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/RetailWebhook'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/Customer'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200'
  accountLowBalance:
    post:
      tags:
        - Webhooks 📡
      summary: Main account low balance webhook
      description: |
        Issues a webhook when the account's balance is low.
      operationId: accountLowBalanceWebhook
      security: []
      parameters:
        - $ref: '#/components/parameters/x-webhook-id'
        - $ref: '#/components/parameters/x-timestamp'
        - $ref: '#/components/parameters/x-signature'
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Webhook'
                - type: object
                  properties:
                    data:
                      type: object
                      title: AccountBalance
                      properties:
                        balance:
                          $ref: '#/components/schemas/total'
      responses:
        '200':
          $ref: '#/components/responses/200'
components:
  securitySchemes:
    apikey_auth:
      description: |
        Authenticate all requests by passing API key in `X-API-Key` header.
      type: apiKey
      in: header
      name: X-API-Key
  responses:
    '200':
      description: Success response
      content:
        application/json:
          schema:
            type: object
            title: SuccessfulResponse
            required:
              - result
            properties:
              result:
                description: Success response
                type: string
                enum:
                  - success
                example: success
    '400':
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error400'
    '401':
      description: Unauthorized to access this resource
      content:
        application/json:
          schema:
            type: object
            title: error401
            required:
              - errorMessage
              - errorName
            properties:
              errorName:
                description: Error name
                type: string
                enum:
                  - UnauthorizedException
                example: UnauthorizedException
              errorMessage:
                description: Error message
                type: string
                example: Unauthorized to access this resource
    '403':
      description: User account on hold status
      content:
        application/json:
          schema:
            type: object
            title: error403
            required:
              - errorMessage
              - errorName
            properties:
              errorName:
                description: Error name
                type: string
                enum:
                  - AccountOnHoldException
                example: AccountOnHoldException
              errorMessage:
                description: Error message
                type: string
                example: Account on hold
    '404':
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error404'
    '409':
      description: Resource in a bad state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error409'
    '500':
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: object
            title: Unexpected Error
            x-model: ApiUnexpectedError
            required:
              - errorMessage
              - errorName
            properties:
              errorMessage:
                type: string
                example: Unexpected Error Occurred
                description: A generic error message indicating an unexpected problem was encountered.
              errorName:
                type: string
                enum:
                  - UnexpectedErrorException
                example: UnexpectedErrorException
    '503':
      description: Service unavailable
      content:
        application/json:
          schema:
            type: object
            title: error503
            required:
              - errorMessage
              - errorName
            properties:
              errorMessage:
                type: string
                example: Service Unavailable
                description: Service Unavailable
              errorName:
                type: string
                enum:
                  - ServiceUnavailableException
                example: ServiceUnavailableException
    409CustomerExists:
      description: Customer already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error409CustomerExists'
    404CustomerNotFound:
      description: Customer not found exception
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error404CustomerNotFound'
    429TooManyRequests:
      description: Too Many Requests
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error429TooManyRequests'
    CustomersList:
      description: Customers list
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomersList'
    CustomersActivationHistory:
      description: Customers activation history
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomersActivationHistory'
    CustomersTransactions:
      description: Customers transactions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomersTransactions'
    409CustomerTransactionExists:
      description: Customer transaction already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error409CustomerTransactionExists'
    Price:
      description: Price and Availability for a Service in a Country
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Price'
    PricesByCountry:
      description: Price list organized by country
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PricesByCountry'
    PricesByService:
      description: Price list organized by service
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PricesByService'
    CustomerNewActivation:
      description: New activation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerActivation'
          examples:
            smsRequested:
              summary: Waiting for first SMS
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552671'
                country_id: us
                service_id: netflix
                sms_status: smsRequested
                activation_status: active
                billing_status: reserved
                report_status: null
                sms_code: null
                sms_text: null
                expire_at: 1729088539
                updated_at: 1729087939
                created_at: 1729087339
                is_retriable: false
                cancelable_after: null
                formatted: +1 415 555-2671
    402PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/error402PaymentRequiredInsufficientUserBalance'
              - $ref: '#/components/schemas/error402PaymentRequiredInsufficientCustomerBalance'
    409MaxPriceExeeded:
      description: Max price exceeded
      content:
        application/json:
          schema:
            type: object
            title: MaxPriceExceeded
            required:
              - errorMessage
              - errorName
              - suggestedPrice
              - orderId
            properties:
              errorMessage:
                type: string
                example: Max price exceeded
                description: Current price is greater than passed in `max_price` parameter.
              errorName:
                type: string
                enum:
                  - MaxPriceExceededException
                example: MaxPriceExceededException
              suggestedPrice:
                type: integer
                multipleOf: 1
                minimum: 1
                example: 130
                description: New suggested price for activation in USD cents.
              orderId:
                type: string
                example: 682b17b958bf608ceae5ec3c
                description: |
                  A unique identifier for continuing this activation attempt with a higher `max_price`.

                  When you receive this error, it means no numbers were available within your specified price limit — but we found options just above it. To try again without losing your selection context, send a new activation request using this `order_id` along with a higher `max_price` (e.g., the provided `suggestedPrice` or more).

                  Using `order_id` ensures the system can continue processing your original activation request rather than starting a new one from scratch. This improves efficiency and success rate.
    CustomerActivation:
      description: Activation state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerActivation'
          examples:
            smsRequested:
              summary: Waiting for first SMS
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552671'
                country_id: us
                service_id: netflix
                sms_status: smsRequested
                activation_status: active
                billing_status: reserved
                report_status: null
                sms_code: null
                sms_text: null
                expire_at: 1729088539
                updated_at: 1729087939
                created_at: 1729087339
                is_retriable: false
                cancelable_after: null
                formatted: +1 415 555-2671
            firstSmsReceived:
              summary: First SMS received
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552672'
                country_id: us
                service_id: netflix
                sms_status: smsReceived
                activation_status: active
                billing_status: billed
                report_status: null
                sms_code: '748392'
                sms_text: Your verification code is 748392
                expire_at: 1729096828
                updated_at: 1729096128
                created_at: 1729095628
                is_retriable: true
                cancelable_after: 1729095748
                formatted: +1 415 555-2672
            retryRequested:
              summary: Waiting for retry SMS
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552673'
                country_id: us
                service_id: netflix
                sms_status: retryRequested
                activation_status: active
                billing_status: billed
                report_status: null
                sms_code: '749283'
                sms_text: Your verification code is 749283
                expire_at: 1729090045
                updated_at: 1729089645
                created_at: 1729089045
                is_retriable: true
                cancelable_after: 1729089045
                formatted: +1 415 555-2671
            retryReceived:
              summary: Retry SMS received
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552674'
                country_id: us
                service_id: netflix
                sms_status: retryReceived
                activation_status: active
                billing_status: billed
                report_status: null
                sms_code: '964572'
                sms_text: Your verification code is 964572
                expire_at: 1729091245
                updated_at: 1729090845
                created_at: 1729090445
                is_retriable: true
                cancelable_after: 1729090445
                formatted: +1 415 555-2674
            activationCanceled:
              summary: Activation canceled
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552675'
                country_id: us
                service_id: netflix
                sms_status: smsRequested
                activation_status: canceled
                billing_status: released
                report_status: null
                sms_code: null
                sms_text: null
                expire_at: 1729072828
                updated_at: 1729071693
                created_at: 1729071628
                is_retriable: false
                cancelable_after: 1729071688
                formatted: +1 415 555-2675
            activationRefunded:
              summary: Activation refunded
              value:
                activation_id: 64a1c0e8d2a1f9b7e45d3b8e
                customer_id: yHZpQ8lf89aLt8uR6hNyJH7gk0y5
                customer_price: 80
                price: 20
                phone: '14155552676'
                country_id: us
                service_id: netflix
                sms_status: smsReceived
                activation_status: expired
                billing_status: refunded
                report_status: approved
                sms_code: '964572'
                sms_text: Your verification code is 964572
                expire_at: 1729078028
                updated_at: 1729066629
                created_at: 1729066628
                is_retriable: false
                cancelable_after: null
                formatted: +1 415 555-2671
    CustomerInformation:
      description: Customer's balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerInformation'
    CustomerBalance:
      description: Customer's balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerBalance'
    CustomerTransactions:
      description: Customer transactions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerTransactions'
    Countries:
      description: List of countries
      headers:
        X-ETag:
          description: X-ETag header for caching
          required: false
          schema:
            type: string
            example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465
        Last-Modified:
          description: Last-Modified header indicating the last update as Unix Timestamp in seconds
          required: false
          schema:
            type: string
            example: '1730124479'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Countries'
    304NotModified:
      description: Not modified (Empty body)
    Services:
      description: Services information
      headers:
        X-ETag:
          description: X-ETag header for caching
          required: false
          schema:
            type: string
            example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465
        Last-Modified:
          description: Last-Modified header indicating the last update as Unix Timestamp in seconds
          required: false
          schema:
            type: string
            example: '1730124479'
      content:
        application/json:
          schema:
            title: Array of services.
            type: array
            items:
              title: Service
              type: object
              properties:
                service_id:
                  type: string
                  example: 7eleven
                  description: Service ID, as returned by `getServices` operation.
                  format: ^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-_]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-_]*[A-Za-z0-9])$
                  minLength: 1
                  maxLength: 30
                name:
                  type: string
                  example: 7-Eleven
                  description: Name of service
                alt_name:
                  type: string
                  example: 7-Eleven
                  description: Alternative name of service
                has_description:
                  type: boolean
                  example: true
                  description: Whether the service has a description
                has_warning:
                  type: boolean
                  example: false
                  description: Whether the service has a warning
                prohibited:
                  type: boolean
                  example: false
                  description: Whether the service is prohibited for order
    ReportReasons:
      description: List of report reasons with evidence requirements
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReportReasons'
    CustomerReport:
      description: Report
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerReport'
    200Report:
      description: New Report response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/200Report'
          examples:
            reportAccepted:
              $ref: '#/components/examples/reportAccepted'
            reportDeclined:
              $ref: '#/components/examples/reportDeclined'
    CustomerReports:
      description: Reports
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerReports'
    CurrencyRate:
      description: Currency rate
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CurrencyRate'
  schemas:
    error400:
      type: object
      title: error400
      x-model: ApiError400
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Invalid request params
          description: Error message
        errorName:
          type: string
          enum:
            - InvalidRequestParamsException
          example: InvalidRequestParamsException
    error409CustomerExists:
      type: object
      title: CustomerExistsException
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - CustomerExistsException
          example: CustomerExistsException
        errorMessage:
          description: Error message
          type: string
          example: Customer already exists
    error429TooManyRequests:
      type: object
      title: error429TooManyRequests
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Too Many Requests
          description: Too Many Requests
        errorName:
          type: string
          enum:
            - TooManyRequestsException
          example: TooManyRequestsException
    error404CustomerNotFound:
      type: object
      title: CustomerNotFoundException
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - CustomerNotFoundException
          example: CustomerNotFoundException
        errorMessage:
          description: Error message
          type: string
          example: Customer not found
    error409:
      type: object
      title: ResourceBadStateException
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Resource is in a bad state
          description: Resource is in a bad state
        errorName:
          type: string
          enum:
            - ResourceBadStateException
          example: ResourceBadStateException
    Customer:
      title: Customer
      type: object
      properties:
        customer_id:
          type: string
          example: xDWxt7dd6efro3yWL4qfuEWjvAz1
          description: ID of customer. Must be unique.
          format: ^[a-zA-Z0-9]+$
          minLength: 1
          maxLength: 80
        balance:
          type: integer
          description: Customer balance in USD cents. Can be negative.
          example: 90
          minimum: -100000
          maximum: 100000
        status:
          type: string
          example: active
          description: Customer status. Can be `disabled`, `active`, `paused`, `markedForDeletion`.
          enum:
            - disabled
            - active
            - paused
            - markedForDeletion
        created_at:
          type: integer
          example: 1632400000
          description: Unix timestamp in seconds. Creation time of customer.
        updated_at:
          type: integer
          example: 1632400000
          description: Unix timestamp in seconds. Last update time of customer.
    CustomersList:
      type: object
      title: CustomersList
      properties:
        customers:
          type: array
          description: An array of customers.
          items:
            $ref: '#/components/schemas/Customer'
        page:
          type: integer
          description: The current page number being viewed.
          example: 1
        limit:
          type: integer
          description: The number of items displayed per page.
          example: 10
        pages:
          type: integer
          description: The total number of available pages, based on the current limit.
          example: 5
        total:
          type: integer
          description: The total number of activation records found.
          example: 48
    CustomerActivation:
      title: Activation
      type: object
      properties:
        activation_id:
          type: string
          example: 63f4d0dab040a865d80da08a
          description: A unique identifier for the activation. This ID is used to reference and manage specific activations throughout their lifecycle.
        customer_id:
          type: string
          example: xDWxt7dd6efro3yWL4qfuEWjvAz1
          description: Customer ID.
        customer_price:
          type: integer
          example: 100
          description: Price of the activation for customer in USD cents. This amount deducted from the customer balance, if sms received.
          minimum: 0
          maximum: 10000
        phone:
          type: string
          example: '447975777666'
          description: The phone number associated with the activation, formatted in E.164 without the leading plus sign (e.g., 447975777666 for a UK number). This is the number to which SMS messages are sent.
        country_id:
          type: string
          example: uk
          description: Country ID, as returned by the `getCountries` operation. A country identifier (e.g., `uk` for the United Kingdom) representing the country in which the phone number is registered.
          pattern: ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
          minLength: 2
          maxLength: 9
        service_id:
          type: string
          example: 7eleven
          description: Service ID, as returned by `getServices` operation. The identifier of the service associated with the activation. This could represent different services, applications, platforms, etc. (e.g., `7eleven`).
        sms_status:
          type: string
          description: Represents the current state of the SMS interaction within the activation process.
          oneOf:
            - const: smsRequested
              description: The initial state when an SMS is requested but not yet received.
            - const: smsReceived
              description: The first SMS has been received.
            - const: retryRequested
              description: The user has requested another SMS.
            - const: retryReceived
              description: The user has received another SMS.
          example: smsRequested
        activation_status:
          type: string
          description: Represents the overall state of the activation.
          oneOf:
            - const: active
              description: The activation is currently active and can proceed.
            - const: finalized
              description: The user has confirmed the activation, and no further changes are possible.
            - const: expired
              description: The activation has expired based on the `expire_at` timestamp.
            - const: canceled
              description: The activation was canceled before any SMS was received.
          example: expired
        billing_status:
          type: string
          description: Indicates the billing state of the activation.
          oneOf:
            - const: reserved
              description: Funds are reserved from the user's available balance when the activation is created.
            - const: released
              description: No SMS was received, and reserved funds were returned to the available balance.
            - const: billed
              description: An SMS was received, and the reserved funds have been charged.
            - const: refunded
              description: A refund was issued after a user report, and the amount was returned to the available balance.
          example: billed
        report_status:
          description: Represents the status of report filed by the user regarding the activation (e.g., reporting a wrong SMS).
          oneOf:
            - type: string
              const: inReview
              description: The report is currently in review.
            - type: string
              const: declined
              description: The report was reviewed, and no refund was granted.
            - type: string
              const: approved
              description: The report was reviewed, and a refund was issued.
            - type: 'null'
              description: No report has been made.
          example: null
        sms_code:
          type:
            - string
            - 'null'
          example: '6363'
          description: The code received in the SMS message. This field is `null` if no SMS code was received.
        sms_text:
          type:
            - string
            - 'null'
          example: Your code is 6363
          description: The text content of the SMS message received. This field is `null` if no SMS message was received.
        price:
          type: integer
          minimum: 1
          example: 90
          description: The cost of the activation in USD cents. This amount is reserved from the user's available balance when the activation is created.
        expire_at:
          type: integer
          example: 1679061628
          description: A unix timestamp in seconds indicating when the activation expires. If the current time is past this timestamp, the activation should be considered expired independently of the `activation_status` field.
        updated_at:
          type: integer
          example: 1679061629
          description: A unix timestamp in seconds indicating the last time the activation was updated.
        created_at:
          type: integer
          example: 1679061001
          description: A unix timestamp in seconds indicating when the activation was created.
        is_retriable:
          type: boolean
          example: true
          description: Indicates whether the user can request another SMS. If `true`, the user is allowed to request a retry SMS.
        cancelable_after:
          type:
            - integer
            - 'null'
          example: null
          description: A unix timestamp in seconds indicating the time after which the activation may be canceled. If `null`, cancellation is not supported for this activation.
        formatted:
          type: string
          example: +44 7975 777666
          description: The phone number formatted for display purposes.
    CustomersActivationHistory:
      title: CustomersActivationHistory
      type: object
      properties:
        activations:
          type: array
          description: An array of activations.
          items:
            $ref: '#/components/schemas/CustomerActivation'
        page:
          type: integer
          description: The current page number being viewed.
          example: 1
        limit:
          type: integer
          description: The number of items displayed per page.
          example: 10
        pages:
          type: integer
          description: The total number of available pages, based on the current limit.
          example: 5
        total:
          type: integer
          description: The total number of activation records found.
          example: 48
    CustomerTransaction:
      title: Transaction
      type: object
      properties:
        customer_id:
          type: string
          example: xDWxt7dd6efro3yWL4qfuEWjvAz1
          description: ID of customer. Must be unique.
          format: ^[a-zA-Z0-9]+$
          minLength: 1
          maxLength: 80
        transaction_id:
          type: string
          example: 63f4d0dab040a865d80da08a
          description: ID of transaction. Must be unique.
          format: ^[a-zA-Z0-9]+$
          minLength: 1
          maxLength: 80
        gateway:
          type: string
          example: stripe
          description: Payment gateway used for transaction.
          minLength: 1
          maxLength: 50
        amount:
          type: integer
          description: Transaction amount in USD cents. Negative amount means customer was charged.
          example: 190
          minimum: -100000
          maximum: 100000
        created_at:
          type: integer
          example: 1632400000
          description: Unix timestamp in seconds. Creation time of transaction.
    CustomersTransactions:
      title: CustomersTransactions
      type: object
      properties:
        transactions:
          type: array
          description: An array of customers transactions.
          items:
            $ref: '#/components/schemas/CustomerTransaction'
        page:
          type: integer
          description: The current page number being viewed.
          example: 1
        limit:
          type: integer
          description: The number of items displayed per page.
          example: 10
        pages:
          type: integer
          description: The total number of available pages, based on the current limit.
          example: 5
        total:
          type: integer
          description: The total number of activation records found.
          example: 48
    error409CustomerTransactionExists:
      type: object
      title: CustomerTransactionExistsException
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - CustomerTransactionExistsException
          example: CustomerTransactionExistsException
        errorMessage:
          description: Error message
          type: string
          example: Customer transaction already exists
    Price:
      type: object
      properties:
        price:
          type: object
          properties:
            min:
              type: integer
              multipleOf: 1
              minimum: 1
              example: 210
              description: Minimum price in USD cents
            max:
              type: integer
              multipleOf: 1
              minimum: 1
              example: 510
              description: Maximum price in USD cents
            suggested:
              type: integer
              multipleOf: 1
              minimum: 1
              example: 310
              description: Suggested price in USD cents
        quality:
          type: object
          properties:
            avg:
              type: number
              minimum: 0
              maximum: 1
              example: 0.3
              description: Average quality of the service, from 0 to 1
        count:
          type: integer
          minimum: 0
          example: 143
          description: The number of available numbers for sale.
    error404:
      type: object
      title: error404
      x-model: ApiError404
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - ResourceNotFoundException
          example: ResourceNotFoundException
        errorMessage:
          description: Error message
          type: string
          example: Resource not found
    PricesByCountry:
      title: Prices organized by country
      type: array
      items:
        title: Array of countries with prices
        type: object
        properties:
          country_id:
            type: string
            example: uk
            description: Country ID, as returned by the `getCountries` operation.
            pattern: ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
            minLength: 2
            maxLength: 9
          services:
            type: array
            items:
              title: Array of services with prices
              type: object
              properties:
                service_id:
                  type: string
                  example: 7eleven
                  description: Service ID as returned by `getServices` operation
                  format: ^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-_]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-_]*[A-Za-z0-9])$
                  minLength: 1
                  maxLength: 30
                price:
                  type: object
                  properties:
                    min:
                      type: integer
                      multipleOf: 1
                      minimum: 1
                      example: 210
                      description: Minimum price in USD cents
                    max:
                      type: integer
                      multipleOf: 1
                      minimum: 1
                      example: 510
                      description: Maximum price in USD cents
                    suggested:
                      type: integer
                      multipleOf: 1
                      minimum: 1
                      example: 310
                      description: Suggested price in USD cents
                quality:
                  type: object
                  properties:
                    avg:
                      type: number
                      minimum: 0
                      maximum: 1
                      example: 0.3
                      description: Average quality of the service, from 0 to 1
                count:
                  type: integer
                  minimum: 0
                  example: 143
                  description: The number of available numbers for sale
    PricesByService:
      title: Prices organized by service
      type: array
      items:
        title: Array of services with prices
        type: object
        properties:
          service_id:
            type: string
            example: 7eleven
            description: Service ID as returned by `getServices` operation
            format: ^(([a-zA-Z]|[a-zA-Z][a-zA-Z0-9\-_]*[a-zA-Z0-9])\.)*([A-Za-z]|[A-Za-z][A-Za-z0-9\-_]*[A-Za-z0-9])$
            minLength: 1
            maxLength: 30
          countries:
            type: array
            items:
              title: Array of countries with prices
              type: object
              properties:
                country_id:
                  type: string
                  example: uk
                  description: Country ID, as returned by the `getCountries` operation.
                  pattern: ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
                  minLength: 2
                  maxLength: 9
                price:
                  type: object
                  properties:
                    min:
                      type: integer
                      multipleOf: 1
                      minimum: 1
                      example: 210
                      description: Minimum price in USD cents
                    max:
                      type: integer
                      multipleOf: 1
                      minimum: 1
                      example: 510
                      description: Maximum price in USD cents
                    suggested:
                      type: integer
                      multipleOf: 1
                      minimum: 1
                      example: 310
                      description: Suggested price in USD cents
                quality:
                  type: object
                  properties:
                    avg:
                      type: number
                      minimum: 0
                      maximum: 1
                      example: 0.3
                      description: Average quality of the service, from 0 to 1
                count:
                  type: integer
                  minimum: 0
                  example: 143
                  description: The number of available numbers for sale
    NewActivationFixedCustomerMarkup:
      title: Fixed with Customer Markup
      required:
        - service_id
        - country_id
        - customer_markup
      properties:
        service_id:
          type: string
          example: 7eleven
          description: ID of Service being verified. Can be retrieved using `GET sms/services`
          minLength: 1
          maxLength: 30
        country_id:
          type: string
          example: us
          description: ID of phone number Country. Can be retrieved using `GET /countries`
          minLength: 2
          maxLength: 9
        max_price:
          type: integer
          example: 90
          description: |
            Maximum price in USD cents you (developer) are willing to pay for activation.
            This safeguards against price changes.
            If the actual price exceeds this limit, a 409 error is returned along with the new suggested price.
            Defaults to the current suggested price if not provided.
          minimum: 1
          maximum: 10000
        customer_markup:
          type: integer
          description: |
            This parameter is used to calculate price of activation that customer will be billed.
            The markup percentage is applied to the `max_price` to calculate the customer cost.
          minimum: 0
          maximum: 10000
        customer_billing_type:
          type: string
          example: fixed
          description: Billing type for the customer. Must be `fixed`.
          const: fixed
        order_id:
          type: string
          description: |
            Optional continuation token for an activation attempt that failed due to pricing limits.

            When you receive a `409 MaxPriceExceededException`, it means no phone numbers were available within your specified `max_price`, but alternatives are available just above your limit.

            In that case, the response includes a `suggestedPrice` and an `order_id`. To retry the same activation attempt at the suggested price (or higher), send a new request using the same `order_id` and a higher `max_price`.

            This ensures the system can continue the previous attempt with the same selection context, potentially increasing the success rate and reducing redundant attempts.

            **Recommended Usage:**
            - Store the `order_id` when handling a `409 MaxPriceExceededException`.
            - Use it to continue the activation attempt once you've decided to raise the `max_price`.
          example: 682b17b958bf608ceae5ec3c
        quality_factor:
          type: number
          example: 10
          description: |
            Quality factor for the number. The quality factor is a number between 0 and 100. The default value is 50. 0 - means prefer price over quality. 100 - means prefer quality over price.
          minimum: 0
          maximum: 100
    NewActivationFixedCustomerPrice:
      title: Fixed with Customer Price
      required:
        - service_id
        - country_id
        - customer_price
      properties:
        service_id:
          type: string
          example: 7eleven
          description: ID of Service being verified. Can be retrieved using `GET sms/services`
          minLength: 1
          maxLength: 30
        country_id:
          type: string
          example: us
          description: ID of phone number Country. Can be retrieved using `GET /countries`
          minLength: 2
          maxLength: 9
        max_price:
          type: integer
          example: 90
          description: |
            Maximum price in USD cents you (developer) are willing to pay for activation.
            This safeguards against price changes.
            If the actual price exceeds this limit, a 409 error is returned along with the new suggested price.
            Defaults to the current suggested price if not provided.
          minimum: 1
          maximum: 10000
        customer_price:
          type: integer
          example: 100
          description: |
            Price of the activation for customer in USD cents.
            This amount will be deducted from the customer balance, if sms received.
          minimum: 0
          maximum: 10000
        customer_billing_type:
          type: string
          example: fixed
          description: Billing type for the customer. Must be `fixed`.
          const: fixed
        order_id:
          type: string
          description: |
            Optional continuation token for an activation attempt that failed due to pricing limits.

            When you receive a `409 MaxPriceExceededException`, it means no phone numbers were available within your specified `max_price`, but alternatives are available just above your limit.

            In that case, the response includes a `suggestedPrice` and an `order_id`. To retry the same activation attempt at the suggested price (or higher), send a new request using the same `order_id` and a higher `max_price`.

            This ensures the system can continue the previous attempt with the same selection context, potentially increasing the success rate and reducing redundant attempts.

            **Recommended Usage:**
            - Store the `order_id` when handling a `409 MaxPriceExceededException`.
            - Use it to continue the activation attempt once you've decided to raise the `max_price`.
          example: 682b17b958bf608ceae5ec3c
        quality_factor:
          type: number
          example: 10
          description: |
            Quality factor for the number. The quality factor is a number between 0 and 100. The default value is 50. 0 - means prefer price over quality. 100 - means prefer quality over price.
          minimum: 0
          maximum: 100
    NewActivationDynamic:
      title: Dynamic with Customer Markup
      required:
        - service_id
        - country_id
        - customer_markup
      properties:
        service_id:
          type: string
          example: 7eleven
          description: ID of Service being verified. Can be retrieved using `GET sms/services`
          minLength: 1
          maxLength: 30
        country_id:
          type: string
          example: us
          description: ID of phone number Country. Can be retrieved using `GET /countries`
          minLength: 2
          maxLength: 9
        max_price:
          type: integer
          example: 90
          description: |
            Maximum price in USD cents you (developer) are willing to pay for activation.
            This safeguards against price changes.
            If the actual price exceeds this limit, a 409 error is returned along with the new suggested price.
            Defaults to the current suggested price if not provided.
          minimum: 1
          maximum: 10000
        customer_markup:
          type: integer
          description: |
            This parameter is used to calculate price of activation that customer will be billed.
            The markup percentage is applied to actual `activation cost`. Actual `activation cost` is known only after phone number is issued and always less than or equal to `max_price`.
          minimum: 0
          maximum: 10000
        customer_billing_type:
          type: string
          example: dynamic
          description: |
            The billing type for the customer must be `dynamic`.
            The price is adjusted based on the activation price, with the `max_price` price reserved until the activation price is known. `customer_price` must not be provided when this type is selected.
            `Amount = activation_price * ( 1 + markup / 100)`
          const: dynamic
        order_id:
          type: string
          description: |
            Optional continuation token for an activation attempt that failed due to pricing limits.

            When you receive a `409 MaxPriceExceededException`, it means no phone numbers were available within your specified `max_price`, but alternatives are available just above your limit.

            In that case, the response includes a `suggestedPrice` and an `order_id`. To retry the same activation attempt at the suggested price (or higher), send a new request using the same `order_id` and a higher `max_price`.

            This ensures the system can continue the previous attempt with the same selection context, potentially increasing the success rate and reducing redundant attempts.

            **Recommended Usage:**
            - Store the `order_id` when handling a `409 MaxPriceExceededException`.
            - Use it to continue the activation attempt once you've decided to raise the `max_price`.
          example: 682b17b958bf608ceae5ec3c
        quality_factor:
          type: number
          example: 10
          description: |
            Quality factor for the number. The quality factor is a number between 0 and 100. The default value is 50. 0 - means prefer price over quality. 100 - means prefer quality over price.
          minimum: 0
          maximum: 100
    error402PaymentRequiredInsufficientUserBalance:
      type: object
      title: PaymentRequiredExceptionUser
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - PaymentRequiredException
          example: PaymentRequiredException
        errorMessage:
          type: string
          enum:
            - Insufficient user balance
          example: Insufficient user balance
          description: Developer's account balance has not enough funds to complete the operation.
    error402PaymentRequiredInsufficientCustomerBalance:
      type: object
      title: PaymentRequiredExceptionCustomer
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - PaymentRequiredException
          example: PaymentRequiredException
        errorMessage:
          description: Error message
          type: string
          enum:
            - Insufficient customer balance
          example: Insufficient customer balance
    error404NoNumbers:
      type: object
      title: NoNumbersAvailableException
      required:
        - errorMessage
        - errorName
      properties:
        errorName:
          description: Error name
          type: string
          enum:
            - NoNumbersAvailableException
          example: NoNumbersAvailableException
        errorMessage:
          description: Error message
          type: string
          example: No numbers available
    error429LowSuccessRate:
      type: object
      title: error429LowSuccessRate
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Low Success Rate
          description: Low Success Rate
        errorName:
          type: string
          enum:
            - LowSuccessRateException
          example: LowSuccessRateException
    error429TooManyActivations:
      type: object
      title: error429TooManyActivations
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Too Many Activations
          description: Too Many Activations
        errorName:
          type: string
          enum:
            - TooManyActivationsException
          example: TooManyActivationsException
    CustomerActiveActivationsIds:
      title: Active activation IDs array
      type: array
      items:
        type: string
        description: Activation ID.
        example: 63f4d0dab040a865d80da08a
      example:
        - 64a1c0e8d2a1f9b7e45d3b8e
        - 63f4d0dab040a865d80da08d
        - 63f4d0dab040a865d80da08a
    CustomerActiveActivationsWithData:
      title: An array of active activations
      type: array
      items:
        $ref: '#/components/schemas/CustomerActivation'
      example:
        - activation_id: 64a1c0e8d2a1f9b7e45d3b8e
          customer_id: xDWxt7dd6efro3yWL4qfuEWjvAz1
          customer_price: 80
          price: 20
          phone: '14155552671'
          country_id: us
          service_id: netflix
          sms_status: retryReceived
          activation_status: active
          billing_status: billed
          report_status: null
          sms_code: '964572'
          sms_text: Your verification code is 964572
          expire_at: 1729091245
          updated_at: 1729090845
          created_at: 1729090445
          is_retriable: true
          cancelable_after: 1729090445
          formatted: +1 415 555-2671
        - activation_id: 63f4d0dab040a865d80da08d
          customer_id: xDWxt7dd6efro3yWL4qfuEWjvAz1
          customer_price: 80
          price: 20
          phone: '14155552672'
          country_id: us
          service_id: netflix
          sms_status: smsReceived
          activation_status: active
          billing_status: billed
          report_status: null
          sms_code: '964572'
          sms_text: Your verification code is 964572
          expire_at: 1729091245
          updated_at: 1729090845
          created_at: 1729090445
          is_retriable: false
          cancelable_after: 1729090445
          formatted: +1 415 555-2672
        - activation_id: 63f4d0dab040a865d80da08a
          customer_id: xDWxt7dd6efro3yWL4qfuEWjvAz1
          customer_price: 80
          price: 20
          phone: '14155552673'
          country_id: us
          service_id: netflix
          sms_status: smsRequested
          activation_status: active
          billing_status: reserved
          report_status: null
          sms_code: '964572'
          sms_text: Your verification code is 964572
          expire_at: 1729091245
          updated_at: 1729090845
          created_at: 1729090445
          is_retriable: false
          cancelable_after: 1729090445
          formatted: +1 415 555-2673
    error409EarlyCancelDenied:
      type: object
      title: EarlyCancelDeniedException
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Cannot cancel the number immediately after activation.
          description: Cannot cancel the number immediately after activation.
        errorName:
          type: string
          enum:
            - EarlyCancelDeniedException
          example: EarlyCancelDeniedException
    CustomerInformation:
      title: CustomerInformation
      type: object
      properties:
        accountOnHold:
          type: boolean
          example: false
          description: Indicates if the account is on hold.
    CustomerBalance:
      title: CustomerBalance
      type: object
      properties:
        total:
          type: integer
          example: 2301
          description: Available balance in USD cents. Can be negative.
        reserved:
          type: integer
          minimum: 0
          example: 210
          description: Reserved balance for uncompleted activations in USD cents
    CustomerTransactions:
      title: CustomerTransactions
      type: object
      properties:
        transactions:
          type: array
          description: An array of transactions.
          items:
            $ref: '#/components/schemas/CustomerTransaction'
        page:
          type: integer
          description: The current page number being viewed.
          example: 1
        limit:
          type: integer
          description: The number of items displayed per page.
          example: 10
        pages:
          type: integer
          description: The total number of available pages, based on the current limit.
          example: 5
        total:
          type: integer
          description: The total number of activation records found.
          example: 48
    Countries:
      title: Array of Countries
      type: array
      items:
        title: Country
        type: object
        properties:
          country_id:
            type: string
            example: uk
            description: Country ID, as returned by the `getCountries` operation.
            pattern: ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
            minLength: 2
            maxLength: 9
          name:
            type: string
            example: United Kingdom
            description: The name of the country.
          alt_name:
            type: string
            example: France|frankrijk|frança|франция|fr
            description: An alternative names for the country.
          codes:
            type: array
            items:
              type: string
              example: '1658'
            description: |
              An array of country phone codes.
            example:
              - '1658'
              - '1876'
    ReportReasons:
      type: array
      title: Array of Report Reasons
      items:
        type: object
        properties:
          reason_id:
            type: integer
            description: Report reason Id
            minimum: 1
          reason_name:
            type: string
            description: Report reason name
            example: Wrong SMS received
          evidence_required:
            type: boolean
            description: Indicates if evidence is required for the report
      example:
        - reason_id: 1
          reason_name: SMS is not coming
          evidence_required: true
        - reason_id: 2
          reason_name: Wrong SMS received
          evidence_required: false
    error409ReportCreationDeadline:
      type: object
      title: ReportCreationDeadlinePassed
      required:
        - errorMessage
        - errorName
      properties:
        errorMessage:
          type: string
          example: Report creation deadline has passed (60 minutes limit after order creation).
          description: Report creation deadline has passed (60 minutes limit after order creation).
        errorName:
          type: string
          enum:
            - ReportCreationDeadlinePassed
          example: ReportCreationDeadlinePassed
    CustomerReport:
      title: Report
      type: object
      properties:
        reason_id:
          type: integer
          minimum: 1
          example: 1
          description: Report reason Id
        reason_name:
          type: string
          example: SMS is not coming
          description: Report reason name
        message:
          type: string
          example: Test message
          description: Report detailed explanation
        evidence_url:
          type: string
          example: https://test-1.nyc3.digitaloceanspaces.com/reports/evidences/66b3163f708df00376fb91c6.png
          description: Report evidence URL
        activation_state_snapshot:
          type: string
          example: '{"activation_status":"active","sms_status":"smsRequested","billing_status":"reserved","sms_code":null,"sms_text":null,"updated_at":1725264364}'
          description: Activation state on report creating moment
        updated_at:
          type: integer
          example: 1679061001
          description: Unix timestamp in seconds of last report state change.
        created_at:
          type: integer
          example: 1679061001
          description: Unix timestamp in seconds of report creation.
        activation:
          $ref: '#/components/schemas/CustomerActivation'
    ActivationReportRequestBody:
      type: object
      title: Activation Report
      required:
        - reason_id
      properties:
        reason_id:
          type: integer
          minimum: 1
          example: 4
          description: ID of reason
        message:
          type: string
          example: Service activation is not possible because 2FA was previously enabled.
          description: Message with details about the report.
          maxLength: 1000
        evidence:
          type: string
          format: binary
          description: |
            File upload for evidence. Acceptable file types: jpg, png, webp, zip, pdf, mp4.
            Maximum file size: 5MB.
    200Report:
      type: object
      title: CreateReportResponse
      properties:
        status:
          description: Create report response status
          type: string
          enum:
            - accepted
            - declined
          example: declined
        decline_id:
          description: |
            The Decline ID is a unique identifier representing the reason for declining a request. 
            If the request status is `accepted`, the Decline ID will be `null`.
          type:
            - integer
            - 'null'
          example: 1
    CustomerReports:
      title: Reports
      type: object
      example:
        reports:
          - reason_id: 1
            reason_name: SMS is not coming
            message: Test message
            evidence_url: https://test-1.nyc3.digitaloceanspaces.com/reports/evidences/66b3163f708df00376fb91c6.png
            activation_state_snapshot: '{"activation_status":"active","sms_status":"smsRequested","billing_status":"reserved","sms_code":null,"sms_text":null,"updated_at":1725264364}'
            updated_at: 1679061001
            created_at: 1679061001
            activation:
              activation_id: 63f4d0dab040a865d80da08a
              customer_id: xDWxt7dd6efro3yWL4qfuEWjvAz1
              customer_price: 100
              phone: '447975777666'
              country_id: uk
              service_id: 7eleven
              sms_status: smsRequested
              activation_status: expired
              billing_status: billed
              report_status: null
              sms_code: '6363'
              sms_text: Your code is 6363
              price: 90
              expire_at: 1679061628
              updated_at: 1679061629
              created_at: 1679061001
              is_retriable: true
              cancelable_after: null
        page: 1
        limit: 10
        pages: 5
        total: 48
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/CustomerReport'
        page:
          type: integer
          description: Selected page
          example: 1
        limit:
          type: integer
          description: Items limit per page
          example: 10
        pages:
          type: integer
          description: Total pages count
          example: 5
        total:
          type: integer
          description: Total records found
          example: 48
    CurrencyRate:
      title: CurrencyRate
      type: object
      properties:
        rate:
          type: number
          example: 1
          description: Exchange rate for the specified currency
    RetailWebhook:
      title: Retail Webhook event
      type: object
      x-model: RetailWebhookEvent
      required:
        - id
        - api_version
        - type
        - data
      properties:
        id:
          type: string
          example: abcd1234
          description: A unique identifier for the webhook event. Used for idempotency.
        api_version:
          type: string
          example: '1.0'
          description: The version of the API that the webhook event is using.
        type:
          type: string
          enum:
            - customer.low_balance
            - account.low_balance
            - customer.updated
            - customer.activation.updated
            - activation_report.updated
            - alternative.activation.updated
          example: customer.low_balance
          description: The type of webhook event.
        data:
          type: object
          description: The payload of the webhook event. The structure of this object varies depending on the event type.
          example:
            activation_id: 63f4d0dab040a865d80da08a
            phone: '447975777666'
            country_id: uk
            service_id: 7eleven
            sms_status: smsRequested
            activation_status: expired
            billing_status: billed
            report_status: null
            sms_code: '6363'
            sms_text: Your code is 6363
            price: 90
            expire_at: 1679061628
            updated_at: 1679061629
            created_at: 1679061001
            is_retriable: true
            cancelable_after: null
    customer_id:
      type: string
      example: xDWxt7dd6efro3yWL4qfuEWjvAz1
      description: Customer ID.
    activation_id:
      type: string
      example: 63f4d0dab040a865d80da08a
      description: A unique identifier for the activation. This ID is used to reference and manage specific activations throughout their lifecycle.
    report_status:
      description: Represents the status of report filed by the user regarding the activation (e.g., reporting a wrong SMS).
      oneOf:
        - type: string
          const: inReview
          description: The report is currently in review.
        - type: string
          const: declined
          description: The report was reviewed, and no refund was granted.
        - type: string
          const: approved
          description: The report was reviewed, and a refund was issued.
        - type: 'null'
          description: No report has been made.
      example: null
    properties-customer_id:
      type: string
      example: xDWxt7dd6efro3yWL4qfuEWjvAz1
      description: ID of customer. Must be unique.
      format: ^[a-zA-Z0-9]+$
      minLength: 1
      maxLength: 80
    balance:
      type: integer
      description: Customer balance in USD cents. Can be negative.
      example: 90
      minimum: -100000
      maximum: 100000
    Webhook:
      title: API Webhook event
      type: object
      required:
        - id
        - api_version
        - type
        - data
      properties:
        id:
          type: string
          example: abcd1234
          description: A unique identifier for the webhook event. Used for idempotency.
        api_version:
          type: string
          example: '1.0'
          description: The version of the API that the webhook event is using.
        type:
          type: string
          enum:
            - account.low_balance
            - activation.updated
            - activation_report.updated
            - alternative.activation.updated
          example: activation.updated
          description: The type of webhook event.
        data:
          type: object
          description: The payload of the webhook event. The structure of this object varies depending on the event type.
          example:
            activation_id: 63f4d0dab040a865d80da08a
            phone: '447975777666'
            country_id: uk
            service_id: 7eleven
            sms_status: smsRequested
            activation_status: expired
            billing_status: billed
            report_status: null
            sms_code: '6363'
            sms_text: Your code is 6363
            price: 90
            expire_at: 1679061628
            updated_at: 1679061629
            created_at: 1679061001
            is_retriable: true
            cancelable_after: null
    total:
      type: integer
      example: 2301
      description: Available balance in USD cents. Balance may be negative.
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 50
        description: Maximum allowed number of requests.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 0
        description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1706864028
        description: Unix timestamp in seconds when the rate limit will reset.
    Retry-After:
      schema:
        type: integer
        example: 3600
        description: Number of seconds to wait before retrying the request.
  parameters:
    customer_id:
      name: customer_id
      in: path
      required: true
      description: ID of customer. Must be unique.
      schema:
        type: string
        example: xDWxt7dd6efro3yWL4qfuEWjvAz1
        pattern: ^[a-zA-Z0-9]+$
        minLength: 1
        maxLength: 80
    activation_id:
      name: activation_id
      in: path
      required: true
      description: Activation id
      schema:
        type: string
        example: 63f4d0dab040a865d80da08a
    page:
      in: query
      name: page
      required: false
      description: Selected page number
      schema:
        type: integer
        example: 2
        description: Selected page number
        default: 1
    limit:
      in: query
      name: limit
      required: false
      description: Items limit per page
      schema:
        type: integer
        example: 10
        description: Items limit per page
        default: 10
        minimum: 1
        maximum: 100
    x-webhook-id:
      name: x-webhook-id
      in: header
      description: The webhook ID
      required: true
      schema:
        type: string
    x-timestamp:
      name: x-timestamp
      in: header
      description: The timestamp of the webhook
      required: true
      schema:
        type: integer
        example: 1632400000
        description: Unix timestamp in seconds.
    x-signature:
      name: x-signature
      in: header
      description: The signature of the webhook
      required: true
      schema:
        type: string
  examples:
    reportAccepted:
      summary: Report accepted
      value:
        status: accepted
        decline_id: null
    reportDeclined:
      summary: Report declined
      value:
        status: declined
        decline_id: 1
