Skip to navigation

Batch Management

View as Markdown

When you submit leads, SimZ creates a batch and returns a batchId. Save that value in your CRM or application so you can check progress and control dialing later.

Check batch status

Use GET /api/lead-receive-service/agent/batches/{batchId} to inspect the batch summary and per-entry call progress.

curl "https://api.simz.com/api/lead-receive-service/agent/batches/batch_123" \
-H "X-Company-API-Key: sk_comp_example"

The response includes batch status, accepted and rejected counts, and entry-level call fields such as status, callSid, and callDuration.

Pause a batch

POST /api/lead-receive-service/agent/batches/{batchId}/pause pauses only the accepted backlog that has not yet been dialed.

  • Dispatchable batches (queued or processing) can be paused.
  • Leads already in accepted status and waiting to dial are held.
  • Calls already accepted by core may continue and remain traceable.
curl -X POST "https://api.simz.com/api/lead-receive-service/agent/batches/batch_123/pause" \
-H "X-Company-API-Key: sk_comp_example"

Resume a batch

POST /api/lead-receive-service/agent/batches/{batchId}/resume resumes a paused batch that still has accepted backlog.

  • Only batches in paused status can be resumed.
  • If nothing has been dialed yet, the batch returns to queued.
  • If dialing already started, the batch returns to processing.

Cancel a batch

POST /api/lead-receive-service/agent/batches/{batchId}/cancel cancels accepted leads that have not yet been dialed.

  • Accepted backlog entries are cancelled and will not be dialed.
  • The batch is marked cancelled even when no accepted backlog remains (cancelledEntries may be 0).
  • Calls already accepted by core may still complete and remain traceable.
  • You can optionally pass a reason in the request body. SimZ stores it on cancelled entries and defaults to cancelled_by_client when omitted.
curl -X POST "https://api.simz.com/api/lead-receive-service/agent/batches/batch_123/cancel" \
-H "Content-Type: application/json" \
-H "X-Company-API-Key: sk_comp_example" \
-d '{"reason":"cancelled_by_client"}'

Pause all or cancel all

Use company-wide controls when you need to stop multiple active batches at once.

EndpointBehavior
POST /api/lead-receive-service/agent/batches/pause-allPauses every dispatchable batch for your company that still has accepted backlog.
POST /api/lead-receive-service/agent/batches/cancel-allCancels accepted backlog across every controllable batch for your company.

Both endpoints accept an optional JSON body:

{
"agentId": "agent_123",
"reason": "cancelled_by_client"
}
  • agentId scopes the operation to one agent. Omit it to affect all matching batches for your company.
  • reason is optional, only applies to cancel-all, and defaults to cancelled_by_client when omitted.

Skip behavior: neither endpoint fails the whole request when individual batches do not qualify.

  • pause-all skips batches that are not dispatchable (queued or processing), already paused, or have no accepted backlog.
  • cancel-all considers controllable batches (queued, processing, or paused) and skips any batch where no accepted entries were cancelled.

Common errors

CodeHTTP statusMeaning
BATCH_NOT_FOUND404Batch does not exist.
FORBIDDEN403Batch belongs to another company.
BATCH_NOT_PAUSABLE409Batch is not in a dispatchable state (queued or processing).
BATCH_NOT_RESUMABLE409Batch is not paused.
BATCH_NOT_CANCELLABLE409Batch is terminal or not in paused, queued, or processing status.
NO_ACCEPTED_BACKLOG409No accepted leads remain waiting to dial. Applies to pause and resume only.

See Errors and Rate Limits for submission errors and retry guidance.