Platfone Activation API
API docs by Redocly

Platfone Activation API (1.0.0)

Download OpenAPI specification:

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

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

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.

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

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.

API methods (rate limiting)

To ensure optimal performance, the following API methods are subject to these rate limits:

Method Path Limit
GET user/balance 300 requests per 1 minute
POST activation 300 requests per 1 minute
PUT activation/:id/retry 50 requests per 1 minute
PUT activation/:id/cancel 50 requests per 1 minute
GET activation/history 6 requests per 1 minute
GET activation/:id 300 requests per 1 minute
GET activation/countries 15 requests per 1 minute
GET activation/services 15 requests per 1 minute
GET activation/prices/countries 6 requests per 1 minute
GET activation/prices/services 6 requests per 1 minute
GET activation/prices/services/:service_id/countries/:country_id 60 requests per 1 minute

Versioning

The API is subject to change without notice. We will try to keep the API backwards compatible, but we cannot guarantee it. If we make backwards incompatible changes, we will release a new version of the API. The version will be included in the URL. For example, if the current version is v1, the URL will be https://temp-number-api.com/api/v1. If we release a new version, the URL will be https://temp-number-api.com/api/v2.

SMS Activation

SMS activation is a process used in registration, verification, or activation of user accounts, services, or software via SMS text message. This API may be used to automate the activation by receiving SMS to temporary mobile phone number. This section contains the operations related to SMS activation, such as ordering a number, checking the activation status, and retrying or canceling the activation.

Order number for activation

Returns a mobile phone number for service activation and activation id. Send an SMS to the provided phone number and use the activation ID to check the SMS with GET /activation/:activation_id.

Basics

  • Specify service_id and country_id to order a number. Retrieve these IDs via GET /activation/services and GET /activation/countries.
  • For services not listed in catalog, use the special other service. Note: other service usage is not allowed for services listed in our catalog.
  • 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 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.

💰 Managing Activation Costs with max_price

To avoid unexpected charges, you can specify a max_price — the maximum amount (in USD cents) you’re willing to pay for an activation. This helps control your budget and ensures you don't accidentally overspend.

📉 What Happens If No Numbers Are Available Within Your max_price?

If we can’t find an available number within your specified max_price, you’ll receive a 409 MaxPriceExceededException. This means your budget was too low for current availability, but good news — we’ve found suitable numbers just above your limit.

🔁 How to Proceed: Use suggestedPrice and order_id

The error response includes:

  • suggestedPrice: the nearest available price for an activation
  • order_id: a continuation token that keeps the context of your original request

To retry the activation:

  1. Set max_price to the suggestedPrice (or higher)
  2. Include the order_id in your request

This ensures you're continuing the same order attempt and improves your chance of success by preserving the original selection context.

✅ Why This Matters

Using order_id is highly recommended. It:

  • Increases the likelihood of receiving a number quickly
  • Avoids restarting the selection process from scratch
  • Gives your application a smoother retry logic with price control

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.

Response schema

Please refer to "Get activation state" endpoint documentation for the response schema details.

Authorizations:
apikey_auth
Request Body schema: application/json
service_id
required
string [ 1 .. 30 ] characters

ID of Service being verified. Can be retrieved using GET sms/services

country_id
required
string [ 2 .. 9 ] characters

ID of phone number Country. Can be retrieved using GET /countries

max_price
integer [ 1 .. 10000 ]

Maximum price in USD cents you are willing to pay for activation. This safeguards against price changes. If the actual price exceeds this limit, a 409 error is returned along with the new suggested price.

order_id
string

Optional continuation token for an activation attempt that failed due to pricing limits.

When you receive a 409 MaxPriceExceededException, it means no phone numbers were available within your specified max_price, but alternatives are available just above your limit.

In that case, the response includes a suggestedPrice and an order_id. To retry the same activation attempt at the suggested price (or higher), send a new request using the same order_id and a higher max_price.

This ensures the system can continue the previous attempt with the same selection context, potentially increasing the success rate and reducing redundant attempts.

Recommended Usage:

  • Store the order_id when handling a 409 MaxPriceExceededException.
  • Use it to continue the activation attempt once you've decided to raise the max_price.
quality_factor
number [ 0 .. 100 ]

