openapi: 3.1.0
info:
  version: 0.0.1
  title: Platfone Alternative 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 Alternative API

    This API is a alternative API for those who has exisiting integration with activation provider and want to switch to Platfone without any code changes. We recommend to use our full fledged API for new integrations as more features and better performance are available.

    ## What is this API for?
    This API will allow you to get temporary mobile number and receive SMS messages to that number. You can use this API to automate SMS verification for your users. Billing applies only to successfully received SMS messages.

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

    **Sandbox environment**

    🏖️ Try sandbox environment at: [https://platfone.com/test](https://platfone.com/test).
    - No balance required. 
    - Use the API and see results in the UI. 
    - Send fake SMS via UI or API to prepare and test your code before going live. 

    Note: API keys and URLs for sandbox and production are different.

    ## API key

    All requests must include an API key as a parameter `api_key`. 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:

    ```
    Production -> https://temp-number-api.com/stubs/handler_api.php
    Sandbox    -> https://temp-number-api.com/test/stubs/handler_api.php
    ```

    ## Action parameter

    All requests must include an `action` query parameter specifying the operation to perform.

    ## Requests

    - Both GET and POST request supported for all endpoints.
servers:
  - url: https://temp-number-api.com/stubs
security:
  - api_key: []
tags:
  - name: User
    description: User account related operations
  - name: Activation
    description: SMS activation related operations
  - name: Catalog
    description: Prices, services, countries related operations
  - 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:
  /handler_api.php?api_key=$api_key&action=getBalance:
    get:
      tags:
        - User
      summary: Get user's balance
      description: Balance inquiry
      operationId: getUserBalance
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getBalance`
      responses:
        '200':
          $ref: '#/components/responses/UsersBalance'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getBalance"
  /handler_api.php?api_key=$api_key&action=getCountries:
    get:
      tags:
        - Catalog
      summary: Get a list of all countries
      description: Get a list of all countries
      operationId: getCountries
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getCountries`
        - name: mode
          in: query
          required: false
          schema:
            type: string
            enum:
              - strict
              - enriched
              - full
            default: strict
          description: |
            mode (optional): Controls which ID namespaces are included in the response.
            - strict (default) - Return only items that exist in the **common registry** of country IDs used across most third-party providers. This mode is 1:1 compatible with the widely adopted, legacy ID set and contains no extras.
            - enriched - Return the **strict** set first, then append any additional items that we support which are **not** present in the common registry. Use this when you want drop-in compatibility plus our extensions.
            - full - Return the complete set of **Platfone native IDs** (our canonical namespace), independent of the common registry. Use this when you do not have any IDs restrictions and want to get full list.
      responses:
        '200':
          $ref: '#/components/responses/Countries'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getCountries"
  /handler_api.php?api_key=$api_key&action=getServicesList:
    get:
      tags:
        - Catalog
      summary: Get a list of all services
      description: Get a list of all services
      operationId: getServicesList
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getServicesList`
        - name: mode
          in: query
          required: false
          schema:
            type: string
            enum:
              - strict
              - enriched
              - full
            default: strict
          description: |
            mode (optional): Controls which ID namespaces are included in the response.
            - strict (default) - Return only items that exist in the **common registry** of service IDs used across most third-party providers. This mode is 1:1 compatible with the widely adopted, legacy ID set and contains no extras.
            - enriched - Return the **strict** set first, then append any additional items that we support which are **not** present in the common registry. Use this when you want drop-in compatibility plus our extensions.
            - full - Return the complete set of **Platfone native IDs** (our canonical namespace), independent of the common registry. Use this when you do not have any IDs restrictions and want to get full list.
      responses:
        '200':
          $ref: '#/components/responses/Services'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getServicesList"
  /handler_api.php?api_key=$api_key&action=getPrices&service=$service&country=$country:
    get:
      tags:
        - Catalog
      summary: Price list
      description: Get current prices
      operationId: getPrices
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getPrices`
        - name: $service
          in: query
          schema:
            type: string
          description: Short name of the service (Optional, by default all services)
        - name: $country
          in: query
          schema:
            type: string
          description: Country code name (Optional, defaults to all countries)
      responses:
        '200':
          $ref: '#/components/responses/Prices'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getPrices&service=$service&country=$country"
  /handler_api.php?api_key=$api_key&action=getNumber&service=$service&country=$country&maxPrice=maxPrice:
    get:
      tags:
        - Activation
      summary: Request a number
      description: |
        Request a phone number to activate a specific service in a given country.    
        Use `max_price` to specify the maximum price you're willing to pay, protecting against price fluctuations.
      operationId: requestNumber
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getNumber`
        - name: $service
          in: query
          required: true
          schema:
            type: string
          description: service for ordering
        - name: $country
          in: query
          required: true
          schema:
            type: string
          description: country for ordering
        - name: $maxPrice
          in: query
          schema:
            type: number
          description: the maximum price for which you are ready to buy a number at Free Price (optional parameter, if it is not specified, the purchase will take place at the regular price)
      responses:
        '200':
          $ref: '#/components/responses/Number'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getNumber&service=$service&country=$country&maxPrice=maxPrice"
  /handler_api.php?api_key=$api_key&action=getNumberV2&service=$service&country=$country&maxPrice=maxPrice:
    get:
      tags:
        - Activation
      summary: Request a number (v2)
      description: |
        Request a phone number to activate a specific service in a given country. Has a more detailed response structure.    
        Use `max_price` to specify the maximum price you're willing to pay, protecting against price fluctuations.
      operationId: requestNumberV2
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getNumberV2`
        - name: $service
          in: query
          required: true
          schema:
            type: string
          description: service for ordering
        - name: $country
          in: query
          required: true
          schema:
            type: string
          description: country for ordering
        - name: $maxPrice
          in: query
          schema:
            type: number
          description: the maximum price for which you are ready to buy a number at Free Price (optional parameter, if it is not specified, the purchase will take place at the regular price)
      responses:
        '200':
          $ref: '#/components/responses/NumberV2'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getNumberV2&service=$service&country=$country&maxPrice=maxPrice"
  /handler_api.php?api_key=$api_key&action=getStatus&id=$id:
    get:
      tags:
        - Activation
      summary: Get activation status
      description: Get activation status.
      operationId: getActivation
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getStatus`
        - name: $id
          in: query
          required: true
          schema:
            type: string
          description: Activation ID
      responses:
        '200':
          $ref: '#/components/responses/Activation'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getStatus&id=$id"
  /handler_api.php?api_key=$api_key&action=getStatusV2&id=$id:
    get:
      tags:
        - Activation
      summary: Get activation status (v2)
      description: Get activation status (version 2). Returns both sms code and text.
      operationId: getActivationV2
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getStatusV2`
        - name: $id
          in: query
          required: true
          schema:
            type: string
          description: Activation ID
      responses:
        '200':
          $ref: '#/components/responses/ActivationV2'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getStatusV2&id=$id"
  /handler_api.php?api_key=$api_key&action=setStatus&status=$status&id=$id:
    get:
      tags:
        - Activation
      summary: Change activation status
      description: Change activation status
      operationId: changeActivationStatus
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `setStatus`
        - name: $id
          in: query
          required: true
          schema:
            type: string
          description: Activation ID
        - name: $status
          in: query
          required: true
          schema:
            type: integer
            enum:
              - 1
              - 3
              - 6
              - 8
          description: |
            activation status  
            `1` inform about the readiness of the number (SMS sent to the number)  
            `3` request another code (free)  
            `6` complete activation (if there was a status 'code received' - marks it successfully and completes, if there was a 'preparation' - deletes and marks an error, if there was a status 'awaiting retry' - transfers activation to SMS pending)  
            `8` inform that the number has been used and cancel the activation
      responses:
        '200':
          $ref: '#/components/responses/ChangeStatus'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=setStatus&status=$status&id=$id"
  /handler_api.php?api_key=$api_key&action=getHistory&start=$start&end=$end:
    get:
      tags:
        - Activation
      summary: Get activation history
      description: Get activation history
      operationId: getActivationsHistory
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getHistory`
        - name: $start
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Timestamp in Unix Timestamp format (optional) - from which date to take activations
        - name: $end
          in: query
          schema:
            type: integer
            format: int64
            minimum: 1
          description: Timestamp in Unix Timestamp format (optional) - by which date to take activations
      responses:
        '200':
          $ref: '#/components/responses/ActivationsHistory'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getHistory&start=$start&end=$end"
  /handler_api.php?api_key=$api_key&action=getFullSms&id=$id:
    get:
      tags:
        - Activation
      summary: Get full sms text for the number
      description: Get full sms text for the number
      operationId: getFullSms
      parameters:
        - name: $api_key
          in: query
          required: true
          schema:
            type: string
          description: API key
        - name: action
          in: query
          required: true
          schema:
            type: string
          description: Action to perform, set to `getFullSms`
        - name: $id
          in: query
          required: true
          schema:
            type: string
          description: Activation ID
      responses:
        '200':
          $ref: '#/components/responses/FullSms'
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getFullSms&id=$id"
webhooks:
  activationUpdated:
    post:
      tags:
        - Webhooks 📡
      summary: Activation updated webhook
      description: |
        Issued when an activation recieves sms.
      operationId: alternativeActivationUpdatedWebhook
      security: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: ActivationUpdated
              properties:
                activationId:
                  type: string
                  description: The activation id
                  example: 6616f0ced2f00dd5b8fafbb4
                service:
                  type: string
                  description: The service name
                  example: go
                text:
                  type: string
                  description: The text message
                  example: Your activation code is 1234
                code:
                  type: string
                  description: The activation code
                  example: '1234'
                country:
                  type: string
                  description: The country code
                  example: '0'
                receivedAt:
                  type: string
                  format: date-time
                  description: The date and time the sms was received
                  example: '2022-06-01 12:00:00'
      responses:
        '200':
          $ref: '#/components/responses/200'
components:
  securitySchemes:
    api_key:
      description: |
        All requests must have an API key as a parameter "api_key".
        Your API key provides access to paid services. The API key should be kept confidential
      type: apiKey
      in: query
      name: 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
    UsersBalance:
      description: Returns user's balance response.
      content:
        text/html:
          example: |
            Success server response:
            'ACCESS_BALANCE:balance'


            Possible server response errors:
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - error SQL-server
    Countries:
      description: Countries information
      content:
        text/html:
          example: |
            ANSWER:
            JSON - object in format:
            {{'country':{'id':0,'rus':'Россия','eng':'Russia','chn':'俄罗斯',
            'visible':1,'retry':1,'rent':1,'multiService':1}}

            where (
              id: country id;
              rus: country name in Russian;
              eng: country name in English;
              chn: country name in Chinese;
              visible: 0 - country is not displayed on the site, 1 - displayed;
              retry: 0 - repeated SMS is NOT available, 1 - available;
              rent: 0 - country not leased, 1 - leased;
              multiService: 0 - country is NOT available for multiservice, 1 - available
            )


            Possible server response errors:
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - error SQL-server
    Services:
      description: Services information
      content:
        text/html:
          example: |
            ANSWER:
            JSON - object in format:
            { 
              "status": "success", 
              "services": [{"code":"aoo","name":"Pegasus Airlines"}] 
            }

            Possible server response errors:
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - error SQL-server
    Prices:
      description: Price for a service in a country
      content:
        text/html:
          example: |
            JSON - object in format:
            {"Country":{"Service":{"cost":Cost,"count":Count}}}


            Possible server response errors:
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - error SQL-server
    Number:
      description: Number response
      content:
        text/html:
          example: |
            Success server response:
            'ACCESS_NUMBER:activation_id:number'


            Possible server response errors:
            'WRONG_MAX_PRICE:$min' - the specified maximum price is less than the allowed one ($min - minimum allowable price)
            'BAD_ACTION' - incorrect action
            'BAD_SERVICE' - incorrect service name
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - sql-server error
            'BANNED:YYYY-m-d H-i-s' - time for which the account is blocked
            'WRONG_EXCEPTION_PHONE' - incorrect exclusion prefixes
            'NO_BALANCE_FORWARD' - not enough funds to request number
            'NO_NUMBERS' - there are no numbers available for the specified parameters
    NumberV2:
      description: Number V2 response
      content:
        text/html:
          example: |
            Success server response:
            {
            "activationId": "65aa31afa690a5ebc0c7c24a",
            "phoneNumber": "33780882123",
            "activationCost": "0.3",
            "countryCode": "0",
            "canGetAnotherSms": true,
            "activationTime": "2024-01-19 10:24:18",
            "activationEndTime": "2024-01-19 10:44:18",
            "activationOperator": null
            }


            Possible server response errors:
            'WRONG_MAX_PRICE:$min' - the specified maximum price is less than the allowed one ($min - minimum allowable price)
            'BAD_ACTION' - incorrect action
            'BAD_SERVICE' - incorrect service name
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - sql-server error
            'BANNED:YYYY-m-d H-i-s' - time for which the account is blocked
            'WRONG_EXCEPTION_PHONE' - incorrect exclusion prefixes
            'NO_BALANCE_FORWARD' - not enough funds to request number
            'NO_NUMBERS' - there are no numbers available for the specified parameters
    Activation:
      description: Activation state
      content:
        text/html:
          example: |
            Success server response:

            'STATUS_WAIT_CODE' - waiting for SMS
            'STATUS_WAIT_RETRY:past, unmatched code' - waiting for code clarification
            'STATUS_WAIT_RESEND' - waiting for re-sending SMS (the software must press re-send SMS and change the status to 6)
            'STATUS_CANCEL' - activation canceled
            'STATUS_OK:activation code' - code received


            Possible server response errors:
            'NO_ACTIVATION' - activation id does not exist
            'BAD_KEY' - invalid API key
            'BAD_ACTION' - incorrect action
            'ERROR_SQL' - error SQL-server
    ActivationV2:
      description: Activation state Version 2
      content:
        text/html:
          example: |
            Success server response:
            {
              "sms": {
                "code": "activation code",
                "text": "SMS text"
              }
            }

            If the activation is active, but the code is not received yet, the response will be:
            {
              "sms": null
            }

            If the activation is expired or canceled, the response will be:
            'STATUS_CANCEL' - activation canceled

            Possible server response errors:
            'NO_ACTIVATION' - activation id does not exist
            'BAD_KEY' - invalid API key
            'BAD_ACTION' - incorrect action
            'ERROR_SQL' - error SQL-server
    ChangeStatus:
      description: Change activation status
      content:
        text/html:
          example: |
            Success server response:
            'ACCESS_READY' - numbers readiness confirmed
            'ACCESS_RETRY_GET' - waiting for a new SMS
            'ACCESS_ACTIVATION' - the service has been successfully activated
            'ACCESS_CANCEL' - activation canceled


            Possible server response errors:
            'EARLY_CANCEL_DENIED' - You can't cancel the number within the first 2 minutes
            'NO_ACTIVATION' - activation id does not exist
            'BAD_STATUS' - incorrect status
            'BAD_ACTION' - incorrect action
            'BAD_SERVICE' - incorrect service name
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - sql-server error
    ActivationsHistory:
      description: Activations history
      content:
        text/html:
          example: |
            Success server response format will be as follow:
            [{
              "id": 635468024,
              "date": "2022-11-12 15:58:39",
              "phone": "79918529716",
              "sms": ['Your sms code'],
              "cost": 1.2
            }]


            Possible server response errors:
            'BAD_KEY' - invalid API key
            'BAD_ACTION' - incorrect action
            'ERROR_SQL' - error SQL-server
            'NO_ACTIVATIONS' - no activations
    FullSms:
      description: Number response
      content:
        text/html:
          example: |
            Success server response:
            'FULL_SMS:sms text'


            Possible server response errors:
            'NO_ACTIVATION' - activation id does not exist
            'BAD_ACTION' - incorrect action
            'BAD_SERVICE' - incorrect service name
            'BAD_KEY' - invalid API key
            'ERROR_SQL' - sql-server error
