platfone-com User API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Platfone Activation User 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 Activation API
  description: '# About Activation API


    Platfone Activation API will allow you to get temporary mobile number and receive SMS messages to that number. You can use this API to automate SMS activations and OTP verification for your users. Billing applies only to successfully received SMS messages. ## How to use


    1. Register an account

    2. Add balance to your account

    3. Get your API key


    **Sandbox environment**


    🏖️ Try sandbox environment:

    - No balance required. - Use the API and see results in web dashboard. - Send fake SMS via Web or API to 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 in the `X-Api-Key` header. You can get your API key from https://platfone.com/app/api


    ## API base URL


    All requests must be made to the following URL:


    ```

    Production -> https://temp-number-api.com/api/v1

    Sandbox -> https://temp-number-api.com/test/api/v1

    ```


    ## Main API requests


    **Prices**


    - Get prices by service - Get a price list organized by service. - Get prices by country - Get a price list organized by country. - Get price for service in country - Get a price for specific service and country. **Numbers**


    You will get a phone number that can receive unlimited SMS messages for limited time from one specific service. If you want SMS from a different service, you must order a new number for that service. Alternatively, use the "other" service option to receive SMS from any service not listed in the Get services. - Get number - Get a number for a specific service and country. - Cancel number - Cancel a number. This number will no longer receive SMS messages. - Get numbers history - Get a list of numbers you have ordered. **SMS**


    - Get SMS - Get one-time code and full SMS message received by a number. - Request one more SMS - Request one more SMS message from the same number. **Catalog**


    - Get countries - Get a list of countries where mobile phone numbers are provided. - Get services - Get a list of services eligible for activation. **Balance**


    - Get balance - Get your balance. ## Usage 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 `sms_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


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


    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.'
servers:
- url: https://temp-number-api.com/api/v1
security:
- apikey_auth: []
tags:
- name: User
  description: User account related operations.
paths:
  /user/balance:
    servers:
    - url: https://temp-number-api.com/api/v1
    get:
      tags:
      - User
      summary: Get user's balance
      description: 'Retrieves the user''s current balance, 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
      responses:
        '200':
          $ref: '#/components/responses/UsersBalance'
        '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/user/balance" \

          -H "Content-Type: application/json" \

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
components:
  headers:
    Retry-After:
      schema:
        type: integer
        example: 3600
        description: Number of seconds to wait before retrying the request.
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 50
        description: Maximum allowed number of requests.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1706864028
        description: Unix timestamp in seconds when the rate limit will reset.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 0
        description: The number of requests remaining in the current rate limit window.
  responses:
    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'
    '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
    UsersBalance:
      description: User's balance
      content:
        application/json:
          schema:
            title: UserBalance
            type: object
            properties:
              total:
                type: integer
                example: 2301
                description: Available balance in USD cents. Balance may be negative.
              reserved:
                type: integer
                minimum: 0
                example: 210
                description: Reserved balance for uncompleted activations in USD cents
    '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
  schemas:
    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
  securitySchemes:
    apikey_auth:
      description: 'Authenticate all requests by passing API key in `X-API-Key` header.

        '
      type: apiKey
      in: header
      name: X-API-Key