Sign in

v1

latestOpenAPI 3.0.32026-07-2618073.2 KB
Purchases

Create new bulk purchase

Creates a new wholesale purchase for the specified country. Immediately debits the balance and returns the purchase with the status “PENDING”.

Wholesale purchase creation process

  1. Checks the availability of the country and the user's balance.
  2. Reserves multiple accounts with the provider.
  3. Atomically debits the balance and creates a bulk purchase record.
  4. Returns the bulk purchase with the status “PENDING”.

Webhook notification. Optionally provide callback_url to receive a webhook when the archive is ready.

Next steps. Call “GET /bulk/:purchaseId” to get the account archive link.

post/v1/purchases/bulk

Request body

country_codestring required

ISO 3166-1 alpha-2 country code.

quantityinteger required

Number of accounts to purchase

callback_urlstring uri

URL to receive webhook notification when bulk archive is ready. POST request will be sent with WebhookBulkReadyPayload.

Retry policy. If your endpoint does not return HTTP 200, webhook will be retried up to 3 times with delays: immediately, after 10 seconds, after 30 seconds. Any non-200 response triggers retry.

Example request

{
  "country_code": "US",
  "quantity": 10,
  "callback_url": "https://example.com/webhooks/code-received"
}

Response

Response for status 200

bulk_purchase_idinteger required

Unique ID of the bulk purchase request

country_codestring required

ISO 3166-1 alpha-2 country code.

quantityinteger required

Number of accounts in this purchase

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

Current status of bulk purchase

created_atstring required

Bulk purchase creation timestamp

updated_atstring required

Last update timestamp

Example response

{
  "bulk_purchase_id": 123,
  "total_price": {
    "amount": "1.50",
    "currency_code": "USD"
  },
  "price_per_account": {
    "amount": "1.50",
    "currency_code": "USD"
  },
  "item": {
    "export_id": "550e8400-e29b-41d4-a716-446655440000",
    "archive_url": "/v1/purchases/bulk/123/download",
    "quantity": 10,
    "created_at": "2024-11-19T08:15:00.000Z"
  }
}