# Skrap.ai API — Introduction

> Verify emails, find work emails, enrich people and companies, search leads and run bulk jobs from your own code. JSON over HTTPS, one API key header, the same engine and credit rules as the web app.

Base URL: `https://api.skrap.ai`. All requests and responses are JSON over HTTPS. Full reference: https://skrap.ai/docs/api.md · Webhooks: https://skrap.ai/docs/webhooks.md · OpenAPI: https://skrap.ai/openapi.json

## Quickstart

1. Create an API key in the app (Settings → API keys & MCP; Professional and Enterprise plans): https://app.skrap.ai
2. Verify your first email:

```bash
curl -X POST https://api.skrap.ai/api/v2/verify-email \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}'
```

## Authentication

- Create an API key in the app under Settings → API keys & MCP. Free accounts get one key at the Free rate limit; paid plans get more keys and higher limits. Keys are shown in full only once, to you; store them like passwords.
- Send it on every request in the x-api-key header. Keys on a team spend the team's shared credits.
- Optional per-key controls: an IP allowlist (exact IPs or IPv4 ranges such as 10.0.0.0/8) and an expiry date. Requests from other IPs get 403 IP_NOT_ALLOWED; expired keys get 401 API_KEY_EXPIRED.
- Without a key, the same endpoints also work through the MCP server (OAuth sign-in) and the app, at your plan's rate limit below.
- Optional scopes per key (verify, find, bulk, search, lists, enrichment, account, webhooks): a key limited to verify cannot spend credits on enrichment. Keys created without scopes, and every key created before scopes existed, have full access. A call outside the key's scopes gets 403 SCOPE_REQUIRED (requiredScope in the body).
- Optional credit cap per key, per UTC day or per calendar month (UTC): a request that would take the key past its cap gets 429 KEY_CREDIT_CAP, with Retry-After set to the seconds until the cap resets. Bulk jobs are checked against the cap when you create them (one credit per row). Set scopes and caps when you create or edit a key in Settings → API keys & MCP; the key list shows what each key spent this period.

## Credits

| Action | Cost |
| --- | --- |
| Verify — Valid or Risky | 1 credit |
| Verify — Invalid or Unknown | Free |
| Find — email found (Valid or Risky) | 1 credit |
| Find — not found (Invalid or Unknown) | Free |
| Bulk verify / bulk find — per row, same rules as single calls | 1 credit per Valid or Risky row |
| Lead & company search | Free |
| Company profile or employee list (MCP enrich_company, list_company_employees) — found | 1 credit (a miss is free) |
| Email of a search result | 1 credit when found |
| Repeat of a verify, find, search-result email, company profile or employee page you already paid for (within 30 days on Free, 90 on Pro, 180 on Enterprise; the answer carries `repeat`) | Free |
| Reverse email lookup — person found | 2 credits |
| Person enrichment — profile found (+ work email) | 1 credit (+1) |
| Company enrichment — company found (+ headcount breakdown) | 1 credit (+1) |
| Company contacts | 1 credit per person |
| Enrichment — nothing found | Free |

## Rate limits

| Plan | Limit |
| --- | --- |
| Professional | 120 requests / minute per key |
| Enterprise | 600 requests / minute per key |
| Pay as you go (no subscription) | 60 requests / minute per key |
| Free | 30 requests / minute per key |
| Custom | Agreed with sales |

- The limit is a fixed 60-second window per key, not a per-second cap: on Professional you may send the minute's 120 requests at once (an average of 2 a second). Single verify and find calls take one email or one person each; send lists to the bulk endpoints (up to 25,000 rows per job).
- Every counted response carries `RateLimit: limit=120, remaining=87, reset=41` and `RateLimit-Policy: 120;w=60` (IETF draft headers). Over the limit you get 429 RATE_LIMITED with `Retry-After` (seconds), and the body names your plan, its limit and the next plan's: `retryAfterSec`, `plan`, `planName`, `limitPerMinute`, `upgrade`.
- Concurrency: up to 50 verify, 10 find and 5 enrichment calls run at once per key; further calls wait in a queue (up to 20 seconds) instead of failing. Only a call still waiting after 20 seconds gets 429 RATE_LIMIT_EXCEEDED with Retry-After: 5.
- Enrichment also has a daily cap of 5,000 credits per account (429 ENRICH_DAILY_LIMIT, resets at midnight UTC).
- The /api/v1 endpoints also share a per-IP ceiling of 5,000 requests per 15 minutes (429 RATE_LIMIT_EXCEEDED).

