POST /dip_batches

Check a file of up to 20,000 numbers in the background.

The whole file is charged before it starts from your prepaid balance in the currency the request names (else your account's own), at the GET /dips/products prices converted at today's rate: 402 insufficient_balance when it does not cover it. A batch that does not start is refunded in full, and any numbers the service did not accept are refunded. Needs an Idempotency-Key; one key can never pay twice. Follow it with GET /dip_batches/{id}, and read the answers with GET /dip_batches/{id}/results. A locked account gets 423 account_locked.

Fields

Example

curl -X POST "https://api.voicepro.plus/v3/dip_batches" \
  -H "Authorization: Bearer vpkey_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["+447700900001","+447700900002"],"products":["nrv"],"name":"October list"}'

{
  "object": "dip_batch",
  "id": "dipb_8KQ2M7",
  "name": "October list",
  "total": 2,
  "done": 0,
  "products": [
    "nrv"
  ],
  "state": "running",
  "created_at": "2026-10-26T09:00:00Z",
  "finished_at": null,
  "charge": {
    "amount": "0.0004",
    "currency": "USD"
  }
}

Errors

Every error has the same shape: { "error": { "type", "code", "message", "param", "request_id" } }.

More in Dips

• GET/dips/products
• GET/dips
• GET/dips/{id}
• GET/dips/usage
• GET/dip_batches
• GET/dip_batches/{id}
• GET/dip_batches/{id}/results
• GET/risk_ranges
• GET/number_watches
• GET/number_watches/{id}
• GET/number_watches/{id}/events
• POST/dips
• POST/number_watches
• DELETE/number_watches/{id}