Platfone Alternative API (0.0.1)

Download OpenAPI specification:

E-mail: [email protected] URL: https://platfone.com License: Apache 2.0 Terms of Service

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

Register an account at https://platfone.com
Add balance to your account
Get your API key from https://platfone.com/app/api

Sandbox environment

🏖️ Try sandbox environment at: 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

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.

User

User account related operations

Get user's balance

Balance inquiry

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getBalance`

Responses

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getBalance"

Response samples

200

Content type

text/html

Success server response:
'ACCESS_BALANCE:balance'


Possible server response errors:
'BAD_KEY' - invalid API key
'ERROR_SQL' - error SQL-server

Activation

SMS activation related operations

Request a number

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.

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getNumber`
$service required	string service for ordering
$country required	string country for ordering
$maxPrice	number 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

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getNumber&service=$service&country=$country&maxPrice=maxPrice"

Response samples

200

Content type

text/html

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

Request a number (v2)

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.

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getNumberV2`
$service required	string service for ordering
$country required	string country for ordering
$maxPrice	number 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

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getNumberV2&service=$service&country=$country&maxPrice=maxPrice"

Response samples

200

Content type

text/html

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

Get activation status

Get activation status.

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getStatus`
$id required	string Activation ID

Responses

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getStatus&id=$id"

Response samples

200

Content type

text/html

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

Get activation status (v2)

Get activation status (version 2). Returns both sms code and text.

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getStatusV2`
$id required	string Activation ID

Responses

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getStatusV2&id=$id"

Response samples

200

Content type

text/html

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

Change activation status

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `setStatus`
$id required	string Activation ID
$status required	integer Enum: 1 3 6 8 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

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=setStatus&status=$status&id=$id"

Response samples

200

Content type

text/html

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

Get activation history

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getHistory`
$start	integer <int64> >= 0 Timestamp in Unix Timestamp format (optional) - from which date to take activations
$end	integer <int64> >= 1 Timestamp in Unix Timestamp format (optional) - by which date to take activations

Responses

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getHistory&start=$start&end=$end"

Response samples

200

Content type

text/html

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

Get full sms text for the number

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getFullSms`
$id required	string Activation ID

Responses

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getFullSms&id=$id"

Response samples

200

Content type

text/html

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

Catalog

Prices, services, countries related operations

Get a list of all countries

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getCountries`
mode	string Default: "strict" Enum: "strict" "enriched" "full" 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

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getCountries"

Response samples

200

Content type

text/html

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

Get a list of all services

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getServicesList`
mode	string Default: "strict" Enum: "strict" "enriched" "full" 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

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getServicesList"

Response samples

200

Content type

text/html

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

Price list

Get current prices

Authorizations:

api_key

query Parameters

$api_key required	string API key
action required	string Action to perform, set to `getPrices`
$service	string Short name of the service (Optional, by default all services)
$country	string Country code name (Optional, defaults to all countries)

Responses

Request samples

CLI

curl -X GET "$server_base_path/stubs/handler_api.php?api_key=$api_key&action=getPrices&service=$service&country=$country"

Response samples

200

Content type

text/html

JSON - object in format:
{"Country":{"Service":{"cost":Cost,"count":Count}}}


Possible server response errors:
'BAD_KEY' - invalid API key
'ERROR_SQL' - error SQL-server

Webhooks 📡

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.

Activation updated webhook Webhook

Issued when an activation recieves sms.

Request Body schema: application/json

activationId	string The activation id
service	string The service name
text	string The text message
code	string The activation code
country	string The country code
receivedAt	string <date-time> The date and time the sms was received

Responses

Request samples

Payload

Content type

application/json

{"activationId": "6616f0ced2f00dd5b8fafbb4",
"service": "go",
"text": "Your activation code is 1234",
"code": "1234",
"country": "0",
"receivedAt": "2022-06-01 12:00:00"
}

Response samples

200

Content type

application/json

{"result": "success"
}