Sign in

v1

latestOpenAPI 3.0.32026-07-2618073.2 KB
Purchases

Create new purchase

Creates a new purchase for specified country. Deducts balance immediately and returns purchase with PENDING status.

Purchase Creation Process

  1. Validates country availability and user balance.
  2. Reserves account from provider.
  3. Atomically deducts balance and creates purchase record.
  4. Returns purchase in PENDING status.

Next steps. Call POST /purchases/:id/request-code to retrieve login credentials.

Country availability. Accounts may become unavailable between checking /accounts and creating purchase. Always handle availability errors gracefully.

post/v1/purchases/

Request body

country_codestring required

ISO 3166-1 alpha-2 country code.

Example request

{
  "country_code": "US"
}

Response

Response for status 200

idinteger required

Unique purchase identifier.

country_codestring required

ISO 3166-1 alpha-2 country code.

phone_numberstring nullable required

E.164 International Format. Phone number with country code prefix (e.g., +12025550123 for US, +79991234567 for Russia).

Usage. This is your Telegram account login. Use it with verification.code and verification.password to access the account.

status'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND' required

Purchase Status Lifecycle. PENDING (initial) → SUCCESS (after code request) or ERROR (provider failure). Any status can transition to REFUND via admin action.

Important. Status is immutable once set to SUCCESS, ERROR, or REFUND.

Filter options

  • PENDING - code not requested.
  • SUCCESS - code ready.
  • ERROR - provider failed.
  • REFUND - money returned.
purchase_type'SINGLE' | 'BULK' | 'ADMIN' required

Type of purchase: SINGLE (regular), BULK (batch purchase), ADMIN (admin deduction)

created_atstring required

Purchase creation time in ISO 8601 format (UTC).

Example response

{
  "id": 12345,
  "country_code": "US",
  "display_name": {
    "ru": "США",
    "en": "United States"
  },
  "phone_number": "+12025550123",
  "price": {
    "amount": "1.50",
    "currency_code": "USD"
  },
  "status": "SUCCESS",
  "purchase_type": "SINGLE",
  "verification": {
    "code": "12345",
    "password": "secret123",
    "received_at": "2024-11-19T07:52:00.000Z"
  },
  "created_at": "2024-11-19T07:50:00.000Z"
}