# Onlinesim API URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/info/ General description This API will allow you to access all services provided by Onlinesim: SMS receiving from a single specific service on a virtual number; rent a number to receive SMS from multiple different senders (apps/websites/mobile numbers); you can also use our free numbers to test the service before the purchase. This API is available for registered Onlinesim users only! You need to have Onlinesim profile to be able to access this API. Several methods of authentication are available (Authentication), but we will use API key authentication in this documentation for reasons of simplicity. Receiving messages from payment services, banks, and other financial institutions is not available on our platform. For more detailed information, including a list of such services, please refer to the Public Offer. List of API requests Requests are specific for each service provided by Onlinesim and allocated in corresponding sections: Profile section These requests are related to the profile or all the services provided by Onlinesim: getBalance - returns the current available balance of your profile, the frozen balance (the funds reserved for active operations, which will be returned if those operations are cancelled), and information about your referral program income. webhook - allows you to set a URI to which all the messages from your active operations will be forwarded to. This includes messages from both single-service and long term rental. Single-service activations section Allows you to order a number to receive an unlimited number of SMS from a single service within a short time window (15 minutes for most of the services). Please note that you cannot change the service during the operation. To receive SMS from different services, you will need to order new numbers with the appropriate parameters. getTariffs - returns a quantity of available numbers for each service and country (if specified); getNum - orders a number for a particular service, allowing to receive SMS messages from it; getState - returns detailed information on all active numbers of the profile (including received messages); setOperationRevise - requests next received by the specified number SMS from the queue, if first one didn't have the right code and/or expected information; setOperationOk - sets operation status as successful and closes the operation. Rent section This service implies that the number will be used to receive SMS from multiple different senders (including SMS from other mobile numbers), except for those that are prohibited. tariffsRent - returns a list of countries with detailed information on rental plans; getRentNum - orders a number of a chosen country for rent for a certain period; extendRentState - extends the rent of a given number; getRentState - returns a list of numbers of your profile with current active rent and received messages; closeRentNum - closes the rental number. Free numbers This API allows you to access the functions to use free Onlinesim numbers available on the home page of our website. You can use these numbers for testing, but please note that the quantity of available numbers as well as list of available countries are limited. It is also worth noting that messages received on free numbers are not private — they are displayed in the corresponding widget on the main page and are accessible to other users of the site. There is one general request that allows you to access free numbers: getFreeList - returns detailed information on available list of countries, free numbers and messages they've received. Postman collection available here: Postman documentation Each request has its own description, type, endpoint's URL, parameters, request and response schemas. Some responses can have examples of specific errors that might appear. Responses are represented in JSON or TXT format based on method called and results. Exception Handling For the convenience of display in the interface, only the most common responses are presented. An extended list of possible responses for each endpoint is provided in the OpenAPI 3.1 specification, which can be downloaded via the button in the header (in YAML or JSON format). After downloading, uncomment all linesBelow are common errors: they are not tied to a specific endpoint and may occur in multiple methods. Such responses always come with HTTP status 200, and the error code is passed in the response field: { "response": "ERROR_CODE" } Processing Rules Code format — UPPER_SNAKE_CASE The list of codes is not closed — it may be extended An unknown code should be treated as a generic error and logged for investigation Code Category Description UNDEFINED_COUNTRY Request parameters Invalid country parameter value. Available values are in the country list UNDEFINED_DAYS Request parameters Invalid rental or extension period. Valid values are in the days object of the tariffsRent response for base rental periods, and in the extend object of the getRentState response for extensions ERROR_NO_SERVICE Request parameters Invalid service parameter value. Available values are in the service list NO_NUMBER State and availability No available numbers with the specified parameters. Retry later or try changing the order parameters (country and service for receiving, country and period for rent) WARNING_LOW_BALANCE State and availability Insufficient balance to order a number ACCOUNT_BLOCKED Account and access Account is blocked, contact support API_ACCESS_DISABLED Account and access API access is disabled in the profile settings (the API Included toggle is inactive) API_ACCESS_IP Account and access IP address is not in the allowlist (see Access from IP) ERROR_WRONG_KEY Authorization Invalid API key ERROR_NO_KEY Authorization API key is missing INTERVAL_CONCURRENT_REQUESTS_ERROR Request limits Exceeded the allowed frequency or number of concurrent requests. Reduce the intensity of requests and try again later REQUEST_NOT_FOUND Routing The method name is invalid or missing TRY_AGAIN_LATER Other An unexpected error occurred, try the request again later ## Servers ### `https://onlinesim.io` Onlinesim server --- # Authorization URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/auth/ # Authorization ## apikey API key is a secret key for a simplified authorization in Onlinesim API. How to get an API key: Log in to personal account, go to the Profile and click on API tab. Copy the key from the API Key field and add it to your application. How to use it: All Onlinesim API requests (except for getFreeList) must contain an API key. API key can be specified as a query parameter, for example: https://onlinesim.io/api/getTariffs.php?apikey={apikey} Using an API key provides a simplified way to authorize requests. We recommend using OAuth 2.0 for more secure data handling. For detailed information, please refer to the official OAuth 2.0 documentation. - type: `apiKey` ## BearerAuth The API key can also be used for authorization in the request header using the Authorization: Bearer scheme, for example: Authorization: Bearer {apikey} User-Agent: PostmanRuntime/7.29.2 Accept: */\* Cache-Control: no-cache Postman-Token: 948bc880-8d25-4298-994f-fe6e22ada339 Host: onlinesim.io Accept-Encoding: gzip, deflate, br Connection: keep-alive Cookie: xxxx Using an API key provides a simplified way to authorize requests. We recommend using OAuth 2.0 for more secure data handling. For detailed information, please refer to the official OAuth 2.0 documentation. - type: `http` ## OAuth2 OAuth 2.0 The OAuth 2.0 authorization protocol provides several authorization scenarios, in our case Authorization Code and Implicit Flow types are available. For detailed information, please refer to the official OAuth 2.0 documentation.Authorization URL: https://onlinesim.io/oauth/authorize Token URL: https://onlinesim.io/oauth/token Scopes: sms-scope grants access to manage numbers for the SMS receiving service from Onlinesim; rent-scope grants access to renting phone numbers from Onlinesim; free-scope grants access to using Onlinesim's free numbers. Register the app in our authorization service Open OAuth page Add your app by clicking "Create New Client", then fill the fields below: Name - could be the app name or any other name you and your users will associate with the app; Redirect URL - after user authorization on our server, the client will be redirected with authorization code to this URL. Confidential - (optional), mark the client as Confidential if your application runs on a server and can securely store the Client Secret. Click "Create". New client will appear in the list of applications. Save the Client ID and Secret in a secure location; they will be used by your application for authorization. OAuth 2.0. Authorization code flow Authorize a user and get a token Authorize a client with a GET request to https://onlinesim.io/oauth/authorize with parameters client_id, redirect_uri, response_type, scope, state: Parameter Description Parameter Name Data Type Description client_id STRING Client ID (returned when the app registration process is complete) redirect_uri STRING Redirect destination for the client after a successful authorization, it must match the value of Redirect URL field you've set during app registration process. response_type STRING Use code as a value for Authorization code flow scope STRING Access rights that your app asks from the user. Possible values: sms-scope, rent-scope, free-scope. You can specify multiple values state STRING A random string for CSRF protection (verify it after the redirect) After the request to https://onlinesim.io/oauth/authorize is sent, the user from your app will be redirected to the authorization page to enter the login and password. If successful, authorize your app to work with user data in the Onlinesim service. To do so, he has to click on the Authorize button: At this point, you can check the state parameter, to confirm secure communication with the authorization service If the authorization is successful, the user will be redirected to redirect_uri with the parameter code. Now you can get the access token after making a POST request to https://onlinesim.io/oauth/token: Parameter Description Parameter name Data type Description grant_type STRING Authorization scenario type, use authorization_code when using the Authorization Code flow. client_id STRING Client ID (returned when the app registration process is complete) client_secret STRING Client_secret (returned when the app registration process is complete) redirect_uri STRING Redirect URL for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process. code STRING Authorization code, obtained in the previous step Since client_secret is a private key, it is not recommended to store it in the frontend of the client. For better security, you should store it in the backend of your app. To implement the Authorization Code scenario, you need to pass this code from the frontend to the backend of your service. As a result of a successful request to https://onlinesim.io/oauth/token, you get JSON in response, which contains access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds before the access token is expired and the refresh_token is used to renew the access token when it expires. Authorization and token refreshment For all API requests, add the Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you need to refresh your token or get a new one. { "response": "ERROR_WRONG_KEY" } To refresh the token you must make a POST request to https://onlinesim.io/oauth/token with the parameters grant_type, client_id, client_secret, and refresh_token. For the refresh_token field, use the value obtained in step 4. Parameter Description Parameter name Data type Description grant_type STRING Use refresh_token as a value client_id STRING Client ID (returned when the app registration process is complete) client_secret STRING Client_secret (returned when the app registration process is complete) refresh_token STRING Refresh_token is obtained along with the access_token. It has a much longer lifetime and is used to refresh access_token code STRING Authorization code, obtained in the previous step OAuth 2.0. Implicit flow Authorize a user and get a token Authorize a client with a GET request to the endpoint https://onlinesim.io/oauth/authorize with parameters client_id, redirect_uri, response_type, scope, state: Parameter Description Parameter name Data type Description client_id STRING Client ID (returned when the app registration process is complete) redirect_uri STRING Redirect destination for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process. response_type STRING Use token as a value for Implicit flow scope STRING Access rights that your app asks from the user. Possible values: sms-scope, rent-scope, free-scope. You can specify multiple values state STRING A random string for CSRF protection (verify it after the redirect) After the request to https://onlinesim.io/oauth/authorize is sent, the user will be redirected from your app to the authorization page to enter the login & password and, if successful, authorize your app to work with user data in the Onlinesim service. To do so, he has to click on Authorize button: At this point, you can check the state parameter, to confirm secure communication with the authorization service In case of successful authorization, the user will be redirected to the redirect_uri address with the parameter access_token. This token is required for authorization in Onlinesim API. Authorization of requests to the Onlinesim API Add to all API requests Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you should get a new token. { "response": "ERROR_WRONG_KEY" } - type: `oauth2` --- # Components URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/components/ # Components ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | --- # Get information on current user balance URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-getbalance-php/ **Get information on current user balance** Returns the current balance of the profile, the frozen balance and — optionally — the income from the referral program. You might use it to check the balance of the profile to top it up when needed (for example to handle WARNING_LOW_BALANCE exceptions) ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `income` | query | boolean | | Information on affiliate program earnings | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for getBalance request: the server returns information on your current balance status or throws an exception --- # Get list of free numbers URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-getfreelist/ **Get list of free numbers** Depending on the parameters returns information on available countries with free numbers, received messages and the list of restricted services. Without parameters: returns a list of available countries with free numbers, messages received by the first number from the list and the list of restricted services. With country parameter: returns a list of available free numbers of that country, messages received by the first number from the list and the list of restricted services. With country and number parameters: returns a list of SMS messages received by this number and the list of restrices services. You can send this request to get a number that can be used for SMS receiving, for example for testing. It is worth to mention that since the access for these numbers is public we do not recommend to use them to create accounts for personal use with any personal information.Please note that some services are prohibited for use (and SMS from these services are not available), you can find the list of such services on the front page or in Public offer. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `country` | query | string | | Country code (according to countries list) | | `number` | query | string | | Free phone number, without the country code, whose incoming SMS need to be displayed | | `page` | query | integer | | SMS page number (default is 1) | | `count` | query | integer | | Number of SMS per page. Values below 10 are coerced to 10; values above 500 — to 500. Default is 10 | | `locale` | query | string | | Content language. Defaults to the value of lang | | `as_country_text` | query | string | | If yes, country in the request is treated as a country slug from the config (e.g. moldova) rather than a numeric code | | `with_content` | query | string | | If yes, the response includes the SEO content of the page (content field); otherwise content is null | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for getFreeList request: the server returns information on free numbers and messages they've received, or throws an exception --- # Buy a virtual number for a selected service URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-getnum-php/ **Buy a virtual number for a selected service** Requests a phone number for a particular service, allowing to receive SMS messages from it. Allows you to order a number of a specified country to receive SMS from the website/app that you want. This request in fact plays the same role as the "Buy number" button located on the user dashboard. You can also specify additional parameters such as masks for exception in case if the service has specific requirements. Some websites and applications might block numbers with certain digit sequence (masks) from registration. In this case, this parameter might come in handy. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `service` | query | string | yes | Service names according to the service list | | `country` | query | string | yes | Country code (according to countries list) | | `reject` | query | string[] | | | | `dev_id` | query | integer | | Account ID for software developers (Onlinesim profile's ID) | | `number` | query | boolean | | Flag for displaying detailed information about the operation in the server response. When the value true is passed, the request will return the ordered phone number in the response, as well as a number of additional reference fields | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for getNum request: the server issues a dedicated virtual number for specified service or throws an exception --- # Get information on numbers with active operations URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-getstate-php/ **Get information on numbers with active operations** Returns detailed information on all active numbers you have (or specific one). It allows you to check the status of operations of your account and read the messages received on ordered numbers. For example, you can use this request to get a list of all SMS from active numbers to process them. In fact, this is a representation of active operations section ("My numbers") from the user dashboard. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `tzid` | query | string | | Operation ID, returned by the server when a number is issued (in response to a getNum or getRentNum request). The list of active operations of the profile with their IDs can also be obtained via getState - for receiving operations, and via getRentState - for rental operations. If the operation ID is not passed, the response will contain data on all operations | | `message_to_code` | query | integer | | SMS display mode: 0 - show the entire SMS, 1 - display only the code from the SMS | | `orderby` | query | string | | Sort order of SMS messages by their time of receipt: asc - sorting from oldest to newest; desc - sorting from newest to oldest | | `msg_list` | query | integer | | SMS message list display mode: 0 - only the active message, 1 - as a list of all incoming messages | | `clean` | query | integer | | Message display mode (only for msg_list = 0): 0 - show previosly shown messages, 1 - do not show previously shown messages | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for getState request: the server returns detailed information on active numbers of your account or throws an exception --- # Get information about tariffs for "SMS receiving" service URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-gettariffs-php/ **Get information about tariffs for "SMS receiving" service** This request will provide you Onlinesim tariff list for single-service activations. It is actually a representation of a service list ("Buy a number" section) located in the user dashboard. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `locale_price` | query | string | | Price charged for the service in the currency of your profile (USD by default) | | `country` | query | string | | Country code (according to countries list) | | `filter_country` | query | string | | Filter for countries (discards country objects not related to the target country, leaving only the requested one) | | `filter_service` | query | string | | Filter for service (discards service objects not related to the target one, leaving only the requested one) | | `count` | query | string | | Number of services displayed on one page of the response | | `page` | query | string | | Page of the tariff list (pagination navigation) | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response (with response: "1") or an error (with response: "ERROR_CODE") --- # Close virtual phone number rent operation URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-rent-closerentnum-php/ **Close virtual phone number rent operation** This request closes the specified rental operation (except for US number rentals — they can be closed only upon expiration of the operation term). Closing the operation is irreversible process: once you close the operation, you won't be able to use this rental number again. You should only use this request when you certain that this number is no longer needed. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `tzid` | query | string | yes | Operation ID returned by the server when issuing a number (in response to getNum or getRentNum). The list of active operations on your profile with their IDs can also be obtained via getState or getRentState | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for closeRentNum request: the server closes the current rental operation and returns information for it or throws an exception --- # Extend virtual phone number rent URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-rent-extendrentstate-php/ **Extend virtual phone number rent** Extends a rent for a specified period (in days). This request is needed when your rental period is about to expire, but you plan to continue using it. It is worth to mention, that this request is need to be sended only when the rent is still active. If the rent is already expired, you won't be able to extend it. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `tzid` | query | string | yes | Operation ID returned by the server when issuing a number (in response to getNum or getRentNum). The list of active operations on your profile with their IDs can also be obtained via getState or getRentState | | `days` | query | integer | yes | Extention period for rental number (in days). Can only accept values listed in extend section of getRentState | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for extendRentState request: extends the rent of a number with requested parameters or throws an exception --- # Buy virtual phone number for rent URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-rent-getrentnum-php/ **Buy virtual phone number for rent** This request allows you to rent a number of a specific country for SMS receiving. You can use this request when you need to receive messages from multiple different services or from a single one, but over a long time period. Please note that every new rent operation has a 20 minute protective interval, during which SMS must be received by issued number. If you won't use the number within this timeframe the operation will be terminated automatically and the cost of rent will be refunded.Also some services are prohibited for use (and SMS from these services are not available), you can find the list of such services on the front page or in Public offer. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `country` | query | string | yes | Country code (according to countries list) | | `days` | query | integer | yes | Initial rental period (in days). Valid values are in the days object of the tariffsRent | | `extension` | query | boolean | | Auto-renewal (when enabled, automatically extends the rental for 30 days upon expiration) | | `pagination` | query | boolean | | Message pagination | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for getRentNum request: the server issues a number with requested parameters for rent or throws an exception --- # Get information about the state of virtual phone number rent operation URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-rent-getrentstate-php/ **Get information about the state of virtual phone number rent operation** This request returns a list of active rental numbers. You can use it to quickly browse all your active rental numbers (or only specific one) and their received messages. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `tzid` | query | string | | Operation ID, returned by the server when a number is issued (in response to a getNum or getRentNum request). The list of active operations of the profile with their IDs can also be obtained via getState - for receiving operations, and via getRentState - for rental operations. If the operation ID is not passed, the response will contain data on all operations | | `pagination` | query | boolean | | Pagination mode for message browsing (disabled if false) | | `page` | query | integer | | Page of messages (only relevant when pagination is enabled) | | `per_page` | query | integer | | Number of messages per page, default is 20 (only relevant when pagination is enabled) | | `orderby` | query | string | | Sort order of SMS messages by their time of receipt: asc - sorting from oldest to newest; desc - sorting from newest to oldest | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for getRentState request: the server returns information of specified active rental operation (or all of them) or throws an exception --- # Get information on tariffs for rent numbers URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-rent-tariffsrent-php/ **Get information on tariffs for rent numbers** Returnes information on available for rent numbers of specified country (or all of countries, if not specified): rental plans and other parameters of rent. Unlike regular SMS receiving, rental implies a longer period of use. Also, unlike regular receiving, you can receive any number of SMS messages during the entire rental period from various senders: from websites and applications to SMS sent from regular mobile numbers. If you initially chose a number with the extention option, you can extend the rental at any time before it expires. Please note that some services are prohibited for use (and SMS from these services will not be received), you can find the list of such services on the front page or in Public offer. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `country` | query | string | | Country code (according to countries list) | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for tariffsRent request: the server returns information on available rental plans or throws an exception --- # Complete activation operation URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-setoperationok-php/ **Complete activation operation** Closes the operation and changes its status depending on the result to successful or failed. This request must be sent when you want to explicitly close the operation (for example, after receiving the SMS message you need). You can also temporarily block the re-issuance of this number by passing the ban=1 parameter, for situations where the number is specified in an incorrect format (this is only possible if there are no incoming SMS). Executing of this request is similar to closing active operation in "My numbers" section of the user interface on the website. After closing the operation, you will no longer be able to order or use this number again! If there are no incoming SMS, the operation can be closed only after the protective interval expires (300 seconds for WhatsApp, 120 seconds for other services). ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `tzid` | query | string | yes | Operation ID returned by the server when issuing a number (in response to getNum or getRentNum). The list of active operations on your profile with their IDs can also be obtained via getState or getRentState | | `ban` | query | integer | | This parameter can be used if the number you issued had an incorrect format. You can pass the parameter with the value 1 to block the number, but only if there is no incoming SMS on it | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for setOperationOk request: the server successfully closes the specified operation or throws an exception --- # Request next received SMS from the number URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-get-api-setoperationrevise-php/ **Request next received SMS from the number** Moves the internal pointer to the next SMS message for the specified operation ID. The method only shifts the pointer to the next message within the operation; it does not return the SMS text. To get the message content after calling this method, use getState. This request can be useful when a service sends multiple SMS messages in a row or when you need to receive more than one message from the same service on a single number. For example if the first SMS only contains general information, terms or any promo material and you need the code that is contained in the second SMS, use this request to get the data you need. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `tzid` | query | string | yes | Operation ID returned by the server when issuing a number (in response to getNum or getRentNum). The list of active operations on your profile with their IDs can also be obtained via getState or getRentState | | `lang` | query | string | | Response language: fr - French, de - German, ru - Russian, en - English, zh - Chinese. Please note that the translation applies only to string field values, such as service names or country names. Field names themselves, error messages, and standard values (for example, true/false for boolean fields) remain in English | ## Responses ### 200 Successful response for setOperationRevise request: the server moves the pointer to the next SMS received on this number, or throws an exception --- # Receive SMS via webhook URL: https://onlinesim.io/openapi_docs/Onlinesim-API-UN/Onlinesim-API-UN-post-newsms/ **Receive SMS via webhook** We've added a webhook feature for you! You can set a URL in your profile settings and as soon as we get SMS for any number that you've ordered, it will be forwarded to you. This works for both single-service activations and long term rental! The schema of the incoming payload is described below in the Incoming payload section ## Request Body Required: yes SMS payload sent by Onlinesim to your webhook URL Content-Type: application/json - `schema` (object) - `user_id` (string) Your Profile's ID - `country_code` (string) International dialing code of the country to which the number that received the SMS belongs. Available values are in the Code column of the country list - `number` (string) Phone number in international format - `sender` (string) Sender's name or phone number - `message` (string) SMS context - `time_start` (string) Date and time when operation was ordered - `time_left` (string) Remaining operation time depending on the operation type: for reception — in seconds, for rental — in minutes - `operation_id` (string) Operation ID - `webhook_type` (object) Type of service (single service activations or rent) - `code` (string) SMS ID ## Responses ### 200 Your server should respond with HTTP 200 OK to acknowledge receipt --- # Reseller API URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/info/ General description The API is intended for current and potential Onlinesim partners. It allows you to monetize your numbers by providing them to our customers for receiving SMS from various services and applications. Currently, two versions of the API are implemented: v1 is suitable for partners who already have their own logic for working with numbers. In this scheme, our server contacts yours for information about available numbers and, if a suitable number is found, requests it to receive SMS. v2 has a reverse scheme: the main logic of operations is on our side. You periodically send us a list of your numbers and forward incoming SMS to them, while the numbers are immediately available for order by customers. Both APIs require activation of the Onlinesim partner account! You need to register an Onlinesim profile and contact support for connection information to access these APIs. In this documentation, we will use API key authentication for simplicity, but other authentication methods are also available (more details can be found in the corresponding section (Authorization)). The client is billed for the operation, not for individual SMS. Funds are credited upon successful completion of the operation. The operation can last from 15 minutes (for the "Receive SMS" service) to several months (for the "Number Rental" service) and include several SMS. Please note that by continuing, you agree to this condition! Message filtering in both APIs can be performed either on our side or on yours. Before connecting, you need to inform the support staff on which side the SMS filtering should be performed. Filtering implies checking the SMS you send against the templates of messages of the ordered service. This is necessary to prevent unscrupulous customers from using cheap services to receive SMS from more expensive ones. By default, message filtering is performed on our side. v1 API This integration method is recommended for partners who already have applications with ready-to-use logic. Otherwise, we recommend using API v2, as the operation logic is on our side and its connection is significantly easier. Connection and configuration for each partner are individual, so you need to contact support for details of integration. All interaction takes place via HTTP POST and/or GET requests between the endpoint specified by you and our support. This API will also require the implementation of functionality to exclude the issuance of numbers by their masks. Requirements for v1: Request / response format: JSON4 Encoding: UTF-8 Make sure that the user-agent is included in the request headers All requests / responses use gzip compression The names of countries and services used in the response of GET_SERVICES must match the corresponding lists of countries and services One number should only be used for one operation at a time: your server can issue this same number for another service only after the previous operation is completed It is necessary to implement functionality to exclude the issuance of numbers with certain masks: if an exclusion mask is specified in the request, numbers with such a sequence of digits should not be issued (for the GET_NUMBER request) Webhook PUSH_SMS: your server must automatically forward SMS received by numbers with active operations to the Onlinesim server Filtering can be performed either on our side or on yours. Before integration, inform us which option is preferable for you The number must be issued within 10 seconds of receiving the GET_NUMBER (and GET_NUMBER (RENT)) request, otherwise the number order is canceled Checklist for integration: It is necessary to implement 3 methods and a webhook: GET_SERVICES - requests the number of numbers by country and service from your server GET_NUMBER - reserves a number for a short period (by default 15 minutes) with specified parameters for receiving SMS from a specific service for a specified amount PUSH_SMS (webhook) - when an SMS is received by a reserved number, your server sends it to our server FINISH_ACTIVATION - closes the operation with specific parameters (depending on the result) Contact us via email or Telegram to create a partner profile, provide the URL for requests from our side, obtain a link for the webhook, and test the numbers. After successful tests, your numbers will be available to our customers within a few hours. v2 API Reseller API v2 allows you to integrate your equipment and numbers for their subsequent use by customers for receiving SMS through our website. We have tried to make it as simple as possible for integration. To get started, you need to: Implement 2 methods: sendNumbersOnline - sends a list of your numbers to our server, this request should be sent every 5 minutes to update the list of numbers and as confirmation of your server's uptime; If you plan to use a large number of numbers and sending sendNumbersOnline every 5 minutes as confirmation of uptime is difficult for you, we recommend using an alternative option - the checkWork request. forwarding incoming SMS to our server — addMessage (one message at a time) or addMessages (in batches). It is recommended to use addMessages instead of addMessage and send SMS in batches, for example, once every 5 seconds. Contact support to obtain _SERVER_URL_ The remaining requests are optional, implementing them is not mandatory, but their description is available in the documentation. The requests have an optional parameter test, which can be used for testing. It can take the values test1 and test2; if set to the first, it will allow the request to reach the server but will not trigger function execution. If set to test2, it will return the body of your request in the response. The parameter can be passed either in the query string (for GET methods) or as a field in its body (for POST methods) - both options are valid. After you receive a response indicating that the sendNumbersOnline request was successfully executed, contact partner support to check if our server is receiving messages using the addMessage or addMessages requests. If successful, your numbers will be available to our customers within a few hours. Appendix Workflow ## Servers ### `{yourserver}` Your server URL --- # Authorization URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/auth/ # Authorization ## apikey General Information Requests are authenticated with API key - a secret personal key assigned by our server to identify calls to Reseller API from users. API key should be passed in request's body (v1 Reseller API) or request's header (v2 Reseller API). Unauthenticated calls will result in 401 Unauthorized error. How to get an API key: Log in to personal account, go to the Profile and click on API tab. Copy the key from the corresponding field. How to use it: All Reseller API requests must contain an API key. Based on version, all API calls must contain the key: if you are using v1 Reseller API - it has to be in the 'key' field inside the body of each request, { "action": "GET_SERVICES", "key": "apikey" } if you are using v2 Reseller API - it has to be in the header of each request using Authorization: Bearer schema. Authorization: Bearer {apikey} User-Agent: PostmanRuntime/7.29.2 Accept: */\* Cache-Control: no-cache Postman-Token: 948bc880-8d25-4298-994f-fe6e22ada339 Host: onlinesim.io Accept-Encoding: gzip, deflate, br Connection: keep-alive Cookie: xxxx API key can also be specified as a query parameter apikey for both API versions. https://onlinesim.io/api/getNumbersStats.php?apikey={apikey} - type: `apiKey` --- # Components URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/components/ # Components ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | --- # Remove phone number from Onlinesim server list URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-delete-api-resellers-removenumber/ **Remove phone number from Onlinesim server list** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request allows to delete specific numbers from the list of your current numbers. Please note, that either the phone number in international format or its ID, specified when it was added, must be passed in the request. Simultaneous passing of both parameters is not allowed. You can use it instead of sendNumbersOnline request to modify the list of numbers precisely, by deleting the numbers that are on the list. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `number` | query | string | | Phone number in international format (including country code). Required if id parameter is not passed. Cannot be passed simultaneously with id parameter. | | `id` | query | integer | | ID of the phone number, specified when it was added. Required if number parameter is not passed. Cannot be passed simultaneously with number parameter. | | `Authorization` | header | string | yes | see more here | | `test` | query | string | | Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. | ## Responses ### 200 Onlinesim server response ### 400 Missing or incorred parameters (request must contain parameters in it's body with proper names as described in documentation) ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Remove multiple phone numbers from the existing list URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-delete-api-resellers-removenumbers/ **Remove multiple phone numbers from the existing list** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request allows to delete specific numbers from the list of your current numbers in bulk. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `test` | query | string | | Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. | ## Request Body Content-Type: application/json - `schema` (object) - `ids` (string[]) - `items` (string) Number ID - `numbers` (string[]) - `items` (string) Number in international format (with + sign) - `[0]` (object) - `[1]` (object) ## Responses ### 200 Onlinesim server response ### 400 Missing or incorred parameters (request must contain parameters in it's body with proper names as described in documentation) ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Confirm server uptime status URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-get-api-resellers/ **Confirm server uptime status** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request serves as confirmation that your server is up and running. This is alternative to sending sendNumbersOnline every 5 minutes, you can send checkWork request with no additional parameters with same time interval. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `test` | query | string | | Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. | ## Responses ### 200 Onlinesim server response ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Get detailed information about phone number and it's status URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-get-api-resellers-checknumber/ **Get detailed information about phone number and it's status** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request retrieves detailed information about the number. You might need it to gather the data to analyse the statistics. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `number` | query | string | yes | Phone number in international format (including country code) | | `with_history` | query | boolean | | Detailed operation history flag (when true returns a list of operations for the specified numbers) | | `Authorization` | header | string | yes | see more here | | `test` | query | string | | Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. | ## Responses ### 200 Onlinesim server response ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Get detailed information about specified phone numbers in your profile and their statuses URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-get-api-resellers-checknumbers/ **Get detailed information about specified phone numbers in your profile and their statuses** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request is similar to checkNumber request, with exception that it allows you to check numbers on the Onlinesim server in bulk. It provides a detailed information about specified numbers, or about all numbers on your account if no specific numbers are passed. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `with_history` | query | boolean | | Detailed operation history flag (when true returns a list of completed operations for the specified numbers) | | `Authorization` | header | string | yes | see more here | | `test` | query | string | | Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. | ## Request Body Content-Type: application/json - `schema` (object) - `numbers` (string[]) - `items` (string) Number in international format (with + sign) ## Responses ### 200 Onlinesim server response ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Get information about numbers income URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-get-api-resellers-takeoffnumbers/ **Get information about numbers income** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request is optional, and you can skip this part. It returns income information of your online numbers, this data is also available on your personal page. It returns a list of online numbers of the account which income is greater than the specified sum parameter value. This request can be used to quickly obtain information on what online numbers has reached the desired income and can be replaced with new ones. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `sum` | query | string | | Filter income value, in rubles. For example: if sum = 37.5, the request will return a list of online numbers which income is equal to 37.5 RUB or more If 0 passed as a value, the server returns a list of all online numbers of the account. | | `Authorization` | header | string | yes | see more here | | `test` | query | string | | Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. | ## Responses ### 200 Onlinesim server response ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Get country names list URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-get-countries/ **Get country names list** This request returns a list of country names. Your GET_SERVICES server response must use country names listed here. Note that some countries might be temporarily disabled on our website. Please inform us whenever you want to add numbers for the countries you were not providing previosly. ## Responses ### 200 Example of successful response for country names list request --- # Get service names list URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-get-services/ **Get service names list** This request returns a list of names for all services. Your GET_SERVICES server response must use service names listed here. Please note that some services might be disabled for certain countries as some apps and websites target specifically one or a few regions, disabling the ability to use phone numbers from other countries. ## Responses ### 200 Example of successful response for service names list request --- # Change the list of the disabled services URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-api-auth-me/ **Change the list of the disabled services** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.After modifying the list of disabled services, you need to resend the sendNumbersOnline request with the numbers for the changes to take effect.This request allows to add services to the blacklist preventing them to be used for SMS activation on your numbers. This request might come in handy when you use your numbers for SMS verification for your own purposes or projects. It will block these services on your account entirely assigning them USED status and preventing them to be issued to the clients. This request modifies the whole blacklist, so if you want to add a new service to it, you should also include those services that were on the list before.This blacklist doesn't work for the rent: rental phone numbers WILL BE ABLE TO RECEIVE SMS FROM BLACKLISTED SERVICES . ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Payload for saveConfig request Content-Type: application/json - `schema` (object) - `disabled_service` (object) An object where the keys and values are the slugs of services that should be disabled for sale on your account. The names must match theservices list - `[additionalProperties]` (string) Short service name (slug) ## Responses ### 200 Successful response with partner profile data ### 400 Missing or incorred parameters (request must contain parameters in it's body with proper names as described in documentation) ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions ### 422 Unprocessable Entity. The request was well-formed but contained semantic errors. The response and message fields contain the same JSON string with detailed error mapping. Parse this string as JSON to identify which fields failed validation. --- # Forward received SMS to Onlinesim server URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-api-resellers-addmessage/ **Forward received SMS to Onlinesim server** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This requests forwards messages that were received by your numbers to our server. You can filter the messages before sending a request (send only SMS from ordered service) or send all messages, and we will filter them on our side. You can also block all incoming SMS containing confidential or sensitive information such as SMS with credentials of private account on mobile operator's website and other SMS. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `Content-Type` | header | string | yes | Content type header and encoding scheme | ## Request Body Your server should send this request as soon as number with active operation receives the message (webhook). Content-Type: application/json - `schema` (object) - `[0]` (object) - `number` (oneOf) Phone number in international format or number's ID (see sendNumbersOnline server response) - `[0]` (integer) - `[1]` (string) - `from` (string) Name or a phone number of a sender - `message` (string) Message text - `date` (string) Date and time when SMS was received (in any format, for example in UNIX timestamp) - `[1]` (object) - `test` (string) Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. ## Responses ### 200 Onlinesim server response ### 400 Bad Request ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions ### 404 Not Found --- # Batch forward received SMS to Onlinesim server URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-api-resellers-addmessages/ **Batch forward received SMS to Onlinesim server** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request forwards multiple incoming SMS messages to Onlinesim server in a single batch. We recommend using this method instead of addMessage and sending SMS in batches, for example once every 5 seconds. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `Content-Type` | header | string | yes | Content type header and encoding scheme | ## Request Body Your server should send this request when new messages are received and you need to forward multiple SMS at once. Content-Type: application/json - `schema` (object) - `messages` (object[]) Array of messages. - `items` (object) - `number` (oneOf) Phone number in international format or number's ID (see sendNumbersOnline server response) - `[0]` (integer) - `[1]` (string) - `from` (string) Name or a phone number of a sender - `message` (string) Message text - `date` (string) Date and time when SMS was received (in any format, for example in UNIX timestamp) - `test` (string) Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. ## Responses ### 200 Onlinesim server response ### 400 Missing or incorred parameters (request must contain parameters in it's body with proper names as described in documentation) ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Forward specified phone numbers to Onlinesim server URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-api-resellers-addnumber/ **Forward specified phone numbers to Onlinesim server** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request allows you to add numbers to the Onlinesim server by one at a time, on the contrary to sendNumbersOnline that sends all active numbers as a list. This could be especially useful if you need to add new numbers to the list of existing ones, instead of passing the modified list every time when you add new numbers. Enabling rent parameter (by assigning value 1 to it) allows clients to rent your number for a longer period, significantly increasing your income. However you need to contact partner support to get a detailed information on terms and requirements before we enable it for your account. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Adding new numbers to the list of existing ones on Onlinesim server. Content-Type: application/json - `schema` (object) Payload schema - `[0]` (object) - `number` (string) Phone number in international format - `country_id` (integer) Country code (according to countries list) - `operator` (integer) MCC + MNC operator code (first 5 digits of IMSI) - `date_start` (integer) Date and time of the start of the phone number placement in UNIX timestamp format - `port_id` (string) Unique port name, this name will be displayed in our interface on your personal web-page. Unless specified defaults to phone number value (value of number parameter) - `used` (string[]) - `items` (string) List of services to mark this number as used. Pass values from the Service column of the services table (e.g. vkcom, tg, google). Server caches this value for about a week from the last time it was passed and uses it when the number is activated. Any repeated request with this parameter resets the cache and starts a new countdown. If used is not passed in the request, server will use previously cached value (if any). To clear the cache, pass an empty array []. - `rent` (integer) Rent mode for this number: 1 - enabled, 0 - disabled - `[1]` (object) - `test` (string) Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. ## Responses ### 200 Onlinesim server response ### 400 Missing or incorred parameters (request must contain parameters in it's body with proper names as described in documentation) ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Add multiple phone numbers to the existing list URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-api-resellers-addnumbers/ **Add multiple phone numbers to the existing list** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This request allows you to add new numbers the list of existing ones to the Onlinesim server in bulk. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Content-Type: application/json - `schema` (object) - `numbers` (object[]) - `items` (object) - `number` (string) Number in international format (with + sign) - `country_id` (integer) Country code (according to countries list) - `port_id` (string) Unique port name, this name will be displayed in our interface on your personal web-page. Unless specified defaults to phone number value (value of number parameter) - `used` (string[]) List of services to mark this number as used. Pass values from the Service column of the services table (e.g. vkcom, tg, google). The server caches the passed value for about a week from the last retrieval and uses it when the number is enabled. Re-sending the request with this parameter resets the cache expiration and starts the countdown again. If used is not passed in the request, the server uses the previous cached value (if any). To clear the cache, pass an empty array []. - `items` (string) - `rent` (integer) Rent mode for this number: 1 - enabled, 0 - disabled - `operator` (integer) MCC + MNC operator code (first 5 digits of IMSI) - `date_start` (integer) Date and time of placement (UNIX timestamp) - `test` (string) Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. ## Responses ### 200 Onlinesim server response ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Send phone numbers in bulk to Onlinesim server list URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-api-resellers-sendnumbersonline/ **Send phone numbers in bulk to Onlinesim server list** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.In this request all numbers available for sale should be passed. This request should be sent to Onlinesim server every 5 minutes (to ensure that your server is up and running) and after any change in the number list: after adding new numbers or removing any of previously passed ones. However, there is another way: you can send checkWork request every 5 minutes (as confirmation that your server is up and running), and use addNumber and removeNumber to add or delete numbers respectively. If your server is not confirmed to be up and running (via sendNumbersOnline or checkWork) within 10 minutes, the system will consider your server unavailable and automatically remove all your numbers from issuing. Only list of active numbers should be passed in this request. If you have a 32 port device and a 512 port SIM bank, you should send a list with 32 numbers that currently in the ports. Violation of this condition will cause the system to automatically block receiving numbers from you for 30 minutes.Enabling rent parameter (by assigning value 1 to it) allows clients to rent your number for a longer period, significantly increasing your income. However you need to contact partner support to get a detailed information on terms and requirements before we enable it for your account. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Your server should send this request every 5 minutes as a confirmation of uptime or when the list of available numbers is changed (when new numbers are added or previously passed ones are removed). Content-Type: application/json - `schema` (object) - `numbers` (object[]) - `items` (object) - `number` (string) Phone number in international format - `country_id` (integer) Country code (according to countries list) - `operator` (integer) MCC + MNC operator code (first 5 digits of IMSI) - `date_start` (integer) Date and time of the start of the phone number placement in UNIX timestamp format - `port_id` (string) Unique port name, this name will be displayed in our interface on your personal web-page. Unless specified defaults to phone number value (value of number parameter) - `used` (string[]) - `items` (string) List of services to mark this number as used. Pass values from the Service column of the services table (e.g. vkcom, tg, google). Server caches this value for about a week from the last time it was passed and uses it when the number is activated. Any repeated request with this parameter resets the cache and starts a new countdown. If used is not passed in the request, server will use previously cached value (if any). To clear the cache, pass an empty array []. - `rent` (integer) Rent mode for this number: 1 - enabled, 0 - disabled - `test` (string) Optional field for the request body of Reseller API v2. Allowed values are test1, test2. While being assigned, test1 value will allow the request to be passed, however the data won't be saved by our server (the function will not be executed by this request). While being assigned, test2 value will print out your request's payload in response. Can be passed as query parameter (for GET) or as a field in request's body (for POST). Both ways are equivalent, but using them simultaneously is not recommended. ## Responses ### 200 Onlinesim server response ### 400 Bad Request ### 401 Unauthorized. The request is missing or uses an invalid API key. Some endpoints may return a 200 status with an ERROR_WRONG_KEY message instead of 401 — check the response body ### 403 Forbidden. The request was understood but refused due to insufficient permissions --- # Finish current operation URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-finishactivation/ **Finish current operation** This request is sent by Onlinesim server to close current operation with a certain status (which depends on the result of operation). By default, this request is sent when the operation time expires. The request may also be sent earlier in one of the following two cases: if an SMS from the requested service was successfully received and the client closes the operation manually; if an SMS from the requested service was not received and the client cancels the operation. Receiving a request with status 1 is a signal that the number for some reason could not receive an SMS from the requested service. In essence, it is a signal that it is better not to issue this number for the specified service, as without additional checks the next operation is likely to fail. You can use this status as an indicator to check problematic "number + service" pairs and exclude them from issuance in the future. If you do not want to use this status, you can ignore it and continue to issue numbers for this service. Your server must sent successful operation closing response within 10 seconds of the request. Otherwise current request will be cancelled and a new request will be sent.Please do not close operations on your side until you receive our FINISH_ACTIVATION request. Closing operations manually may lead to status desynchronization and incorrect processing of subsequent requests. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Request payload from Onlinesim server Content-Type: application/json - `schema` (object) - `action` (string) Method name, in this case FINISH_ACTIVATION - `activationId` (integer) Operation ID (assigned by your server) - `sum` (number) Sum credited to the partner’s balance for the provided service (in RUB) - `status` (integer) Status code of the operation, enum: 1 - The number could not receive an SMS from the requested service during three (or more) operations. Check if there are problems with this number and service, it may be worth excluding it from issuance in the future 3 - Successfully sold 4 - Cancelled, message was not delivered 5 - Refunded, in case of errors and message problems - `key` (string) API key of your Onlinesim partner's profile ## Responses ### 200 The successful response of your server for FINISH_ACTIVATION request must be in following format: --- # Finish rent operation of a virtual phone number URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-finishactivationrent/ **Finish rent operation of a virtual phone number** This request is sent by Onlinesim server to close current rent operation with a specific status (which depends on the result of operation). By default, this request is sent when the operation time expires. The request may also be sent earlier in one of the following two cases: if an SMS from the requested service was successfully received and the client closes the rental operation ahead of time; if an SMS from the requested service was not received and the operation is closed after the protective interval expires (20 minutes from the moment the operation was created). Receiving a request with status 1 is a signal that the number for some reason failed to receive an SMS from the requested service within three (or more) operations. You can use this status as an indicator for the need to check the number and exclude it from issuing in the future, or ignore it. You can either create a new endpoint for the rent only or use your existing FINISH_ACTIVATION endpoint for single-service activations (v1). However in the latter case you need to modify it so your server could process the closing of rental operations correctly. Your server must sent successful rent operation closing response within 10 seconds of the request. Otherwise current request will be cancelled and a new request will be sent.Please do not close operations on your side until you receive our FINISH_ACTIVATION request. Closing operations manually may lead to status desynchronization and incorrect processing of subsequent requests. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Request payload from Onlinesim server Content-Type: application/json - `schema` (object) - `action` (string) Method name, in this case FINISH_ACTIVATION - `activationId` (integer) Operation ID (assigned by your server) - `status` (integer) Status code of the operation, enum: 1 - Number failed to receive SMS within three (or more) rent operations. Check if there are any problems with this number, maybe it should be excluded from issuing in the future 3 - Successfully sold 4 - Cancelled, message was not delivered 5 - Refunded, in case of errors and message problems - `key` (string) API key of your Onlinesim partner's profile - `service` (string) Service name, in this case rent - `sum` (number) Total service price that includes all rental periods, in RUB (this sum will be credited to your Onlinesim account after successful rental operation) ## Responses ### 200 The response of your server for FINISH_ACTIVATION request must be in following format: --- # Order a virtual number for the specified service URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-getnumber/ **Order a virtual number for the specified service** Request for ordering a number for SMS receiving from a specified service. This request is sent to your server to order a number with specific parameters to receive SMS from a single service for short period (default is 15 minutes). The operation can be closed prematurely (check FINISH_ACTIVATION). Your server must issue a number with specified parameters within 10 seconds of the request. Otherwise current request will be cancelled.As we mentioned before, you will have to implement a fucntionality for number's mask exception: optional parameter exceptionPhoneSet might contain an array with exception set. When one does, your server should exclude numbers with matching patters from issuing them. For example, if [46950] value is passed, your server should not issue numbers of Sweden that start with +46950* Numbers that are used in one operation cannot be used in other until the previous operation is closed (until FINISH_ACTIVATION request is received). ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `Content-Type` | header | string | yes | Content type header and encoding scheme | ## Request Body Request payload from Onlinesim server Content-Type: application/json - `schema` (object) - `action` (string) Method name, in this case GET_NUMBER - `country` (string) 'Country name, enum (country list)' - `operator` (string) 'Operator name (for examples take a look at operator list)' - `service` (string) 'Service name, enum (service list)' - `sum` (number) Service price, in RUB (this sum will be credited to your Onlinesim account after successful operation) - `key` (string) API key of your Onlinesim partner's profile - `exceptionPhoneSet` (integer[]) List of exception prefixes that SHOULD NOT be issued when the number is requested. Format: country code + following digits of a number. - `items` (integer) ## Responses ### 200 The response of your server for GET_NUMBER request must be in following format: --- # Order rent of a virtual phone number URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-getnumberrent/ **Order rent of a virtual phone number** This request creates a new rent operation, which will allow to use a number to receive SMS from any service and other mobile numbers for a long period of time (from 1 day up to several months). DO NOT CLOSE an operation before FINISH_ACTIVATION request.You can either create a new endpoint for rent orders only or use the same GET_NUMBER endpoint as for single-service activations (v1). However in the latter case you need to modify it so your server could create the rental operation correctly. Your server must issue a number for rent with specified parameters within 10 seconds of the request. Otherwise current request will be cancelled.If number won't receive SMS within 20 minutes after operation is created, the operation will be cancelled automatically, making it available for another operation. If number fails 3 consecutive operations to receive SMS within 20 minutes, it will be banned by our server. These bans are lifted automatically every 24 hours. Rent can be prolonged by the client, but the income is CREDITED UPON OPERATION CLOSING (upon rent expiration or termination). We're blocking messages from banks, payment systems and credit institutions to prevent any legal consequences for our partners that might be caused by unscrupulous customers. At the same time long term rental does not support any exceptions for services as we don't know beforehand which service may or may not be used by our clients. Please keep in mind that ANY BLACKLISTED SERVICES YOU MAY ADD FOR SINGLE-SERVICE ACTIVATIONS WILL NOT BE APPLIED FOR RENT. You will have to implement a fucntionality for number's mask exception for rent (same as for regular SMS receiving): optional parameter exceptionPhoneSet might contain an array with exception set. When one does, your server should exclude numbers with matching patters from issuing them. For example, if [46950] value is passed, your server should not issue numbers of Sweden for rent that start with +46950* ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Request payload from Onlinesim server for rent operation Content-Type: application/json - `schema` (object) - `action` (string) Method name, in this case GET_NUMBER - `key` (string) API key of your Onlinesim partner's profile - `country` (string) Country name, enum (country list)' - `operator` (string) 'Operator name (for examples take a look at operator list)' - `service` (string) Service name, enum. For long term rental value is always rent - `sum` (number) Price for initial rental period, in RUB (this amount will be credited to your Onlinesim account when operation is closed successfully) - `exceptionPhoneSet` (integer[]) List of exception prefixes that SHOULD NOT BE ISSUED when the number is requested. Format: country code + following digits of a number. I.e, when value 46950 is passed, numbers of Sweden starting with +46950 shouldn't be issued - `items` (integer) ## Responses ### 200 The response of your server for GET_NUMBER request must be in following format: --- # Get list of available services and countries URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-getservices/ **Get list of available services and countries** This request is sent from Onlinesim server to yours every minute to get a quantity of available numbers. Your server should return a relevant list of available numbers in format described below. Your partner's API key will be passed in the request in a payload. Your server must return actual quantity of numbers, simultaneously available for order, in the context of "country + service" pair. Take into account also the actual capacity of your hardware: for example, if you have a SIM bank with 512 ports, but only 64 GSM modules, you should return 64 numbers, not 512. If your server reports that numbers are available for a pair, but then repeatedly fails to provide a number when an order is received (returning an error), the system will automatically block number issuance for that pair.Your server must issue a list with quantity of available numbers within 10 seconds of the request. Otherwise current request will be cancelled.operatorMap should contain operator any that includes summarized amount of numbers of all operators for each service Each successful operation has to reduce count of available numbers for the service by 1. If operation was cancelled or failed (SMS hasn't been received), the counter has to remain unchanged. Operation result is passed as status parameter in FINISH_ACTIVATION request. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Request payload from Onlinesim server Content-Type: application/json - `schema` (object) - `action` (string) Method name, in this case GET_SERVICES - `key` (string) API key of your Onlinesim partner's profile ## Responses ### 200 The response of your server for GET_SERVICES request must be in following format: --- # Get list of available services and countries for rent URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-getservicesrent/ **Get list of available services and countries for rent** This request is sent from Onlinesim server to yours to get a list of available for rent numbers. Your server should return a list of numbers in format described below. Your partner's API key will be passed in the request in a payload. You can either add a result field that contains quantity of available numbers for rent to your existing GET_SERVICES endpoint response for singe-service activations (v1) or create a new endpoint for rent only.Your server must return actual quantity of numbers that are available for order, in terms of "country + service" combination. Also take into account the actual capacity of your hardware: for example, if you have a SIM bank with 512 ports, but only 64 GSM modules, you should return 64 numbers, not 512. If your server reports that numbers for the combination are available, but then repeatedly fails to issue a number when an order comes in (returns an error), the system automatically blocks the issuance of numbers for this combination for some time.Your server must issue a list with quantity of available numbers for rent within 10 seconds of the request. Otherwise current request will be cancelled.operatorMap must contain operator any that includes summarized amount of numbers of all operators listed for rent. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | ## Request Body Request payload from Onlinesim server Content-Type: application/json - `schema` (object) - `action` (string) Method name, in this case GET_SERVICES - `key` (string) API key of your Onlinesim partner's profile ## Responses ### 200 The response of your server for GET_SERVICES request must be in following format: --- # Send SMS to Onlinesim URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-v1-push_sms/ **Send SMS to Onlinesim** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.This is a webhook for sending messages to Onlinesim server. These requests should be sent automatically when your number with active operation has received a message to forward it to Onlinesim server. If you get a response with 200(OK) status, SMS can be marked in your database as successfully delivered (don't send message again). If response is different from 200, then in 10 seconds another request with the same context should be sent, unless it's NO_OPERATION or BAD_SERVICE error. Request header should have utf-8 encode scheme placed in 'Content-Type' ('Content-Type': 'application/json; charset=utf-8'). Following responses with errors are possible: NO_OPERATION / NO_OP - this error occurs when you try to push SMS for a number that has no active operation; BAD_SERVICE - this error occurs when you try to push SMS from a service that is banned by our server (banks, payment systems, etc.); IGNORED - this error occurs when you try to push SMS from a service that is differs from the one the client has ordered (only appears when filtration is done on our side); SERVICE_BAN - this error occurs when you try to push SMS from the service you've blacklisted (you can add services to the blacklist, it prevents users to order your numbers for these services) ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `Content-Type` | header | string | yes | Content type header and encoding scheme | ## Request Body PUSH_SMS webhook: your server must send this request once an event is triggered (when the ordered number has received a message). Content-Type: application/json - `schema` (object) - `smsId` (integer) Operation ID (assigned by your server) - `phoneFrom` (string) Name or phone number of a sender - `phone` (string) Phone number with active operation, that has received the SMS - `text` (string) Message text - `action` (string) Method name, in this case PUSH_SMS - `key` (string) API key of your Onlinesim partner's profile ## Responses ### 200 Onlinesim server response ### 404 NO_OPERATION / NO_OP This error occurs when you try to push SMS for a number that has no active operation --- # Send SMS to Onlinesim for rent operation URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/Reseller-API-UN-post-v1-push_sms_rent/ **Send SMS to Onlinesim for rent operation** URL of Onlinesim server is provided by Onlinesim partner support specialists. Please note, that the URL in the example is just a placeholder.If you get a response with 200(OK) status, SMS can be marked in your database as successfully delivered (don't send message again). If response is different from 200, then in 10 seconds another request with the same context should be sent, unless it's NO_OPERATION or BAD_SERVICE error. Request header should have utf-8 encode scheme placed in 'Content-Type' ('Content-Type': 'application/json; charset=utf-8'). Following responses with errors are possible: NO_OPERATION / NO_OP - this error occurs when you try to push SMS for a number that has no active operation; BAD_SERVICE - this error occurs when you try to push SMS from a service that is banned by our server (banks, payment systems, etc.); IGNORED - this error occurs when you try to push SMS from a service that is differs from the one the client has ordered (only appears when filtration is done on our side); SERVICE_BAN - this error occurs when you try to push SMS from the service you've blacklisted (you can add services to the blacklist, it prevents users to order your numbers for these services) ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `Authorization` | header | string | yes | see more here | | `Content-Type` | header | string | yes | Content type header and encoding scheme | ## Request Body PUSH_SMS webhook: your server must send this request once an event is triggered (when the ordered number has received a message). Content-Type: application/json - `schema` (object) - `smsId` (integer) Operation ID (assigned by your server) - `phoneFrom` (string) Name or a phone number of a sender - `phone` (string) Phone number with active operation, that has received the SMS - `text` (string) Message text - `action` (string) Method name, in this case PUSH_SMS - `key` (string) API key of your Onlinesim partner's profile - `service` (string) Service name, for long term rental always rent ## Responses ### 200 Onlinesim server response --- # Countries URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/custom/countries/ List of supported country codes for the API. Use these codes in the country parameter. --- # Operators URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/custom/operators/ List of supported operators. Use these codes in the operator parameter. --- # Services URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/custom/services/ List of supported services for SMS activation. Use these service names in the service parameter. --- # Testing URL: https://onlinesim.io/openapi_docs/Reseller-API-UN/custom/testing/ Testing Protocol After implementing the protocol, Onlinesim developers will test it. When you are ready, please send your URL to our support team. After that, your server must be available 24/7. We will start testing as soon as possible. The tests we will conduct: Simultaneous number issuance for the same service. The most important test. Your system must correctly handle simultaneous requests and must not issue the same number again. For example, the system will send 30 requests with the same criteria: russia, megafon, vk. If you issued a number again - test failed. Correct handling of activation completion request. Activation management is done ONLY on the Onlinesim side. For reasons beyond our control (network issues), we may not receive a response from you about the successful status change. Therefore, if Onlinesim sends the activation completion status again, you must check for the existence of such an activation by id and if the activation exists, send status SUCCESS. Also, you should NOT complete the activation on your side independently. Only a request from Onlinesim to complete the operation should complete the activation on your side. SMS Test. After the SMS has reached your database, you must forward it to us as soon as possible. When an SMS arrives - send it to us immediately. If you receive a response with status SUCCESS, mark the SMS in your database as successfully delivered and do not send it again. If a status other than SUCCESS is returned, repeat the request with a 10-second delay until you receive status SUCCESS. If you send the same SMS after we respond to you with status SUCCESS - test failed. Field types. Carefully check the field types you send via the protocol. If the protocol description says that the field is of numeric type, and you send smsId: «123» - test failed. The phone number must include the country code. In the phone number request, the field number and in the SMS delivery request, the field phone must be NUMERIC and WITH the country code. The time to issue a number from you should be minimal. If the time to issue a number is more than 3 seconds - test failed. The number of numbers returned by the GET_SERVICES request should reflect reality. If you return 100 vk, but in reality there are 30, and 70 requests will return with the response NO_NUMBERS - test failed. Test for excluding prefixes. You must correctly handle the exceptionPhoneSet field when requesting GET_NUMBER. If you issue a phone number whose prefix is in the list - test failed. --- # Alternative API URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/info/ General description Alternative API for integration with Onlinesim. This API will allow you to access two main services of Onlinesim: rent numbers to receive SMS from multiple different senders and receiving SMS from a single specific service. This API is available for registered Onlinesim users only! You need to have Onlinesim profile to be able to access this API. Several methods of authentication are available (see Authorization), but we will use API key authentication in this documentation for reasons of simplicity. Receiving messages from payment services, banks, and other financial institutions is not available on our platform. For more detailed information, including a list of such services, please refer to the Public Offer. List of API requests Requests are specific for each service and allocated in corresponding sections: Profile section These requests are related to the profile or both services provided by Onlinesim getBalance - returns current balance of your Profile; getCountries - returns a list of countries and general information on what services are available. Single-service activations section Allows you to order a number to receive an unlimited number of SMS from a single service within a short time window (15 minutes for most of the services). Please note that you cannot change the service during the operation. To receive SMS from different services, you will need to order new numbers with the appropriate parameters. getNumbersStatus - requests a list of available numbers grouped by country and service; getNumber - orders a number of a chosen country and service to receive SMS; getStatus - returns a list of received SMS activation codes; getFullSms - returns a list of received SMS with full text; setStatus - set a status of the operation (cancel an order, close the operation prematurely, etc). Rent section This service implies that the number will be used to receive SMS from multiple different senders (including SMS from other mobile numbers), except for those that are prohibited. getRentServicesAndCountries - requests a list of countries with available for rent mobile numbers; getRentNumber - orders a number of a chosen country for rent for a certain period; getRentList - returns a list of numbers of your profile with current active rent; getRentStatus - returns a list of received messages; setRentStatus - closes the rental number. Postman collection available here: Postman documentation Each request has its own description, type, endpoint's URL, parameters, request and response schemas. Some responses can have examples of specific errors that might appear. Responses are represented in JSON or TXT format based on method called and results. Common exceptions Common errors for all API methods in TXT format. TEXT_ERROR TEXT_ERROR Description BAD_KEY API key is invalid or missing BAD_ACTION Unhandled exception ## Servers ### `http://api-conserver.onlinesim.io` Onlinesim server --- # Authorization URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/auth/ # Authorization ## api_key API key is a secret key for a simplified authorization in Onlinesim API. How to get an API key: Log in to personal account, go to the Profile and click on API tab. Copy the key from the API Key field and add it to your application. How to use it: All Onlinesim API requests (except for getFreeList) must contain an API key. API key can be specified as a query parameter, for example: https://onlinesim.io/api/getTariffs.php?api_key={api_key} Using an API key provides a simplified way to authorize requests. We recommend using OAuth 2.0 for more secure data handling. For detailed information, please refer to the official OAuth 2.0 documentation. - type: `apiKey` ## BearerAuth The API key can also be used for authorization in the request header using the Authorization: Bearer scheme, for example: Authorization: Bearer {api_key} User-Agent: PostmanRuntime/7.29.2 Accept: */\* Cache-Control: no-cache Postman-Token: 948bc880-8d25-4298-994f-fe6e22ada339 Host: onlinesim.io Accept-Encoding: gzip, deflate, br Connection: keep-alive Cookie: xxxx Using an API key provides a simplified way to authorize requests. We recommend using OAuth 2.0 for more secure data handling. For detailed information, please refer to the official OAuth 2.0 documentation. - type: `http` ## OAuth2 OAuth 2.0 The OAuth 2.0 authorization protocol provides several authorization scenarios, in our case Authorization Code and Implicit Flow types are available. For detailed information, please refer to the official OAuth 2.0 documentation.Authorization URL: https://onlinesim.io/oauth/authorize Token URL: https://onlinesim.io/oauth/token Scopes: sms-scope grants access to manage numbers for the SMS receiving service from Onlinesim; rent-scope grants access to renting phone numbers from Onlinesim; free-scope grants access to using Onlinesim's free numbers. Register the app in our authorization service Open OAuth page Add your app by clicking "Create New Client", then fill the fields below: Name - could be the app name or any other name you and your users will associate with the app; Redirect URL - after user authorization on our server, the client will be redirected with authorization code to this URL. Confidential - (optional), mark the client as Confidential if your application runs on a server and can securely store the Client Secret. Click "Create". New client will appear in the list of applications. Save the Client ID and Secret in a secure location; they will be used by your application for authorization. OAuth 2.0. Authorization code flow Authorize a user and get a token Authorize a client with a GET request to https://onlinesim.io/oauth/authorize with parameters client_id, redirect_uri, response_type, scope, state: Parameter Description Parameter Name Data Type Description client_id STRING Client ID (returned when the app registration process is complete) redirect_uri STRING Redirect destination for the client after a successful authorization, it must match the value of Redirect URL field you've set during app registration process. response_type STRING Use code as a value for Authorization code flow scope STRING Access rights that your app asks from the user. Possible values: sms-scope, rent-scope, free-scope. You can specify multiple values state STRING A random string for CSRF protection (verify it after the redirect) After the request to https://onlinesim.io/oauth/authorize is sent, the user from your app will be redirected to the authorization page to enter the login and password. If successful, authorize your app to work with user data in the Onlinesim service. To do so, he has to click on the Authorize button: At this point, you can check the state parameter, to confirm secure communication with the authorization service If the authorization is successful, the user will be redirected to redirect_uri with the parameter code. Now you can get the access token after making a POST request to https://onlinesim.io/oauth/token: Parameter Description Parameter name Data type Description grant_type STRING Authorization scenario type, use authorization_code when using the Authorization Code flow. client_id STRING Client ID (returned when the app registration process is complete) client_secret STRING Client_secret (returned when the app registration process is complete) redirect_uri STRING Redirect URL for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process. code STRING Authorization code, obtained in the previous step Since client_secret is a private key, it is not recommended to store it in the frontend of the client. For better security, you should store it in the backend of your app. To implement the Authorization Code scenario, you need to pass this code from the frontend to the backend of your service. As a result of a successful request to https://onlinesim.io/oauth/token, you get JSON in response, which contains access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds before the access token is expired and the refresh_token is used to renew the access token when it expires. Authorization and token refreshment For all API requests, add the Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you need to refresh your token or get a new one. { "response": "ERROR_WRONG_KEY" } To refresh the token you must make a POST request to https://onlinesim.io/oauth/token with the parameters grant_type, client_id, client_secret, and refresh_token. For the refresh_token field, use the value obtained in step 4. Parameter Description Parameter name Data type Description grant_type STRING Use refresh_token as a value client_id STRING Client ID (returned when the app registration process is complete) client_secret STRING Client_secret (returned when the app registration process is complete) refresh_token STRING Refresh_token is obtained along with the access_token. It has a much longer lifetime and is used to refresh access_token code STRING Authorization code, obtained in the previous step OAuth 2.0. Implicit flow Authorize a user and get a token Authorize a client with a GET request to the endpoint https://onlinesim.io/oauth/authorize with parameters client_id, redirect_uri, response_type, scope, state: Parameter Description Parameter name Data type Description client_id STRING Client ID (returned when the app registration process is complete) redirect_uri STRING Redirect destination for the client after a successful authorization, it must match the Redirect URL parameter used during app registration process. response_type STRING Use token as a value for Implicit flow scope STRING Access rights that your app asks from the user. Possible values: sms-scope, rent-scope, free-scope. You can specify multiple values state STRING A random string for CSRF protection (verify it after the redirect) After the request to https://onlinesim.io/oauth/authorize is sent, the user will be redirected from your app to the authorization page to enter the login & password and, if successful, authorize your app to work with user data in the Onlinesim service. To do so, he has to click on Authorize button: At this point, you can check the state parameter, to confirm secure communication with the authorization service In case of successful authorization, the user will be redirected to the redirect_uri address with the parameter access_token. This token is required for authorization in Onlinesim API. Authorization of requests to the Onlinesim API Add to all API requests Authorization: Bearer access_token header. If your request results in ERROR_WRONG_KEY, you should get a new token. { "response": "ERROR_WRONG_KEY" } - type: `oauth2` --- # Get information on current user balance URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getbalance/ **Get information on current user balance** Returns the current user balance. You call this method to check the balance of the profile to top it up when needed or to handle WARNING_LOW_BALANCE exceptions. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getBalance | ## Responses ### 200 Successful getBalance response from the server: either returns your profile''s current available balance or throws an exception. --- # Get list of countries with available numbers for order URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getcountries/ **Get list of countries with available numbers for order** This request returns a set of data needed for ordering a number on our service. You can also use it to retrieve a list of all available countries with detailed information of their ID and available services. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getCountries | ## Responses ### 200 Successful getCountries response from the server: either returns a list of available countries with information on available services or throws an exception. --- # Get full SMS text URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getfullsms/ **Get full SMS text** This request returns a full context of received SMS of a given number. You might want to use this request when provided by getStatus information is not enough to comprehence or you need some data that is contaied in the message, for example when SMS contains not only a verification code, but also the link for promocode, date and time of receipt or any other information that you want to use in your application. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getFullSms | | `id` | query | integer | yes | Operation ID (according to getNumber or getStatus responses) | ## Responses ### 200 Successful getFullSms response from the server: either returns full text of a received SMS or throws an exception. --- # Buy virtual number for selected service URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getnumber/ **Buy virtual number for selected service** This request allows you to order a phone number of a specific country to receive SMS from a selected service. This is the main service provided by Onlinesim: you can use virtual numbers to receive verification codes or any other information contained in SMS messages. Please note, that number is issued for 15 minutes (time period depends on the country and service and can differ) and after the operation is closed this number will not be available. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getNumber | | `service` | query | string | yes | Service slug (short service name, required upon ordering a number, according to getNumbersStatus response) | | `country` | query | integer | yes | Country ID (according to getCountries response) | | `phoneException` | query | oneOf | | Array for mask exception (including the country code) For example: with value 911,912123 won''t issue numbers of India, that start with 911* and 912123* | ## Responses ### 200 Successful getNumber response from the server: either returns an operation ID and issued number for SMS receiving or throws an exception. --- # Get information on the number of available numbers by services URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getnumbersstatus/ **Get information on the number of available numbers by services** This request returns a list of available numbers by country and service. You might want to use it to check if the numbers of desired country are available for order and if so, how many. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getNumbersStatus | | `country` | query | integer | | International dialing code of the country (Е.164 standard, without "+" sign) | ## Responses ### 200 Successful getNumbersStatus response from the server: either returns detailed information on available numbers by service or throws an exception. --- # Get list of active rental numbers of the profile URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getrentlist/ **Get list of active rental numbers of the profile** This request returns a list of rental numbers with current rent for your profile, including unactivated numbers, if the activation period has not expired. You might want to use this request to retrieve a relevant information on all the active rental numbers you've ordered. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getRentList | ## Responses ### 200 Successful getRentList response from the server: either returns a list of active rental numbers by country or throws an exception. --- # Rent virtual number for receiving SMS URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getrentnumber/ **Rent virtual number for receiving SMS** This request allows you to order a phone number for rent. You might want to use this service when you need to receive SMS from multiple different sources (websites, applications, other mobile numbers) or when need to receive SMS from a single one on the same number, but over a longer time (for example over 7 days). Phone number should be activated by receiving SMS within 20 minutes after the order, otherwise the operation will be closed and refunded automatically.Please note that some services are prohibited for use (and SMS from these services are not available), you can find the list of such services on the front page or in Public offer. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getRentNumber | | `country` | query | integer | yes | Country ID (according to getRentServicesAndCountries response) | | `time` | query | integer | | Desired rental period in hours, which will be converted into days with a rounding-up upon order (e.g. 2h - 1 day, 25h - 2 days) | ## Responses ### 200 Successful getRentNumber response from the server: either issues a number for rent with specified parameters or throws an exception. --- # Get list of countries and rent details for virtual number renting URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getrentservicesandcountries/ **Get list of countries and rent details for virtual number renting** This request returns a list of countries available for rent with rent details. You might want to use it to check if the numbers of desired country are available for rent and if so, how many. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getRentServicesAndCountries | | `country` | query | integer | | Country ID (according to getCountries) | ## Responses ### 200 Successful getRentServicesAndCountries response from the server: either returns detailed information on available numbers for rent by country or throws an exception. --- # Get rent operation status URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getrentstatus/ **Get rent operation status** This request returns a list of SMS received on a rental virtual number. You might want to use this request to check the received message on a specified rental number to process this data in your application. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getRentStatus | | `id` | query | integer | yes | Operation ID (assigned upon order, according to getRentList) | ## Responses ### 200 Successful getRentStatus response from the server: either returns a list of received messages by the specified virtual rental number or throws an exception. --- # Get short code from received SMS URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-getstatus/ **Get short code from received SMS** This request returns a short code contained in SMS received by the specified number (to see the full text of the message, check getFullSms request). This request can be used when you're sure that no other information in message is worth to store or use in future, other than a code. Otherwise consider using getFullSms request. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case getStatus | | `id` | query | integer | yes | Operation ID (according to getNumber or getStatus responses) | ## Responses ### 200 Successful getStatus response from the server: either returns short code from a received SMS or throws an exception. --- # Change rent operation status URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-setrentstatus/ **Change rent operation status** This request closes the rent on a specified phone number. Closing the operation is irreversible process: once you close the operation, you won't be able to use or restore access to this rental number.You might want to use this request when you need to close the operation explicitly and do not plan to use the number further, for example when the data you wanted has been retrieved. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case setRentStatus | | `id` | query | integer | yes | Operation ID (assigned upon order, according to getRentList) | | `status` | query | number | yes | Operation status code (constant value, can only accept 2, else throws an error) | ## Responses ### 200 Successful setRentStatus response from the server: either changes the rental operation status or throws an exception. --- # Change operation status URL: https://onlinesim.io/openapi_docs/Alternative-API-UN/Alternative-API-UN-get-stubs-handler_api-php-action-setstatus/ **Change operation status** This request allows you to change the status of the operation according to its results (cancel operation, get next SMS code, close operation). You might want to use this request when you want explicitly change the status of the operation, for example when your application needs to retrieve information from the second message received by this number. Closing the operation is irreversible process: once you close the operation, you won't be able to use or restore access to this number. ## Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `action` | query | string | yes | Method name, in this case setStatus | | `id` | query | integer | yes | Operation ID (according to getNumber or getStatus responses) | | `status` | query | integer | yes | Status code: 1 - inform when the phone number is ready (SMS was sent to this number), 3 - request digital code from the next message, 6 - close the operation | ## Responses ### 200 Successful setStatus response from the server: either switches operation status to the specified or throws an exception. --- # Onlinesim MCP URL: https://onlinesim.io/openapi_docs/agent/ MCP Onlinesim MCP Local CLI + Streamable HTTP MCP server for SMS numbers — install once, connect Cursor, Claude, VS Code, or Codex. One-line install (macOS, Linux, Windows) 14 tools for Quick SMS and rentals Works with Cursor, Claude Code, VS Code, Codex Open MCP docs Also available Beyond REST APIs — run Onlinesim tools from your AI client. Onlinesim MCP Local MCP CLI for Onlinesim SMS numbers — Streamable HTTP for AI clients. Run a small local server, connect your AI client, and order receive-only numbers without leaving the chat. What it is Onlinesim MCP is a local CLI that exposes Onlinesim SMS APIs as Model Context Protocol tools over Streamable HTTP. Public binaries and install scripts live on GitHub (on-org/onlinesim-mcp). Authenticate with your Onlinesim API key via onlinesim login or ONLINESIM_APIKEY — never pass the key in tool arguments. One binary: CLI helpers and the MCP HTTP server. Quick SMS verification and long-term rental tools. Works with Cursor, Claude Code, VS Code, and Codex. Project or global client install via onlinesim mcp install. Default endpoint: How it fits together Your MCP client talks to the local onlinesim mcp process. That process calls the Onlinesim HTTP API with your stored key. The MCP endpoint has no auth of its own — keep the default loopback bind, and leave onlinesim mcp running while the client is connected. Where to go next Agent skill (npx skills add) or curl/irm CLI install. Login, start MCP, and wire a project. Cursor, Claude, VS Code, Codex — install and manual JSON. Full tool list for Quick SMS and rentals. MCP Streamable HTTP onlinesim mcp 8787 --- # Install URL: https://onlinesim.io/openapi_docs/agent/install/ Install Install via Agent Skill or one-line scripts from GitHub Releases. Prefer the skill for AI agents (auto binary + MCP + login). Curl/irm remain for a direct CLI install without an agent. Agent skill (recommended) Adds the onlinesim-mcp skill so the agent can install the binary, start MCP, and ask for an API key when needed: New agent chat: the skill runs ensure-ready first (binary → MCP up → auth). If there is no key, the agent asks you to paste it and runs onlinesim login --apikey … Always-on every chat: copy skills/onlinesim-mcp/rules/onlinesim-mcp.mdc into the project .cursor/rules/, or paste it into Cursor → Settings → Rules → User Rules. Direct binary macOS & Linux Installs into ~/.local/bin by default (override with ONLINESIM_INSTALL_DIR). No agent required. Windows PowerShell Installs into %LOCALAPPDATA%\onlinesim\bin and updates your user PATH. No agent required. Verify Open a new terminal so PATH updates apply, then run: If the command is not found, ensure the install directory is on your PATH, or open a new shell. All releases Update After install, upgrade the CLI by running the same installer again — it replaces the binary with the latest GitHub Release. On startup, onlinesim may print a hint when a newer release exists (checked about once per day). Restart MCP after updating so clients use the new binary. macOS / Linux: Windows PowerShell: If you installed the Agent Skill, refresh it separately: Disable the update hint with a flag or env: install.sh install.ps1 curl irm PATH npx skills add npx skills update on-org/onlinesim-mcp ensure-ready SKILL.md ONLINESIM_NO_UPDATE --no-update-check --- # Quick start URL: https://onlinesim.io/openapi_docs/agent/quickstart/ Quick start Login, start MCP, connect a client. Four steps from a fresh install to tools available in your AI client. Save your API key Run onlinesim login (or set ONLINESIM_APIKEY). Get the key from the Onlinesim cabinet. Check balance onlinesim balance confirms the key works before you spend. Start the MCP server Keep onlinesim mcp running while the client is connected, or use onlinesim mcp autostart install for login/reboot background start. Connect a client Run onlinesim mcp install in the project, or add the HTTP endpoint JSON manually. Commands Add to a project Recommended — write the endpoint into IDE config (project by default): Or create the file yourself. Same JSON for Cursor and Claude Code (.mcp.json): root key is servers, not mcpServers More clients, scopes, and flags — see Connect a client. onlinesim login onlinesim balance onlinesim mcp onlinesim mcp install onlinesim mcp autostart .cursor/mcp.json --- # Connect an MCP client URL: https://onlinesim.io/openapi_docs/agent/clients/ Connect an MCP client Wire Cursor, Claude, VS Code, or Codex to the local HTTP endpoint. Same endpoint for all clients. JSON shape differs slightly for VS Code. Keep onlinesim mcp running while the client is connected. Auto-wire (recommended) Write the HTTP endpoint into IDE config files. Does not start the MCP server. Flags: --dir , --url , --force (overwrite existing onlinesim entry). Prefer the Agent Skill in Cursor (installs binary, starts MCP, and handles login when needed): Manual setup by client Put this JSON in a Cursor mcp.json file: global (all projects) this project Claude Code CLI scopes: Or use a project file (same JSON as Cursor): Project file .vscode/mcp.json — key is servers (not mcpServers): Or set url under [mcp_servers.onlinesim] in ~/.codex/config.toml. Local HTTP needs a bridge: Cursor Claude Code VS Code Codex Claude Desktop mcp.json mcp-remote onlinesim mcp install --client --global --project .cursor/mcp.json .mcp.json .vscode/mcp.json --- # MCP tools URL: https://onlinesim.io/openapi_docs/agent/tools/ MCP tools All tools exposed by onlinesim mcp. Use catalog tools to resolve ids. Never invent serviceId or countryId. Ids in replies appear in [brackets]: serviceId (slug), countryId/rentalId (numeric), Order/Receipt ID (tzid). Bulk tools accept 1–20 ids, or omit / [] for all active. spends Do not mix Quick SMS tools with long-term rental tools in one flow. Catalog & balance Quick SMS Long-term rental Account balance before spending. Search Quick SMS services → serviceId. Countries, price, and stock for a service → countryId. Cheapest countries by price for a service. All unique Quick SMS countries (countryId + dial + name). No serviceId. Buy a number for verification (spends balance). Wait for the SMS code (prefer this over tight polling). Poll inbox for one or more order ids. Close Quick SMS order(s). List active Quick SMS orders (and rentals) after crashes. Catalog of long-term rental offers. Rent a number (spends balance). Read rental inbox messages. Extend a rental (spends balance). Cancel rental(s). get_account_balance search_sms_services get_sms_service_countries find_cheapest_sms_countries list_sms_countries order_sms_verification wait_sms_verification check_sms_verification cancel_sms_verification list_sms_orders list_sms_rentals rent_sms_number get_sms_rental_messages extend_sms_rental cancel_sms_rental --- # Quick SMS workflow URL: https://onlinesim.io/openapi_docs/agent/workflow-sms/ Quick SMS workflow Order a number, receive a code, close the order. Agent playbook for one-shot verification SMS. Balance get_account_balance Find a service search_sms_services → serviceId Pick a country find_cheapest_sms_countries or get_sms_service_countries → countryId (full directory: list_sms_countries) Order order_sms_verification — then enter the phone on the target site and request SMS Wait for code Prefer wait_sms_verification; else poll check_sms_verification every 15–30s Cancel cancel_sms_verification when done Statuses waiting for SMS code received Early cancel (~2 minutes) may return NO_COMPLETE_TZID. The tool response includes phone/service/country and guard_secs — wait, then retry. TZ_NUM_WAIT TZ_NUM_ANSWER NO_COMPLETE_TZID --- # Long-term rental URL: https://onlinesim.io/openapi_docs/agent/workflow-rent/ Long-term rental Rent a number for ongoing SMS, extend or cancel later. Separate toolset from Quick SMS verification. Browse offers list_sms_rentals Rent rent_sms_number Read messages get_sms_rental_messages Extend or cancel extend_sms_rental / cancel_sms_rental CLI mirror onlinesim rent --- # CLI & configuration URL: https://onlinesim.io/openapi_docs/agent/cli-config/ CLI & configuration Terminal commands, config file, and environment variables. Everything MCP can do is also available as onlinesim subcommands. Commands save API key remove stored key check config and connectivity print balance start Streamable HTTP MCP server login/reboot autostart (enable, status, start, uninstall) Quick SMS (search, order, check, cancel) long-term rentals show / set / path Auth & config Key is stored locally after login. Env overrides the file. Long-lived MCP reloads key/URL on each tool call. API key override skip GitHub update check Config lives under the OS app config dir for project io.onlinesim.onlinesim (e.g. ~/.config/onlinesim/config.json on Linux). Useful flags --allow-remote binds off loopback. MCP has no auth — restrict network access. Autostart Enable login/reboot autostart with auto-launcher — same model on Windows (Run key), macOS (LaunchAgent), and Linux (systemd --user). Default is user-level so your config and API key keep working. Use --system for machine-wide autostart (needs sudo / Administrator). System tray While onlinesim mcp runs, a tray icon shows balance, active numbers/SMS (click to copy), desktop alerts on new SMS (code auto-copied), client install, Start at login, Notify on SMS, and Quit. Use --no-tray for headless/SSH. ONLINESIM_APIKEY ONLINESIM_NO_UPDATE --allow-remote --no-tray --format json onlinesim mcp autostart auto-launcher LaunchAgent systemd tray