## Latency

- Verify and find answer in the same call: there is nothing to poll. Most verifications take 0.1–5 seconds and most finds 0.5–10 seconds; an address we checked recently comes back in under 0.2 seconds.
- A slow mail server can hold a call longer. We give it up to about 50 seconds; past that you get `unknown` with `retryable: true` (not charged), and a retry a few minutes later is usually instant. Set your HTTP client timeout to at least 60 seconds.
- Bulk jobs run in the background; how fast depends on the mail servers involved. Poll the job or subscribe to the bulk_job.completed webhook instead of holding a connection open.

## Verification statuses

| Status | Meaning |
| --- | --- |
| `valid` | The mailbox exists and accepts mail (the mail server confirmed it, or a verified record matched). Charged. |
| `risky` | Deliverable but uncertain: a catch-all domain (accepts any address, so the mailbox cannot be proven), a full mailbox, a role or disposable address, a mail server that would not confirm the mailbox, or a find's best guess in the company's email format. `riskReasons` / `catchAll` / `score` say which. Charged. |
| `invalid` | The address or domain cannot receive mail. For a find: nobody by that name could be there (every candidate address was rejected, or the domain has no mail server). Free. |
| `unknown` | No answer: the domain's DNS did not answer, or there was no address to give. Free. When retryable is true, the cause was temporary (try again later). |

Catch-all domains: A catch-all (accept-all) domain says yes to every address, real or not, so no one can prove a mailbox there. Verify answers such an address `risky` with `checks.catchAll: true` and `riskReasons: ["catch_all"]` (score 70). Find answers `risky` with `catchAll: true` and the address in the company's email format (`source: "email_format"`), or the most common format when the company's is not known (`source: "best_guess"`). Both are charged, as deliverable-but-unproven answers.

## Errors

Errors return JSON with a stable `code` and the request ID:

```jsonc
{
  "error": "Insufficient credits",        // human-readable message
  "code": "INSUFFICIENT_CREDITS",         // stable code to branch on (table below)
  "details": { "required": 1, "available": 0, "shortfall": 1 },   // some codes only
  "requestId": "req_mwgp6c0x_k2f9a1"      // same as the X-Request-Id header
}
```

