---
title: "Build a prospect list from results"
method: POST
path: "/verification/batches/{id}/create-list"
tags: ["Verification"]
---

# Build a prospect list from results

`POST /verification/batches/{id}/create-list`

## Request

- Base URL: `https://warmysender.com/api/v1`
- URL: `https://warmysender.com/api/v1/verification/batches/{id}/create-list`
- Auth: HTTP bearer

Builds a reusable prospect list from a finished run. By default it keeps two kinds of address: ones whose mailbox was confirmed, and ones on a mail server that accepts every address. Pass keep=valid for confirmed-only, or keep=risky for catch-all only. The default mix is on purpose — many catch-all addresses still deliver — and the response reports the split so you can decide how to send.

Required scope: `verification:write`.

`keep` omitted is the same as `campaign_ready` (confirmed plus catch-all). `keep=valid` builds a separate confirmed-only list so it cannot collide with the default list.

`confirmed_count` is the mailboxes confirmed to exist. `unconfirmable_count` is the ones on a mail server that accepts every address — send to those gradually, with warmup running.

`address_count` is how many contacts ended up in the list after duplicates were collapsed, so it can differ slightly from the two counts added together.

The default list is named after your original run with "- Verified" on the end. Confirmed-only lists add "confirmed only". That is a label, not a promise about every address in it — read the two counts above for what is actually confirmed.

Calling it twice with the same keep returns the same list rather than creating a duplicate.

Costs nothing — the addresses were already checked when the run happened.

If the run produced nothing usable, the response is 200 with `created: false` rather than an error.

## Path parameters

- `id` string, required

## Request body

- object
  - `keep` 'campaign_ready' | 'valid' | 'risky': Who to put in the list. campaign_ready (default) = confirmed plus catch-all. valid = confirmed only. risky = catch-all only.

## Response `201`

Success

## Other responses

- `400`: `invalid_keep` — keep was not campaign_ready, valid, or risky.
- `401`: `unauthorized` — Missing or invalid API key.
- `403`: `verifier_access_required` — This account is on hold, so its verification data cannot be read.; `insufficient_scope` — The API key lacks the scope this endpoint requires.
- `404`: `not_found` — No run with that id in this workspace.
- `409`: `batch_not_finished` — The run is still going, or it did not finish successfully.
- `429`: `rate_limited` — Too many requests — slow down and retry after the Retry-After delay.
- `503`: `verifier_access_required` — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.

---

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