OnlineSim.Api

Typed async C# / .NET client for the OnlineSim API — SMS numbers, rent, account and free numbers — with a built-in offline mock for tests.

Install

One package for .NET Framework 4.6.2+, .NET 6/8/9+ and Unity/Mono (targets netstandard2.0 and net8.0). The only dependency is System.Text.Json, and only on netstandard2.0 (it is in-box on .NET 8+).

dotnet add package OnlineSim.Api

Quick start

Check the balance, order a number, wait for the SMS code.

using OnlineSim.Api;

var client = new OnlineSimClient(Environment.GetEnvironmentVariable("ONLINESIM_KEY"));

var balance = await client.User.BalanceAsync();
Console.WriteLine($"available: {balance.Balance - Math.Max(balance.Zbalance, 0)} USD");

var order = await client.Numbers.GetWithNumberAsync("google", 44);
Console.WriteLine($"enter {order.Number} in the app");

// Polls every 5 s for up to 10 min, then closes the operation.
var code = await client.Numbers.WaitCodeAsync(order.Tzid);
Console.WriteLine($"code: {code}");

Every method is async (Task<T>) and takes an optional CancellationToken as its last parameter. The library awaits with ConfigureAwait(false), so it is safe in UI and .NET Framework hosts with a synchronization context. OnlineSimClient is thread-safe: create one and reuse it.

Client options

using OnlineSim.Api;

var client = new OnlineSimClient(new OnlineSimClientOptions
{
    ApiKey = "your-api-key",
    Lang = "en",
    Timeout = TimeSpan.FromSeconds(15),
});
OptionTypeDefaultDescription
ApiKeystring?—Sent as Authorization: Bearer <ApiKey>, never in the URL. Not needed for tariffs and free numbers.
BaseUrlstring?https://onlinesim.host/api/API base; trailing slash optional.
LangstringenLanguage of server texts (lang query parameter).
DevIdstring?—Partner developer id (dev_id), sent only when set.
TimeoutTimeSpan30 sPer-request timeout; Timeout.InfiniteTimeSpan disables it.
TransportITransport?HttpClientTransportTransport: your own HttpClient (proxy, custom TLS, IHttpClientFactory), or a fake in tests.

new OnlineSimClient(apiKey) is a shortcut for the defaults with a key. To use your own HttpClient:

using System.Net;
using System.Net.Http;
using OnlineSim.Api;

var http = new HttpClient(new HttpClientHandler { Proxy = new WebProxy("http://127.0.0.1:8080") });
var client = new OnlineSimClient(new OnlineSimClientOptions
{
    ApiKey = "your-api-key",
    Transport = new HttpClientTransport(http),
});

Sections: client.Numbers, client.Rent, client.User, client.Free. Webhook bodies are parsed by the static Webhook.Parse.

Returned models keep the server's field names in PascalCase (guard_interval_remaining_seconds → GuardIntervalRemainingSeconds). Two things are normalised: money that the server sends as a decimal string (balance, rent sum in Rent.StateAsync) becomes a decimal, and maps that arrive as a PHP list become dictionaries keyed by index (an empty [] becomes an empty dictionary; PaymentHistory.Paylist sent as [a, b] becomes {"0": a, "1": b}). Times reported by the server stay plain numbers in the server's unit (seconds or minutes, documented per field); durations you pass in are TimeSpan.

Error handling

Every exception derives from OnlineSimException.

ClassWhenProperties
ApiExceptionThe API answered with an error code (also a wrong key, HTTP 456, and the rate limit, HTTP 429 TRY_AGAIN_LATER).Code, Message
NoNumberExceptionNO_NUMBER: no number right now. Derives from ApiException.Code, Message
TransportExceptionNetwork error, request timeout, or a body that is not JSON.Status (null without a response), Body (first 500 chars)
WaitTimeoutExceptionWaitCodeAsync got no code within its Timeout.—

Cancelling your own CancellationToken throws the usual OperationCanceledException, not an SDK exception.

using OnlineSim.Api;

try
{
    await client.Numbers.GetAsync("google", 44);
}
catch (NoNumberException)
{
    // try another country or later
}
catch (ApiException e)
{
    Console.Error.WriteLine($"{e.Code}: {e.Message}"); // e.g. WARNING_LOW_BALANCE
}
catch (TransportException e)
{
    Console.Error.WriteLine($"network: {e.Status} {e.Body}");
}

Message is the server's text when it sends one, otherwise a short English description of the code (ErrorMessages.All), otherwise the code itself. Profile validation failures become ApiException with code VALIDATION_ERROR.