API v3
POST /iot/bulk_jobs
One change for up to 5,000 of the account's IoT SIMs, run in the background.
Name the SIMs by sim_ids (from GET /iot/sims) and/or iccids, 1 to 5,000 in all. Every SIM is checked to be on this account before anything runs: one that is not, a repeat, or more than 5,000 is 400 invalid_parameter and nothing is changed. The answer is 202 with the job; follow it with GET /iot/bulk_jobs/{id}. Each SIM is changed at most once, also if the job is interrupted and resumed; a SIM whose change was interrupted before it was confirmed is reported failed, never sent again. Up to 5,000 SIMs take about 2 minutes. Needs an Idempotency-Key: a retry with the same key and body returns the same job (200); the same key with another body is 409 idempotency_key_reused. A locked account gets 423 account_locked. The iot.bulk_job_done webhook fires when the job finishes.
Addresshttps://api.voicepro.plus/v3/iot/bulk_jobs
Key permissionsims:write
Idempotency-KeyRequired. A retry with the same key and body replays the first answer, so it never acts twice.
Fields
| Name | In | Type | |
|---|---|---|---|
| Idempotency-Key * | header | string | Required on every POST. 8-128 characters: letters, digits, dot, colon, hyphen or underscore. The first response is stored for 24 hours and replayed for any retry with the same key and the same body. Two rules, set per operation by x-charged. Charged or partner-side operations (x-charged true: dips, dip batches, orders, SMS, porting) never re-run while a first attempt is unfinished: a retry answers 409 idempotency_key_in_use (outcome pending) until the first outcome is stored, and the key is also given to the partner as its own reference, so one key never causes more than one order, charge or message, even across failures. A charged operation that fails part-way stores that failure as the key's answer; only a refusal before anything ran (400, 401, 402, 403, 404, 429) frees the key for a retry. Operations with no outside effect (x-charged false) hold their key for at most 2 minutes; after that a retry runs fresh. Missing: 400 missing_parameter (param Idempotency-Key). Malformed: 400 invalid_parameter. Same key, different body: 409 idempotency_key_reused. First request still running: 409 idempotency_key_in_use. |
| sim_ids | body | array of string | |
| iccids | body | array of string | |
| change * | body | object |
* required
Example
curl -X POST "https://api.voicepro.plus/v3/iot/bulk_jobs" \
-H "Authorization: Bearer vpkey_YOUR_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"sim_ids":["sim_7k2mqqxw4hd3nvbc5rtfz6ya","sim_b4nq7zx2kw5rm3dh6ctvfypa"],"change":{"data_limit":{"total_bytes":1073741824,"period":"monthly","alert_bytes":858993459}}}'Response
{
"object": "iot_bulk_job",
"id": "bulk_3f9a1c7e5b2d4a6c8e0f1a2b",
"status": "done",
"change": {
"data_limit": {
"total_bytes": 1073741824,
"period": "monthly",
"alert_bytes": 858993459
}
},
"total": 2,
"processed": 2,
"succeeded": 2,
"failed": 0,
"created_at": "2026-10-28T09:10:00Z",
"finished_at": "2026-10-28T09:10:04Z"
}Errors
Every error has the same shape: { "error": { "type", "code", "message", "param", "request_id" } }.
missing_api_key401: No Authorization header, or not a Bearer key.
invalid_api_key401: The key is not recognised.
api_key_revoked401: The key was revoked in the portal.
api_key_expired401: The key passed the expiry date set on it.
missing_scope403: The key lacks the scope this endpoint needs; param names the scope.
ip_not_allowed403: The key has an IP allowlist and this request came from elsewhere.
account_not_active403: The workspace is suspended or closed.
invalid_parameter400: A query parameter or body field has a bad value; param names it.
missing_parameter400: A required parameter or field is missing; param names it.
unknown_parameter400: A parameter or field that this endpoint does not accept; param names it.
invalid_json400: The body is not valid JSON.
invalid_cursor400: The cursor is malformed, expired or from a different list.
invalid_time_range400: from or to is not an ISO 8601 date-time, or to is not after from.
range_too_long400: The time range is longer than this endpoint allows (stated in the endpoint).
body_too_large413: The body is over 1 MiB.
route_not_found404: No such path in v3.
resource_not_found404: No object with that id on this account.
service_not_enabled404: The account does not have this service (voice trunk, IoT, numbers); param names it.
idempotency_key_reused409: This Idempotency-Key was used within 24 hours with a different request.
idempotency_key_in_use409: A request with this Idempotency-Key is still running, or its outcome at a partner is not yet known (message: outcome pending); retry shortly with the same key. If a charged request never finished, the message says so: check your balance and orders before sending it again with a new key.
state_conflict409: The object is not in a state that allows this action (for example resuming an active SIM).
rate_limited429: Too many requests for this key or for the whole account (the message says which); wait Retry-After seconds.
upstream_unavailable503: A network partner or data service behind this endpoint is unavailable.
network_action_unavailable503: This network action is not switched on for the account yet (for example SIM suspend).
internal_error500: Our fault. Quote the request_id to support.
service_unavailable503: API v3 itself is briefly unavailable (for example a configuration problem on our side); the rest of VoicePro is unaffected. Retry later.
account_locked423: The account is locked pending a Trust & Safety review; writes, including charged actions, are refused until it is cleared. Reads still work.
Webhook events
This call can cause iot.bulk_job_done. See webhooks.