Temp-Number Backend API (by Platfone) (1.0.0)

Returns a mobile phone number for service activation and activation ID. Bills customers amount specified by you. Send an SMS to the provided phone number and use the activation ID to check the SMS with app-getActivation.

Basics

• Specify service_id and country_id to order a number. Retrieve these IDs via app-getServices and app-getCountries.
• For services not listed in catalog, use the special other service.
• is_retriable field in response suggests, if the activation can receive multiple SMS messages.

---

Price Considerations

Billing for SMS Activation

• Only Successful Activations are Billed: You and customer are charged only for activations where an SMS is successfully received. It's important to note that within each activation, only the first received SMS incurs a charge, ensuring you pay only for successful service activation.
• Both Developer and Customer are Billed: The developer is billed for the activation cost, while customer billed by adding markup to price. This ensures you can pass on the cost to the customer while still covering your own expenses.

---

Customer billing

You set CUSTOMER_MARKUP during NodeJS-App Backend installation. CUSTOMER_MARKUP applies to base prices (check them in https://platfone.com). In getPricesByCountry, getPricesByCountry and getPricesForServiceInCountry you get prices with CUSTOMER_MARKUP already applied and ready to be shown to the customer.

---

🔄 Handling Price Changes

The market for temporary numbers is highly dynamic — prices may change every minute.

To prevent overcharging the customer, you MUST set the customer_max_price parameter when creating an activation. This value represents the maximum amount (in USD cents) your customer is willing to pay. Practically, you should set customer_max_price to the price you display in your app or UI, ensuring consistency and trust in your pricing.

🚧 What Happens If the Price Increases?

If no phone number is available at or below your specified customer_max_price, the request will fail with a:

409 MaxPriceExceededException

This means:

• Your price cap was too low for current availability
• But a number just above your limit is available

The response includes:

• suggestedPrice: the updated lowest price available
• order_id: a unique continuation token to retry the activation attempt

🔁 How to Retry the Same Activation Attempt

To continue smoothly:

1. Show the suggestedPrice to your customer, if needed
2. Retry the request using:

• The same order_id
• An updated customer_max_price (e.g., equal to suggestedPrice or higher)

This allows the system to continue the original activation attempt, avoiding full reprocessing and improving the success rate.

✅ Best Practice

• Set customer_max_price to the price you actually show the customer
• On MaxPriceExceededException, use the order_id together with the new customer_max_price to retry seamlessly without starting from scratch

---

Quality Considerations

We constantly monitor the quality of our phone number suppliers. Since higher quality numbers have a better chance of successfully receiving SMS messages, we recommend taking quality into account when ordering numbers.

Quality Factor: The quality_factor parameter allows you to balance quality against price. This parameter is an integer ranging from 0 to 100, with a default value of 50.

• A value of 0 means you prioritize price, essentially disregarding quality in the number selection process.
• A value of 50 indicates you value price and quality equally, offering a balanced approach in your selection.
• A value of 100 indicates a preference for quality, making it the primary criterion for number selection, regardless of price.

Fetches active activations IDs. Optionally include activation data.

Retrieve the activation state, including activation status, sms status, billing status, expiration, SMS code and text message, etc.
Typically, this endpoint is polled either until the SMS is received or the activation expires.

Statuses

There are several statuses that an activation can have, each representing a different state of the activation process. The following are the possible statuses:

💬 sms_status

• Description: Represents the current state of the SMS interaction within the activation process.
• Possible Values:
  • "smsRequested": The initial state when an SMS is requested but not yet received.
  • "smsReceived": The SMS has been received.
  • "retryRequested": The user has requested another SMS.
  • "retryReceived": The user has received a another SMS.

🔁 activation_status

• Description: Represents the overall state of the activation.
• Possible Values:
  • "active": The activation is currently active and can proceed.
  • "finalized": The user has confirmed the activation, and no further changes are possible.
  • "expired": The activation has expired based on the expire_at timestamp.
  • "canceled": The activation was canceled before any SMS was received.

💳 billing_status

• Description: Indicates the billing state of the activation.
• Possible Values:
  • "reserved": Funds are reserved from the user's available balance upon activation creation.
  • "released": No SMS was received, and reserved funds were returned to the available balance.
  • "billed": An SMS was received, and the reserved funds have been charged.
  • "refunded": A refund was issued after a user report, and the amount was returned to the available balance.

📝 report_status

• Description: Represents the status of report filed by the user regarding the activation (e.g., reporting a wrong SMS).
• Possible Values:
  • null: No report has been made.
  • "inReview": The report is under review.
  • "declined": The report was reviewed, and no refund was granted.
  • "approved": The report was reviewed, and a refund was issued.

Expiration

Each activation has a limited lifetime. The expiration time of an activation can be determined by the expire_at attribute. If the activation is not completed within this timeframe, it will expire, and no further SMS retrievals will be possible.

Usage Notes

• Expiration Handling: Developers should validate the expire_at field to ensure the activation is still valid. If the current time is past expire_at, consider the activation expired, even if the activation_status field has not yet been updated to "expired".
• Finalization: The activation_status field includes "finalized" to indicate that the activation has been confirmed by the user, and no further changes are allowed. Finalized activations should be removed from the active activations list.
• Reporting: Use the report_status field to track the outcome of any user reports regarding issues with the activation. This field is closely related to the billing_status if a refund is issued.
• Cancellation: The cancelable_after field indicates when an activation can be canceled. If this field is null, the activation does not support cancellation. If the current time is past the cancelable_after timestamp, the activation can be canceled using cancel operation.
• Retry Handling: The is_retriable field indicates whether the user can request another SMS. If true, the user can request a retry SMS using the retry operation. Retry possible after first sms recieved and while activation_status is active.
• Billing: The price field indicates the cost of the activation in USD cents. The amount is reserved from the user's available balance when the activation is created. The billing_status field indicates the current billing state of the activation.

Instructs the server to overwrite the previous SMS with the first one arriving. Both "code" and "text" fields will be updated. This operation is free of charge, as billing occurs upon receipt of the first SMS.

This operation is only possible if:

• sms_status of the activation is either smsReceived or retryReceived.
• activation_status = active.
• Activation attribute is_retriable = true.

Typically, you can cancel an active activation as long as no SMS has been received.
The cancelable_after field indicates when an activation can be canceled:

• If this field is null, the activation does not support cancellation.
• If the current time is past the cancelable_after timestamp, the activation can be canceled using cancel operation.

Cancellation is only possible if:

• activation_status = active.
• sms_status = smsRequested.
• cancelable_after allows cancelation.

Finalize an activation to prevent further SMS messages from being sent to the phone number and to reduce the number of active numbers.

Finalize is only possible if:

• sms_status of the activation is either of smsReceived, retryRequested or retryReceived.
• activation_status = active
• billing_status = billed

Fetches a history of activations, offering a comprehensive overview of past activation records. Each record includes details such as the activation ID, phone number, country ID, service ID, statuses, SMS code, SMS text, and timestamps for expiration and last update. The response is organized in a paginated format, allowing for efficient navigation through the activation records.

Retrieves the current balance of customer, 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.

Get transactions list of customer. Filter by creation date.

Retrieve information about a customer

Request to delete a customer. The customer is marked for deletion and all operations are restricted.

Get notifications settings of customer.

Set notifications settings of customer.

Set contact us email

Retrieve the price and availability for a specific service in a specific country. Use service_id and country_id to specify the service and country, respectively. These identifiers can be found via the app-getServices and app-getCountries operations.

Retrieve a comprehensive price list, organized by country. This endpoint returns a list of countries, each accompanied by an array of services available within that country, their respective prices, and the amount of available numbers for sale.

Use optional country_id query parameter to get prices in a specific country.

Retrieve a comprehensive price list, organized by service. This endpoint returns a list of services, each accompanied by an array of countries available for that service, their respective prices, and the amount of available numbers for sale.

Use optional service_id request parameter to get prices for a specific service.

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.

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.

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.

Descriptions and warning texts can be fetched in different languages from: https://temp-number.sfo3.cdn.digitaloceanspaces.com/service_descriptions_and_warnings.json

Returns a list of public keys

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

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.

Return a report object by Activation Id

Returns a list of reports with pagination

Create new stripe payment intent for customer.

Get stripe payment intent status by payment intent ID.

Create new appstore transaction for customer. Transaction from appstore passed to this endpoint. If transaction is valid and not already registered it will be saved in Firestore database and synced with customer's balance.

Create new Google Play transaction for customer. Purchase token from Google Play passed to this endpoint. If token is valid and not already registered it will be saved in Firestore database and synced with customer's balance.

Create new paypal order for customer.

Capture paypal order for customer.

Create new cryptomus payment for customer.

Create new customer and set initial balance.

Change customer status.

Available statuses:

• disabled - customer is disabled. All customers operations are restricted.
• active - customer is active. All customers operations are allowed.
• paused - customer is paused. New activations are restricted.
• markedForDeletion - customer is marked for deletion. All customers operations are restricted.

Get customers list with their statuses and balances. Filter by status, customer_id and creation date.