Rent

Rent a number for days and receive every SMS sent to it — client.Rent.

A rent keeps a number for days days. Its SMS come in RentItem.Messages, newest first. Every method also takes a CancellationToken cancellationToken = default as its last parameter.

GetAsync reserves the price (it shows in Zbalance): the rent starts with Status 0 and Checked false and waits up to 20 minutes for its first SMS. The first SMS that is not a notify notice confirms it (Status 1) and charges the price; without one the rent closes and the reservation is released. Some countries (Confirm in TariffsAsync, e.g. US numbers) are confirmed and charged at once.

RentItem: Tzid, Status, Number (without the country code), Country, Sum, Days, Hours, Time, TimeSeconds?, Extension, Extend, Messages, StartTime, StopTime, DayExtend?, … — Sum is the cost in USD incl. extensions (a decimal; the server sends a number, or a decimal string in StateAsync), Time minutes left, TimeSeconds seconds left, Extension 0 not extendable / 1 extendable / 2 auto-extension, Extend maps days to the extension price (empty when not extendable), Messages is a list of RentSms: Id, Service, Text, Code, CreatedAt — Code is "" when no code was found and "0" for a notify SMS (a prohibited sender; the server sends the integer 0, the SDK normalises it to a string).

GetAsync

Rent a number. The price is reserved; the first SMS charges it.

Task<RentItem> GetAsync(int country = 7, int days = 1, bool extension = true)
ParamTypeDefaultDescription
countryint7Country code.
daysint1One of the tariff's Days keys.
extensionbooltruefalse makes the rent non-extendable for good.
var rent = await client.Rent.GetAsync(7, 7);
Console.WriteLine($"{rent.Tzid} {rent.Number} {rent.Sum}");

Errors: NoNumberException; ApiException UNDEFINED_DAYS, UNDEFINED_COUNTRY, WARNING_LOW_BALANCE, INTERVAL_CONCURRENT_REQUESTS_ERROR, TRY_AGAIN_LATER.

StateAsync

All rents of the account.

Task<IReadOnlyList<RentItem>> StateAsync()
foreach (var rent in await client.Rent.StateAsync())
{
    Console.WriteLine($"{rent.Number} {rent.Messages.FirstOrDefault()?.Code}");
}

StateOneAsync

One rent.

Task<RentItem> StateOneAsync(long tzid)
var messages = (await client.Rent.StateOneAsync(tzid)).Messages;

Errors: ApiException ERROR_NO_OPERATIONS for an unknown tzid.

ExtendAsync

Extend a rent by days days and charge the balance at once. Only confirmed rents (Status 1 or 4) created with extension: true.

Task<RentItem> ExtendAsync(long tzid, int days = 1)
var rent = await client.Rent.ExtendAsync(tzid, 3);
Console.WriteLine(rent.StopTime);

Errors: ApiException TRY_AGAIN_LATER (unknown tzid, not confirmed yet or closed, not extendable, unknown period, a repeat within 10 s), WARNING_LOW_BALANCE.

CloseAsync

Return the number before the period ends. A rent that is not confirmed yet (Status 0) and has no SMS can be closed only after 120 s; then, or with only notify SMS, the reservation is released. With a real SMS the rent is confirmed (charged) and closed. A confirmed rent closes without a refund. US numbers cannot be closed early.

Task CloseAsync(long tzid)
await client.Rent.CloseAsync(tzid);

Errors: ApiException ERROR_NO_OPERATIONS, NO_COMPLETE_TZID, NO_CLOSE_RENT_US, TRY_AGAIN_LATER.

TariffsAsync

Rent prices of every country, keyed by country code. No API key needed.

Task<IReadOnlyDictionary<int, RentTariff>> TariffsAsync()

RentTariff: Code, Name, Enabled, New, Position, Extend, Confirm?, Days, Count, ExtCounts? — Days maps rent days to the price in USD, Count to the numbers available.

var tariffs = await client.Rent.TariffsAsync();

TariffsOneAsync

Rent prices of one country.

Task<RentTariff> TariffsOneAsync(int country = 7)
var tariff = await client.Rent.TariffsOneAsync(7);
Console.WriteLine(tariff.Days[7]); // price of 7 days

Errors: ApiException NO_COUNTRY for a country without rent.