How to add plans with async processing via API

Some plans require additional processing time during line creation and cannot be created using the standard synchronous API flow. This applies to Unlimited plans as well as Travel Data / Calls / SMS bundles.

This article explains how to identify async bundles and correctly create lines for them.

Why some plans require async processing

Certain bundle types require additional backend processing during line creation. Because of this, they must be created using an asynchronous endpoint rather than the standard /line/create.

To support this, the API includes:

• A way to identify bundles that require async processing
• An asynchronous line creation endpoint
• A request status endpoint to retrieve the final result

Step 1: Get async-eligible bundles from the bundles list

To retrieve bundles that require async processing, call the bundles endpoint with the with_async flag enabled.

Endpoint

GET /bundles

Query parameter

with_async=true

Details:

• Type: boolean
• Default: false
• When set to true, the response includes bundles that require async processing (Unlimited plans, Travel Data, Travel Calls, Travel SMS)
• Any bundle returned with this flag must be created via /line/create_async

Step 2: Create a line (Async)

Async bundles must be created using the asynchronous endpoint.

Endpoint

POST /line/create_async

Parameters
This endpoint uses the same parameters as /line/create:

• bundle_id
• refill_mb
• refill_days
• filters
• count
• add_in_inventory

Important limitation: Currently, only 1 line per request is supported (count must be 1)

Response:

• The API immediately returns a request_id
• Line creation continues in the background

Step 3: Check line creation status

Use the request_id to check the status of the async request.

Endpoint

GET /request/{requestId}

Request statuses

• processing — the line is still being created
• completed — the line is ready

When the status becomes completed, the final result is available in the result field.

Important notes

• The request_id does not expire
• You should poll this endpoint until the status is completed
• The result format is identical to the /line/create response
• Usually, the request is completed within a few seconds. In rare cases, it may take up to 10 minutes. If it takes longer, contact support.

Typical integration flow

1. Call GET /bundles?with_async=true
2. Select a bundle that requires async processing
3. Create the line using POST /line/create_async
4. Save the returned request_id
5. Poll GET /request/{requestId}
6. When status is completed, read the final result

Choosing the correct line creation endpoint

Use /line/create for:

• Lifetime plan bundles
• Immediate response required
• Creating up to 1000 lines per request

Use /line/create_async for:

• Unlimited plan bundles
• Travel Data / Calls / SMS bundles
• Any other bundle marked as async
• Creating 1 line per request

If you attempt to create an async bundle using /line/create, the API will return an error instructing you to use /line/create_async.

Additional Information

All endpoints, parameters, and response examples are available in the updated API documentation.