Refresh List API

Automate email-list preflight, verification, and report downloads from your own systems. The API uses the same credits, provider checks, and privacy controls as the Refresh List workspace.

Authentication

Create a workspace API key in Workspace and Integrations. Send it as a bearer token with every API request. Keys are shown once and can be revoked at any time.

Authorization: Bearer YOUR_REFRESH_LIST_KEY
Content-Type: application/json

Base URL

https://refreshlist.net/api

Upload and preflight a list

Uploads create a draft and return counts before any credits are used. Email addresses can be supplied as CSV or TXT text.

POST /upload
{ "text": "email\\nhello@example.com", "filename": "list.csv",
  "header": true, "column": 0, "delimiter": "," }

Start verification

Direct uploads for larger files

Send the original UTF-8 CSV as the body, without wrapping it in JSON. This is the same streaming path used by the workspace.

POST /upload?filename=list.csv&column=0&header=true&delimiter=%2C
Content-Type: text/csv

email,name
hello@example.com,Alex

Direct uploads and MCP inline CSV tools support 50 MB with no email-row cap. Format boundaries: 201 columns and one million characters per row. JSON API text uploads remain limited to 5 MB. An oversized or interrupted assessment never starts verification or spends credits.

Approve the combined list

After reviewing the draft, start it from the workspace or API. Starting reserves credits for eligible, unique addresses. Use an idempotency key if your system may retry.

POST /jobs/{jobId}/start
{ "funding": "paid", "idempotencyKey": "your-unique-request-id" }

GET /jobs/{jobId}
GET /jobs/{jobId}/download?type=all
POST /jobs/{jobId}/cancel

Results and limits

Each response is scoped to the authenticated workspace. Current limits are 50 MB with no email-row cap per file. Poll status periodically rather than sending repeated start requests. Duplicate addresses are not charged.

Webhooks

Workspace integrations can send signed events for completed or failed verification. Verify the X-Refresh-List-Signature header using the signing secret shown once when the endpoint is created. Sign the exact string timestamp.payload with HMAC-SHA256 and compare it in constant time.

Errors

Errors return JSON with an error message and an HTTP status. A 401 means the key is missing, expired, or revoked; 429 means you are being rate limited; 4xx validation errors are safe to correct and retry.

Security and support

Never place API keys in browser code, public repositories, URLs, or support tickets. Use HTTPS, keep keys in a server-side secret manager, and revoke any key that may have been exposed. Need help? Contact Refresh List.