Quality factor for the number. The quality factor is a number between 0 and 100. The default value is 50. 0 - means prefer price over quality. 100 - means prefer quality over price.

Responses

Request samples

Content type
application/json
{
  • "service_id": "7eleven",
  • "country_id": "us",
  • "max_price": 90,
  • "order_id": "682b17b958bf608ceae5ec3c",
  • "quality_factor": 10
}

Response samples

Content type
application/json
{
  • "activation_id": "64a1c0e8d2a1f9b7e45d3b8e",
  • "price": 20,
  • "phone": "14155552671",
  • "country_id": "us",
  • "service_id": "netflix",
  • "sms_status": "smsRequested",
  • "activation_status": "active",
  • "billing_status": "reserved",
  • "report_status": null,
  • "sms_code": null,
  • "sms_text": null,
  • "expire_at": 1729088539,
  • "updated_at": 1729087939,
  • "created_at": 1729087339,
  • "is_retriable": false,
  • "cancelable_after": null
}

Get activation state

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.
Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/${activation_id}" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
Example
{
  • "activation_id": "64a1c0e8d2a1f9b7e45d3b8e",
  • "price": 20,
  • "phone": "14155552671",
  • "country_id": "us",
  • "service_id": "netflix",
  • "sms_status": "smsRequested",
  • "activation_status": "active",
  • "billing_status": "reserved",
  • "report_status": null,
  • "sms_code": null,
  • "sms_text": null,
  • "expire_at": 1729088539,
  • "updated_at": 1729087939,
  • "created_at": 1729087339,
  • "is_retriable": false,
  • "cancelable_after": null
}

Retry 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.
Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Responses

Request samples 

curl -X PUT "${server_base_path}/api/v1/activation/${activation_id}/retry" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "result": "success"
}

Cancel activation

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.
Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Responses

Request samples 

curl -X PUT "${server_base_path}/api/v1/activation/${activation_id}/cancel" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "result": "success"
}

Finalize activation

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
Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Responses

Request samples 

curl -X PUT "${server_base_path}/api/v1/activation/${activation_id}/finalize" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "result": "success"
}

Get activations history

Fetches a history of activations, offering a comprehensive overview of past activation records. Each record includes activation details. The response is organized in a paginated format, allowing for efficient navigation through the activation records.

Authorizations:
apikey_auth
query Parameters
page
integer
Default: 1
Example: page=2

Selected page number

limit
integer [ 1 .. 50 ]
Default: 10
Example: limit=10

Items limit per page

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activations" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "activations": [
    ],
  • "page": 1,
  • "limit": 10,
  • "pages": 5,
  • "total": 48
}

Prices

The section includes endpoints for obtaining prices for activation. Various services have different activation costs, which also depend on the country of the mobile number being ordered. All prices are listed in USD cents. In addition to the price, you can also retrieve the number of available phone numbers for sale.

Price for a Service in a Country

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 getServices and getCountries operations.

Authorizations:
apikey_auth
path Parameters
service_id
required
string <^(([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])$> [ 1 .. 30 ] characters
Example: 7eleven

Service ID, as returned by getServices operation.

country_id
required
string [ 2 .. 9 ] characters ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
Example: uk

Country ID, as returned by the getCountries operation.

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/prices/services/${service_id}/countries/${country_id}" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "price": {
    },
  • "quality": {
    },
  • "count": 143
}

Price list organized by country

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.

Authorizations:
apikey_auth
query Parameters
country_id
string [ 2 .. 9 ] characters ^[a-zA-Z0-9]+([-_]*[a-zA-Z0-9]+)*$
Example: country_id=uk

Country ID, as returned by the getCountries operation.

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/prices/countries" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
[
  • {
    }
]

Price list organized by service

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 query parameter to get prices for a specific service.

Authorizations:
apikey_auth
query Parameters
service_id
string <^(([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])$> [ 1 .. 30 ] characters
Example: service_id=7eleven

Service ID, as returned by getServices operation.

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/prices/services" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
[
  • {
    }
]

Catalog

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.

Get countries

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.

Authorizations:
apikey_auth
header Parameters
If-None-Match
string
Example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465

Optional header for cache validation based on X-ETag.

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/countries" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
[
  • {
    }
]

Get services

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.

Authorizations:
apikey_auth
header Parameters
If-None-Match
string
Example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465

Optional header for cache validation based on X-ETag.

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/services" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
[
  • {
    }
]

Get popular services

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.

Authorizations:
apikey_auth
header Parameters
If-None-Match
string
Example: 2a7d00a6580048cdc81c1ac65bab7be9820e4465

Optional header for cache validation based on X-ETag.

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/services" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
[
  • {
    }
]

User

User account related operations.

Get user's balance

Retrieves the user's current balance, 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.
Authorizations:
apikey_auth

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/user/balance" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "total": 2301,
  • "reserved": 210
}