| HTTP | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | A field is missing or malformed; `details` lists each problem (e.g. "email: Invalid email address"). Also a body that is not valid JSON. |
| 401 | `INVALID_API_KEY` | Missing, unknown or revoked key. |
| 401 | `API_KEY_EXPIRED` | The key passed its expiry date. |
| 401 | `AUTHENTICATION_ERROR` | The endpoint needs an app sign-in, not an API key (usage, API keys, app webhooks), or the key's team no longer exists. |
| 402 | `INSUFFICIENT_CREDITS` | Not enough credits (details.required / details.available / details.shortfall on single calls). |
| 402 | `MEMBER_CREDIT_LIMIT` | Your team admin's monthly limit for your account is used up. |
| 402 | `OVERAGE_BLOCKED` | Bulk: pay as you go is paused until the outstanding invoice is paid. |
| 403 | `PLAN_REQUIRED` | The feature needs a higher plan (`requiredPlan` and `feature` in the body). |
| 403 | `IP_NOT_ALLOWED` | The key's IP allowlist does not include the caller. |
| 403 | `ACCOUNT_RESTRICTED` | The account is restricted (e.g. signed up with a temporary email address); `upgradeUrl` in the body. |
| 403 | `DEVICE_CHECK_REQUIRED` | Free sign-up credits: open the app in a browser once to activate them. |
| 404 | `NOT_FOUND` | Unknown route, list, lead, webhook or refinement request id. |
| 404 | `TASK_NOT_FOUND` | Unknown bulk job id, or a job of another account. |
| 409 | `CONFLICT` | Lists: a list with that name, or a lead with that id or email, already exists. |
| 400 | `TASK_CANNOT_CANCEL` | The job is already completed, failed or cancelled. |
| 400 | `TASK_CANNOT_PAUSE` | Only a processing job can be paused; `reason` says why. |
| 400 | `TASK_CANNOT_RESUME` | Only a paused or stalled job can be resumed; `reason` says why. |
| 410 | `RESULTS_EXPIRED` | A bulk job's results were deleted after the retention period. |
| 400 | `UNSUPPORTED_EMAIL` | Reverse lookup: a personal mailbox (Gmail, Outlook …) is not a work address. |
| 403 | `FEATURE_NOT_AVAILABLE` | Enrichment is not enabled on this account yet. |
| 429 | `ENRICH_DAILY_LIMIT` | Your account's daily enrichment credit limit is used up; it resets at midnight UTC. |
| 429 | `FREE_ENRICH_LIMIT` | The Free plan's daily enrichment allowance is used up. |
| 503 | `ENRICH_UNAVAILABLE` | Enrichment is busy or briefly unavailable. Nothing was charged; retry later (Retry-After). |
| 429 | `RATE_LIMITED` | Your plan's per-minute limit for this key; wait for the Retry-After header. |
| 429 | `RATE_LIMIT_EXCEEDED` | Too many requests at once (concurrency queue full for 20 s) or from one IP; back off and retry. |
| 400 | `IDEMPOTENCY_KEY_INVALID` | The Idempotency-Key header is empty, longer than 255 characters or not printable ASCII. |
| 403 | `SCOPE_REQUIRED` | The key's scopes do not include this endpoint (requiredScope in the body). Use a key with that scope. |
| 409 | `IDEMPOTENCY_KEY_REUSED` | This Idempotency-Key was already used on this endpoint with a different request body. Use a new key for a new request. |
| 409 | `IDEMPOTENCY_REQUEST_IN_PROGRESS` | A request with this Idempotency-Key is still running. Retry after Retry-After seconds to get its stored answer. |
| 429 | `KEY_CREDIT_CAP` | The key's own daily or monthly credit cap is reached (details: cap, used, required, period, resetsAt). Retry-After says when it resets. |
| 5xx | `INTERNAL_ERROR` | Our side. Retry with back-off; nothing was charged. |

## API conventions

### Request IDs

Every response carries an `X-Request-Id` header, errors included. Send your own `X-Request-Id` (8–128 characters: letters, digits, `.`, `_`, `:`, `-`) and we echo it back and log it with the call; otherwise Skrap generates one (`req_…`).

Every JSON error body includes the same value as `requestId`. Quote it when you contact support and we can find the exact call. The `requestId` field in find and enrichment answers stays Skrap's own id (it is what you poll a pending find with).

```json
{
  "error": "This API key does not have the enrichment scope",
  "code": "SCOPE_REQUIRED",
  "requiredScope": "enrichment",
  "requestId": "req_mhz3k2a1_9f2c1d"
}
```

### Idempotent retries

Network errors happen. To retry a POST without paying twice or starting a second job, send an `Idempotency-Key` header (1–255 printable ASCII characters; a UUID per logical operation works well).

