platfone-com Catalog API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Platfone Activation Catalog 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: 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.'
paths:
  /activation/countries:
    servers:
    - url: https://temp-number-api.com/api/v1
    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/activation/countries" \

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

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
  /activation/services:
    servers:
    - url: https://temp-number-api.com/api/v1
    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/activation/services" \

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

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
  /activation/services/popular:
    servers:
    - url: https://temp-number-api.com/api/v1
    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/activation/services" \

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

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
components:
  responses:
    304NotModified:
      description: Not modified (Empty body)
    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'
    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
    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
    '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
  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.
  schemas:
    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'
    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