---
title: "Resume a paused file verification job"
method: POST
path: "/v1/jobs/{job_id}/resume"
tags: ["File Processing"]
---

# Resume a paused file verification job

`POST /v1/jobs/{job_id}/resume`

## Request

- Base URL: `https://api.billionverify.com`
- URL: `https://api.billionverify.com/v1/jobs/{job_id}/resume`
- Auth: API key in header `BV-API-KEY`

Resume the current paused attempt of a file verification job.
Resume does not create a new attempt. Repeated resume requests on the same
already-resumed attempt are treated as idempotent no-ops and return the current status.

## Path parameters

- `job_id` string, uuid, required

## Response `200`

Job resumed successfully

- FileVerifyTaskStatusApiResponse
  - `success` boolean
  - `code` string
  - `message` string
  - `data` FileVerifyTaskStatus: Schema mirrors Go struct `service.FileVerifyTaskStatus` (`src/service/file_verify_service.go`). Reflect-based contract test guards that every JSON-serialized Go field appears here.
    - `capacity_wait` object: Remaining addresses await capacity; next_eligible_at is a next-attempt time, not a completion estimate.
      - `waiting_emails` integer
      - `next_eligible_at` string, date-time
      - `waiting_since` string, date-time
    - `task_id` string
    - `status` string: preparing / pending / running / processing / merging / paused / completed / completed_with_warning / failed / cancelled
    - `stage` 'verifying' | 'retry_tail' | 'generating_report', nullable: Execution sub-stage while the job is processing/merging. "retry_tail" means the bulk of emails are done and the remainder are waiting on greylisting retry windows; "generating_report" means verification finished and the result CSV is being built.
    - `pending_retry_emails` integer, nullable: Number of emails still waiting on retry windows. Only present when stage is "retry_tail".
    - `progress` integer: 0-100
    - `email_progress` integer, nullable
    - `chunk_progress` integer, nullable
    - `progress_source` string, nullable: email | chunk
    - `total_emails` integer
    - `processed_emails` integer
    - `valid_emails` integer
    - `invalid_emails` integer
    - `role_emails` integer
    - `catchall_emails` integer
    - `unknown_emails` integer
    - `risky_emails` integer: Rows whose recipient domain is listed by an external blocklist. Counted in the `not_deliverable` bucket. Before 2026-08-04 this counter held internal capacity fallbacks instead, which are now reported under `unknown_emails`.
    - `disposable_emails` integer
    - `disposable_charged_emails` integer: disposable 命中里实际被扣费的 distinct 邮箱数 (SMTP opt-in 路径)。默认 0; 客户带 check_smtp:true 上传 file 且 disposable SMTP 出确定结果时, 这部分被计入 credits_used。详见 docs/disposable/disposable-billing-frontend.md。
    - `credits_used` integer
    - `cache_hit_not_charged` integer, nullable: Number of rows served from user-cache without charging credits (terminal state only).
    - `started_at` string, date-time, nullable
    - `completed_at` string, date-time, nullable
    - `error_message` string, nullable
    - `pause_reason` string, nullable
    - `can_pause` boolean, nullable
    - `can_resume` boolean, nullable
    - `can_restart` boolean, nullable
    - `restart_attempts` integer, nullable
    - `current_attempt` integer, nullable
    - `download_url` string, nullable: API download URL for results CSV (terminal completed state).
    - `direct_download_url` string, nullable: Pre-signed direct-storage URL for results CSV (avoids API hop).
    - `direct_download_expires_at` string, date-time, nullable
    - `result_download_available` boolean: Whether result CSV/detail download is available for the completed task.
    - `result_download_expires_at` string, date-time, nullable: Reserved for a future configured deletion deadline; currently null.
    - `result_download_unavailable_reason` string, nullable: Machine-readable reason when result download is unavailable.
    - `total_chunks` integer, nullable
    - `completed_chunks` integer, nullable
    - `failed_chunks` integer, nullable
    - `runtime_hints` FileVerifyTaskRuntimeHints: Per-job runtime telemetry hints. Canonical Go struct `filejob.JobRuntimeHints` (`src/domain/filejob/read_model.go`); re-exported from `src/service` as `FileVerifyTaskRuntimeHints` via type alias (T3.12 path B).
      - `has_live_execution` boolean, nullable: Whether worker is actively processing this job right now.
      - `inflight_batches` integer, nullable: Number of batches currently in-flight on workers.
      - `last_execution_fact_at` string, date-time, nullable: Last time a worker reported live progress for this job.
    - `deliverability_buckets` DeliverabilityBuckets: Q7 (2026-05-08) + §13 Finding 6 (2026-05-09): pre-aggregated business buckets so clients don't have to parse each row's status/reason. Returned on `/v1/verify/bulk` and `/v1/verify/file/{job_id}`. Math: `strict_deliverable + (usable_with_catchall - strict_deliverable) + not_deliverable + unknown = total_emails`. `anti_verified + transient_failure ≤ unknown` (NOT equal — the residual unknown rows are smtp_blocked / google_dmarc_misalignment / non-anti-domain smtp_unverifiable etc., which retrying does not improve). > **Changed 2026-08-04.** `risky` rows moved from the `unknown` bucket into > `not_deliverable`. They are no longer "we could not tell" — they are "do not > send", the same action as `disposable`, which already lives in that bucket. > The math above is unaffected.
      - `strict_deliverable` integer: valid + role
      - `usable_with_catchall` integer: strict_deliverable + catchall (broader reach if you accept catchall risk)
      - `not_deliverable` integer: invalid + disposable + risky — every row you should drop from the list. `disposable` and `risky` addresses often *do* accept mail; this bucket means "do not send", not "cannot be delivered".
      - `unknown` integer: total unknown rows (super-set of anti_verified + transient_failure). Includes the SMTP capacity fallback (reason=mx_only_verification_semaphore_timeout), which was reported as `risky` before 2026-08-04.
      - `anti_verified` integer: unknown rows whose domain is in the anti-verification consumer list (Apple iCloud / Microsoft consumer / Proton / Tuta) AND reason=smtp_unverifiable. Retrying does NOT help — these providers refuse SMTP probing entirely.
      - `transient_failure` integer: unknown rows whose reason is in the retryable whitelist (smtp_rate_limited / rate_limited / smtp_timeout / dns_timeout / dns_lookup_error / capacity_deferred / context_cancelled / microsoft_api_error / microsoft_api_unavailable / unitedinternet_api_error / unitedinternet_api_unavailable / smtp_rate_check_failed / smtp_rate_wait_failed / internal_verifier_error / dns_resolution_failed / smtp_connection_failed / smtp_egress_unavailable / yahoo_api_rate_limited / smtp_eof_blocked / smtp_greylisted / mimecast_greylist / proofpoint_ad_lookup / policy_temp_fail / google_rate_limit / m365_ip_rep_block / yahoo_api_error / yahoo_api_unavailable / yahoo_api_eof / internal_verifier_error / smtp_550_unclassified / mx_only_verification_semaphore_timeout). Customer can `force_refresh=true` to retry.
    - `unique_emails` integer, nullable: Distinct email count after dedup (used for billing).
    - `total_rows` integer, nullable: Total input rows, excluding header.
  - `error` ErrorInfo
    - `code` string: Detailed error code
    - `message` string: Detailed error message
    - `description` string, nullable: Additional human-readable context (omitempty in Go)
    - `details` unknown

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - invalid or missing API key
- `404`: Resource not found
- `500`: Failed to update task state

---

[API](https://skmtc.dev/billionverify/apis/billionverify-api.md) · [All operations](https://skmtc.dev/billionverify/apis/billionverify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billionverify/apis/billionverify-api/revisions/00762347dc27?raw)