- Same key and same body within 24 hours: you get the stored answer again (same status and body, plus the header `Idempotent-Replayed: true`). Nothing is charged again and no second job or list is created.
- Same key, different body: 409 IDEMPOTENCY_KEY_REUSED.
- Same key while the first request is still running: 409 IDEMPOTENCY_REQUEST_IN_PROGRESS with Retry-After.
- Only successful (2xx) answers are stored. An error frees the key, so a retry with the same key runs again.
- Keys are scoped to your API key and the endpoint: the same value on two endpoints are two different keys.
- Accepted on POST /api/v2/verify-email, /api/v2/find-email, /api/v2/enrich/*, /api/v2/webhooks, /api/v1/bulk-verify, /api/v1/bulk-find, /api/v1/bulk-verify-upload, /api/v1/bulk-find-upload, /api/v1/lists, /api/v1/lists/{id}/leads.

```bash
curl -X POST https://api.skrap.ai/api/v1/bulk-verify \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Idempotency-Key: 3f6c1e0a-6c1f-4f0e-9a49-2b7d1c0e5a11" \
  -H "Content-Type: application/json" \
  -d '{"emails":["jane@example.com","john@example.org"]}'
```

### Rate-limit headers

Calls counted against your plan's per-key limit carry the remaining budget, so a client can slow down before it is refused.

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed per minute for this key on your plan. |
| `X-RateLimit-Remaining` | Requests left in the current window. |
| `X-RateLimit-Reset` | When the window resets, as Unix epoch seconds. |
| `RateLimit` / `RateLimit-Policy` | The same numbers in the IETF draft format (reset in seconds). |
| `Retry-After` | On 429 (and some 503) answers: seconds to wait before retrying. |

## Sandbox (test addresses)

Build and test your integration without spending credits. Addresses at `sandbox.skrap.ai` are answered from fixed rules: no mail server and no data provider is contacted, nothing is charged, and every answer carries `"sandbox": true`. The calls still show in your usage history with 0 credits.

The sandbox works with any API key, on every endpoint below, and through everything built on the API: the MCP server, the SDKs, Zapier, Make, n8n and the Google Sheets add-on.

```bash
curl -X POST https://api.skrap.ai/api/v2/verify-email \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"risky@sandbox.skrap.ai"}'
```

```json
{
  "email": "risky@sandbox.skrap.ai",
  "status": "risky",
  "retryable": false,
  "score": 70,
  "riskReasons": ["catch_all"],
  "sandbox": true
}
```

### Verify

| Address | Answer |
| --- | --- |
| `valid@sandbox.skrap.ai` | valid |
| `invalid@sandbox.skrap.ai` | invalid |
| `risky@sandbox.skrap.ai (or catchall@)` | risky, riskReasons [catch_all] |
| `role@sandbox.skrap.ai` | risky, riskReasons [role_account] |
| `disposable@sandbox.skrap.ai` | risky, riskReasons [disposable] |
| `unknown@sandbox.skrap.ai` | unknown |
| `retry@sandbox.skrap.ai` | unknown, retryable true |
| `anything-else@sandbox.skrap.ai` | invalid |

### Find

| Input (any firstName) | Answer |
| --- | --- |
| `lastName "Valid", domain sandbox.skrap.ai` | valid: <first>.valid@sandbox.skrap.ai |
| `lastName "Risky"` | risky: <first>.risky@… |
| `lastName "Unknown"` | no email, status unknown, retryable true |
| `any other lastName (e.g. "Invalid")` | no email found: emails [], status invalid |

### Enrichment

| Input | Answer |
| --- | --- |
| `reverse-email valid@sandbox.skrap.ai` | found (any other sandbox address: not found) |
| `company: domain sandbox.skrap.ai or linkedin.com/company/skrap-sandbox` | found |
| `company-contacts: the same company input` | 2 people |
| `person: linkedin.com/in/skrap-sandbox` | found |

### Bulk jobs

Bulk verify and bulk find: rows at the sandbox domain are answered instantly with the same rules and are free (each row carries sandbox: true). A file of only sandbox rows costs nothing, so you can test uploads, polling, downloads and the bulk_job.completed webhook end to end.

```text
email
valid@sandbox.skrap.ai
invalid@sandbox.skrap.ai
risky@sandbox.skrap.ai
role@sandbox.skrap.ai
disposable@sandbox.skrap.ai
unknown@sandbox.skrap.ai
```

```text
first_name,last_name,domain
Ada,Valid,sandbox.skrap.ai
Alan,Risky,sandbox.skrap.ai
Grace,Invalid,sandbox.skrap.ai
```