Activation Report

Activation report related operations.

Get available report reasons for activation

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
Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Responses

Request samples 

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"

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Report activation

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.

Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Request Body schema: multipart/form-data
reason_id
required
integer >= 1

ID of reason

message
string <= 1000 characters

Message with details about the report.

evidence
string <binary>

File upload for evidence. Acceptable file types: jpg, png, webp, zip, pdf, mp4. Maximum file size: 5MB.

Responses

Request samples 

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"}'

Response samples

Content type
application/json
Example
{
  • "status": "accepted",
  • "decline_id": null
}

Get report

Return a report object by Activation Id

Authorizations:
apikey_auth
path Parameters
activation_id
required
string
Example: 63f4d0dab040a865d80da08a

Activation id

Responses

Request samples 

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"

Response samples

Content type
application/json
{
  • "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": {
    }
}

Get reports

Returns a list of reports with pagination

Authorizations:
apikey_auth
query Parameters
page
integer
Default: 1
Example: page=2

Selected page number

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

Items limit per page

Responses

Request samples 

curl -X GET "${server_base_path}/api/v1/activation/reports" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY_HERE"

Response samples

Content type
application/json
{
  • "reports": [
    ],
  • "page": 1,
  • "limit": 10,
  • "pages": 5,
  • "total": 48
}

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's sms_status changes to either:

  • smsReceived
  • retryReceived

This event can be used to notify the customer when sms is received.

header Parameters
x-webhook-id
required
string

The webhook ID

x-timestamp
required
integer
Example: 1632400000

The timestamp of the webhook

x-signature
required
string

The signature of the webhook

Request Body schema: application/json
id
required
string

A unique identifier for the webhook event. Used for idempotency.

api_version
required
string

The version of the API that the webhook event is using.

type
required
string
Enum: "account.low_balance" "activation.updated" "activation_report.updated" "alternative.activation.updated"

The type of webhook event.

required
object (Activation)

The payload of the webhook event. The structure of this object varies depending on the event type.

Responses

Request samples

Content type
application/json
{
  • "id": "abcd1234",
  • "api_version": "1.0",
  • "type": "activation.updated",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Activation report status updated webhook Webhook

Issues a webhook when the activation report status is updated.

header Parameters
x-webhook-id
required
string

The webhook ID

x-timestamp
required
integer
Example: 1632400000

The timestamp of the webhook

x-signature
required
string

The signature of the webhook

Request Body schema: application/json
id
required
string

A unique identifier for the webhook event. Used for idempotency.

api_version
required
string

The version of the API that the webhook event is using.

type
required
string
Enum: "account.low_balance" "activation.updated" "activation_report.updated" "alternative.activation.updated"

The type of webhook event.

required
object (ActivationReportUpdated)

The payload of the webhook event. The structure of this object varies depending on the event type.

Responses

Request samples

Content type
application/json
{
  • "id": "abcd1234",
  • "api_version": "1.0",
  • "type": "activation.updated",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Main account low balance webhook Webhook

Issues a webhook when the account's balance is low.

header Parameters
x-webhook-id
required
string

The webhook ID

x-timestamp
required
integer
Example: 1632400000

The timestamp of the webhook

x-signature
required
string

The signature of the webhook

Request Body schema: application/json
id
required
string

A unique identifier for the webhook event. Used for idempotency.

api_version
required
string

The version of the API that the webhook event is using.

type
required
string
Enum: "account.low_balance" "activation.updated" "activation_report.updated" "alternative.activation.updated"

The type of webhook event.

required
object (AccountBalance)

The payload of the webhook event. The structure of this object varies depending on the event type.

Responses

Request samples

Content type
application/json
{
  • "id": "abcd1234",
  • "api_version": "1.0",
  • "type": "activation.updated",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success"
}