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/).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/platfone-com:platfone-com-webhooks-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.0.0
title: Platfone Activation Webhooks 📡 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: 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.'
paths: {}
webhooks:
activationUpdated:
post:
tags:
- Webhooks 📡
summary: 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/Webhook'
- type: object
properties:
data:
$ref: '#/components/schemas/Activation'
responses:
'200':
$ref: '#/components/responses/200'
activationReportUpdated:
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/Webhook'
- type: object
properties:
data:
type: object
title: ActivationReportUpdated
properties:
activation_id:
$ref: '#/components/schemas/activation_id'
report_status:
$ref: '#/components/schemas/report_status'
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:
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
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.
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
total:
type: integer
example: 2301
description: Available balance in USD cents. Balance may be negative.
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
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.
parameters:
x-signature:
name: x-signature
in: header
description: The signature of the webhook
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-webhook-id:
name: x-webhook-id
in: header
description: The webhook ID
required: true
schema:
type: string
securitySchemes:
apikey_auth:
description: 'Authenticate all requests by passing API key in `X-API-Key` header.
'
type: apiKey
in: header
name: X-API-Key