platfone-com Activation Report API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Platfone Activation Activation Report 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: Activation Report
  description: Activation report related operations.
paths:
  /activation/{activation_id}/report/reasons:
    servers:
    - url: https://temp-number-api.com/api/v1
    get:
      tags:
      - Activation Report
      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/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/ReportReasons'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '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/activation/{activation_id}/report/reasons" \

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

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
  /activation/{activation_id}/report:
    servers:
    - url: https://temp-number-api.com/api/v1
    post:
      tags:
      - Activation Report
      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/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':
          $ref: '#/components/responses/404'
        '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/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:
      - Activation Report
      summary: Get report
      description: Return a report object by Activation Id
      operationId: getReport
      parameters:
      - $ref: '#/components/parameters/activation_id'
      responses:
        '200':
          $ref: '#/components/responses/Report'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '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/${activation_id}/report" \

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

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
  /activation/reports:
    servers:
    - url: https://temp-number-api.com/api/v1
    get:
      tags:
      - Activation Report
      summary: Get reports
      description: Returns a list of reports with pagination
      operationId: getReports
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          $ref: '#/components/responses/Reports'
        '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'
      x-codeSamples:
      - lang: cURL
        label: CLI
        source: 'curl -X GET "${server_base_path}/api/v1/activation/reports" \

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

          -H "x-api-key: YOUR_API_KEY_HERE"

          '
components:
  schemas:
    Activation:
      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.
        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 delivery 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.
    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
    Reports:
      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
            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/Report'
        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
    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
    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.

            '
    Report:
      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/Activation'
    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. \nIf the request status is `accepted`, the Decline ID will be `null`.\n"
          type:
          - integer
          - 'null'
          example: 1
    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
    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
    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
    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
  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'
    Reports:
      description: Reports
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Reports'
    Report:
      description: Report
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Report'
    '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
    '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
    '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
    200Report:
      description: New Report response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/200Report'
          examples:
            reportAccepted:
              $ref: '#/components/examples/reportAccepted'
            reportDeclined:
              $ref: '#/components/examples/reportDeclined'
    '404':
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error404'
    ReportReasons:
      description: List of report reasons with evidence requirements
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReportReasons'
    '400':
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error400'
  parameters:
    page:
      in: query
      name: page
      required: false
      description: Selected page number
      schema:
        type: integer
        example: 2
        description: Selected page number
        default: 1
    activation_id:
      name: activation_id
      in: path
      required: true
      description: Activation id
      schema:
        type: string
        example: 63f4d0dab040a865d80da08a
    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
  headers:
    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.
    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.
  examples:
    reportDeclined:
      summary: Report declined
      value:
        status: declined
        decline_id: 1
    reportAccepted:
      summary: Report accepted
      value:
        status: accepted
        decline_id: null
  securitySchemes:
    apikey_auth:
      description: 'Authenticate all requests by passing API key in `X-API-Key` header.

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