# Skrap.ai API reference

Base URL `https://api.skrap.ai`. Authenticate every request with the `x-api-key` header.

## Verify & find

Real-time, one email or one person per call. Both wait for the final answer (nothing to poll); see Latency in the introduction.

### Verify an email

`POST /api/v2/verify-email`

Checks the address against its domain's mail server: syntax, mail servers (MX), disposable domains, role addresses, catch-all and the mailbox itself. Charged 1 credit only when the result is valid or risky; invalid and unknown are free.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | Address to verify. |

Request:

```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"}'
```

Response (200):

```jsonc
{
  "email": "jane@example.com",
  "status": "valid",            // valid | risky | invalid | unknown
  "retryable": false,           // true: unknown for a temporary reason — try later
  "domainInfo": { "domain": "example.com", "hasMxRecords": true },
  "requestId": "req_mwgoo7em_t3hbda",
  "score": 95,                  // 95 valid · 10–70 risky (by risk reason) · 0 invalid · null unknown
  "checks": {
    "syntax": true,
    "mxFound": true,
    "smtp": "accepted",         // accepted | rejected | inconclusive | not_checked
    "catchAll": false,
    "disposable": false,
    "roleAccount": false,
    "freeProvider": false
  },
  "riskReasons": [],            // risky only: catch_all, catch_all_unconfirmed, role_account, disposable
  "didYouMean": null            // typo hint, e.g. "jane@gmail.com" for "jane@gmial.com"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `email` | string | The address checked, trimmed and lower-cased. |
| `status` | string | Deliverability: valid (mailbox confirmed), risky (deliverable but unproven: catch-all, role, disposable, full or unconfirmed), invalid (cannot receive mail), unknown (no answer). One of: `valid`, `risky`, `invalid`, `unknown`. |
| `retryable` | boolean | true only on unknown answers with a temporary cause; retry in a few minutes. |
| `requestId` | string | ID of this call; the same as the X-Request-Id header. |
| `score` | integer \| null | Confidence 0–100 that mail to this address is delivered: 95 valid; risky 70 catch-all, 60 catch-all not confirmed, 50 role account, 10 disposable (the lowest that applies), 65 other risky; 0 invalid; null unknown. |
| `domainInfo` | object | The domain's mail setup, when known (left out on some instant answers from an earlier check). |
| `domainInfo.domain` | string | The address's domain (the company domain for a work address). |
| `domainInfo.hasMxRecords` | boolean | Whether the domain publishes mail servers (MX records). |
| `checks` | object | The individual checks behind the status. |
| `checks.syntax` | boolean | The address is well formed. Always true in a 200 answer (a malformed address is a 400 VALIDATION_ERROR). |
| `checks.mxFound` | boolean \| null | The domain has mail servers; null when its DNS did not answer. |
| `checks.smtp` | string | What the mail server said about the mailbox. not_checked: no mail server to ask, or a disposable / role address answered without asking. One of: `accepted`, `rejected`, `inconclusive`, `not_checked`. |
| `checks.catchAll` | boolean \| null | The domain accepts mail for any address (catch-all); null when not known on this call. |
| `checks.disposable` | boolean | A throwaway-mailbox provider (e.g. mailinator.com). |
| `checks.roleAccount` | boolean | A role address such as info@, support@, sales@. |
| `checks.freeProvider` | boolean | A free mailbox provider such as gmail.com or outlook.com (a personal, not a work, address). |
| `riskReasons` | string[] | Why a risky answer is risky (empty for other statuses). One of: `catch_all`, `catch_all_unconfirmed`, `role_account`, `disposable`. |
| `didYouMean` | string \| null | Typo suggestion for the domain, e.g. jane@gmail.com for jane@gmial.com. |
| `repeat` | object | Only on a free repeat: you already paid for this lookup within your plan's repeat window (30 / 90 / 180 days), so this answer cost nothing. |
| `repeat.free` | boolean | Always true when present. |
| `repeat.firstChargedAt` | string | When you were charged for it (ISO 8601). |

- A catch-all domain: { "status": "risky", "score": 70, "checks": { "smtp": "accepted", "catchAll": true, … }, "riskReasons": ["catch_all"] } (charged).
- No mail server: { "status": "unknown", "score": null, "domainInfo": { "hasMxRecords": false }, "checks": { "mxFound": false, "smtp": "not_checked", … } } (free).

### Find a work email

`POST /api/v2/find-email`

Finds and verifies the work email of a person at a company. Send a name (firstName + lastName, or fullName) and the company: its domain (best results) or its name. 1 credit when an address is found (valid or risky); not found is free.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName / lastName` | string | no | The person's name. A name (these or fullName) is required. |
| `fullName` | string | no | Used when firstName is empty; titles, middle names and credentials are dropped. |
| `domain` | string | no | Company domain, e.g. example.com (a website URL or an email address also works). A domain or a company is required. |
| `company` | string | no | Company name (2–120 characters) when you have no domain; we resolve it to a domain. |
| `location` | string | no | Optional company HQ hint (city or country) that helps match a company name. |
| `linkedinUrl` | string | no | Optional LinkedIn profile URL (linkedin.com/in/…) of the person; helps match our records. |

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v2/find-email" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Doe","domain":"example.com"}'
```

Response (200):

```jsonc
{
  "email": "jane.doe@example.com",   // best address, or null
  "status": "valid",                 // valid | risky | invalid | unknown
  "score": 95,                       // confidence 0–100, null without an address
  "catchAll": false,                 // true: catch-all domain (mailbox cannot be proven)
  "source": "mail_server",           // mail_server | email_format | best_guess | records | web
  "firstName": "Jane",
  "lastName": "Doe",
  "fullName": "Jane Doe",
  "domain": "example.com",
  "companyName": null,               // set when a company name matched exactly
  "emails": [{ "email": "jane.doe@example.com", "status": "valid" }],
  "domainStatus": "valid",           // valid | invalid | unknown
  "companyResolution": { "input": "example.com", "resolvedDomain": "example.com", "companyName": null },
  "retryable": false,
  "pendingRefinement": false,
  "requestId": "req_mwgoos3z_fcw6zx"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `email` | string \| null | The work email found (the best address), or null when none was found. |
| `status` | string | Verification result of the address: valid (the mail server confirmed the mailbox, or a verified record matched), risky (deliverable but unproven, e.g. a catch-all domain). Without an address: invalid (nobody by that name can be there: every candidate was rejected, or the domain takes no mail) or unknown (no answer). One of: `valid`, `risky`, `invalid`, `unknown`. |
| `score` | integer \| null | Confidence 0–100 that the address is the person's working mailbox: 95 valid; risky 70 at a catch-all domain, 40 for a best guess in the most common format, 60 otherwise; null without an address. |
| `catchAll` | boolean \| null | The domain is catch-all (accepts any address, so no mailbox can be proven there); null when not known on this call. |
| `source` | string \| null | Where the address came from: mail_server (the company's mail server accepted it on this call), email_format (the company's known email format, at a catch-all or silent domain), best_guess (the most common format, when the company's is not known), records (our verified records of the person), web (found on a public web page). null without an address. One of: `mail_server`, `email_format`, `best_guess`, `records`, `web`. |
| `firstName` | string \| null | First name searched for (split from fullName when only that was sent). |
| `lastName` | string \| null | Last name searched for. |
| `fullName` | string \| null | Full name as sent, or first + last name. |
| `domain` | string \| null | Company domain searched: the one you sent (normalised: a URL or an email address works too), or the one resolved from `company`. |
| `companyName` | string \| null | The company's name, when the `company` you sent matched one exactly; null otherwise. |
| `emails` | object[] | The address(es) found, best first. Holds at most one address today; kept as a list for compatibility. |
| `emails[].email` | string | Address. |
| `emails[].status` | string | Its verification status. One of: `valid`, `risky`. |
| `domainStatus` | string | The company domain: valid (its mail server answered), invalid (it cannot receive mail), unknown. One of: `valid`, `invalid`, `unknown`. |
| `companyResolution` | object | How the company was matched to a domain. |
| `companyResolution.input` | string | The domain or company name you sent. |
| `companyResolution.resolvedDomain` | string \| null | The domain searched. |
| `companyResolution.companyName` | string \| null | Company name for a confident match, else null. |
| `retryable` | boolean | true only on unknown answers with a temporary cause; retry in a few minutes. |
| `pendingRefinement` | boolean | Always false on /api/v2: the call waits for the final answer. Kept for compatibility. |
| `requestId` | string | ID of this call; the same as the X-Request-Id header. |
| `repeat` | object | Only on a free repeat: you already paid for this lookup within your plan's repeat window (30 / 90 / 180 days), so this answer cost nothing. |
| `repeat.free` | boolean | Always true when present. |
| `repeat.firstChargedAt` | string | When you were charged for it (ISO 8601). |

- Not found: { "email": null, "status": "invalid" or "unknown", "score": null, "source": null, "emails": [], … } with the name and domain echoed. Free.
- A catch-all domain: { "status": "risky", "catchAll": true, "score": 70, "source": "email_format" } — the address in the company's format, unprovable by any mail server (charged).
- A company name we cannot match to a domain: 400 VALIDATION_ERROR "Could not resolve company name to a domain" (free). Send the domain instead.

### Poll a pending find (app endpoint)

`GET /api/v1/find-email/refinement/{requestId}`

For /api/v1/find-email, the app's endpoint, which answers within a few seconds and may return pendingRefinement: true. /api/v2/find-email never needs it: it always returns the final answer.

Request:

```bash
curl "https://api.skrap.ai/api/v1/find-email/refinement/REQUEST_ID" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{ "ready": true, "email": "jane.doe@example.com", "status": "valid", "domainStatus": "valid", "retryable": false }
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `ready` | boolean | false: still checking; poll again in a few seconds. |
| `email` | string \| null | The address, once ready. |
| `status` | string | Its verification status. One of: `valid`, `risky`, `invalid`, `unknown`. |
| `domainStatus` | string | The company domain's status. One of: `valid`, `invalid`, `unknown`. |
| `retryable` | boolean | Unknown for a temporary reason. |

## Enrichment

Turn a work email, a LinkedIn profile or a company domain into a full B2B record. Charged only when something is found; a miss is free. Built for paid plans (the free plan gets a small daily allowance). Each account can spend up to 5,000 credits a day on enrichment; contact us for more.

### Reverse email lookup

`POST /api/v2/enrich/reverse-email`

Who is behind a work email address: name, job title, current company, location, career and LinkedIn profile. Work (company) addresses only; personal mailbox providers such as Gmail are refused. 2 credits when a person is found (3 with includeCompany when the company profile is found).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes | Work email address. |
| `includeCompany` | boolean | no | Also return the full company profile as `companyProfile` (+1 credit when found). |

Request:

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

Response (200):

```jsonc
{
  "found": true,
  "email": "jane.doe@example.com",
  "emailMatchesCurrentJob": true,   // false: an earlier employer's address · null: can't tell
  "person": {
    "fullName": "Jane Doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "headline": "Head of Sales at Example",
    "linkedinUrl": "https://www.linkedin.com/in/jane-doe",
    "location": { "city": "Austin", "region": "TX", "country": "US" },
    "currentJob": {
      "title": "Head of Sales",
      "company": { "name": "Example Inc", "domain": "example.com", "linkedinUrl": "https://www.linkedin.com/company/example" },
      "startDate": "2023-04",
      "endDate": null,
      "current": true
    },
    "experience": [ … ],            // up to 15 jobs, in profile order
    "education": [{ "school": "State University", "degree": "BA", "startYear": 2012, "endYear": 2016 }],
    "skills": ["negotiation", "saas"]
  },
  "company": { "name": "Example Inc", "domain": "example.com", "linkedinUrl": "https://www.linkedin.com/company/example" },
  "creditsCharged": 2,
  "requestId": "req_…"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `found` | boolean | Something was found (and charged); false answers are free. |
| `creditsCharged` | integer | Credits this call cost. |
| `requestId` | string | ID of this call; the same as the X-Request-Id header. |
| `email` | string | The address looked up. |
| `emailMatchesCurrentJob` | boolean | false: the address belongs to a previous employer. |
| `person` | object \| null | The person; null when not found. |
| `person.fullName` | string | Full name. |
| `person.firstName` | string \| null | First name. |
| `person.lastName` | string \| null | Last name. |
| `person.headline` | string \| null | Profile headline. |
| `person.linkedinUrl` | string \| null | LinkedIn profile URL. |
| `person.location` | object | Location: city, region (state), country (ISO 2-letter); each can be null. |
| `person.location.city` | string \| null | City. |
| `person.location.region` | string \| null | Region or state. |
| `person.location.country` | string \| null | ISO 3166-1 alpha-2 country code. |
| `person.currentJob` | object \| null | Current job title and company. |
| `person.currentJob.title` | string \| null | Job title. |
| `person.currentJob.company` | object \| null | Employer. |
| `person.currentJob.company.name` | string \| null | Company name. |
| `person.currentJob.company.domain` | string \| null | Company domain. |
| `person.currentJob.company.linkedinUrl` | string \| null | LinkedIn company page. |
| `person.currentJob.startDate` | string \| null | Start, YYYY-MM. |
| `person.currentJob.endDate` | string \| null | End, YYYY-MM; null while current. |
| `person.currentJob.current` | boolean | Still in this job. |
| `person.experience` | object[] | Up to 15 jobs, in profile order, each like currentJob. |
| `person.education` | object[] | Schools: school, degree, startYear, endYear. |
| `person.skills` | string[] | Skills on the profile. |
| `company` | object \| null | The person's current company (name, domain, LinkedIn page). |
| `company.name` | string \| null | Company name. |
| `company.domain` | string \| null | Company domain. |
| `company.linkedinUrl` | string \| null | LinkedIn company page. |
| `companyProfile` | object \| null | With includeCompany: the full company profile, fields as in Enrich a company. |

- Not found: { "found": false, "email": "…", "person": null, "company": null, "creditsCharged": 0 }.
- Typical uses: qualify inbound sign-ups and form fills, complete CRM contacts that only have an email.

### Enrich a LinkedIn profile

`POST /api/v2/enrich/person`

Profile of a person from their LinkedIn URL, plus the work email at their current employer when we have one on record (an address at a previous employer is never returned). 1 credit when the profile is found, +1 when a work email is returned.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `linkedinUrl` | string | yes | Profile URL, e.g. https://www.linkedin.com/in/jane-doe. |
| `includeEmail` | boolean | no | Look up the work email (default true). |

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v2/enrich/person" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedinUrl":"https://www.linkedin.com/in/jane-doe"}'
```

Response (200):

```jsonc
{
  "found": true,
  "person": { "fullName": "Jane Doe", "currentJob": { "title": "Head of Sales", "company": { "name": "Example Inc", "domain": "example.com", … } }, … },
  "workEmail": { "address": "jane.doe@example.com", "status": "valid" },   // null when none on record
  "creditsCharged": 2,
  "requestId": "req_…"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `found` | boolean | Something was found (and charged); false answers are free. |
| `creditsCharged` | integer | Credits this call cost. |
| `requestId` | string | ID of this call; the same as the X-Request-Id header. |
| `person` | object \| null | The person; null when not found. |
| `person.fullName` | string | Full name. |
| `person.firstName` | string \| null | First name. |
| `person.lastName` | string \| null | Last name. |
| `person.headline` | string \| null | Profile headline. |
| `person.linkedinUrl` | string \| null | LinkedIn profile URL. |
| `person.location` | object | Location: city, region (state), country (ISO 2-letter); each can be null. |
| `person.location.city` | string \| null | City. |
| `person.location.region` | string \| null | Region or state. |
| `person.location.country` | string \| null | ISO 3166-1 alpha-2 country code. |
| `person.currentJob` | object \| null | Current job title and company. |
| `person.currentJob.title` | string \| null | Job title. |
| `person.currentJob.company` | object \| null | Employer. |
| `person.currentJob.company.name` | string \| null | Company name. |
| `person.currentJob.company.domain` | string \| null | Company domain. |
| `person.currentJob.company.linkedinUrl` | string \| null | LinkedIn company page. |
| `person.currentJob.startDate` | string \| null | Start, YYYY-MM. |
| `person.currentJob.endDate` | string \| null | End, YYYY-MM; null while current. |
| `person.currentJob.current` | boolean | Still in this job. |
| `person.experience` | object[] | Up to 15 jobs, in profile order, each like currentJob. |
| `person.education` | object[] | Schools: school, degree, startYear, endYear. |
| `person.skills` | string[] | Skills on the profile. |
| `workEmail` | object \| null | Work email at the current employer when we have one on record (includeEmail, default true); null when none. |
| `workEmail.address` | string | Address. |
| `workEmail.status` | string | Always valid (only verified addresses are returned). One of: `valid`. |

### Enrich a company

`POST /api/v2/enrich/company`

Company profile from a domain or a LinkedIn company URL: industry, type, size, employee count, revenue range, founded year, headquarters, followers and who hosts its email. 1 credit when found; +1 with includeBreakdown (headcount by department and by country).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | no | Company domain (a website URL or an email address also works). |
| `linkedinUrl` | string | no | LinkedIn company URL, when you have no domain. |
| `includeBreakdown` | boolean | no | Headcount by department and by country (+1 credit). |

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v2/enrich/company" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","includeBreakdown":true}'
```

Response (200):

```jsonc
{
  "found": true,
  "company": {
    "name": "Example Inc",
    "domain": "example.com",
    "website": "https://example.com",
    "linkedinUrl": "https://www.linkedin.com/company/example",
    "industry": "Software Development",
    "type": "Privately Held",
    "size": "51-200",
    "employees": 120,
    "revenueRange": "$10M-$50M",
    "foundedYear": 2015,
    "description": "Example builds software for teams.",
    "location": { "city": "Austin", "region": "Texas", "country": "US" },
    "followers": 3000,
    "emailProvider": "google_workspace",   // microsoft_365 | zoho | proofpoint | mimecast | barracuda | other | null
    "acceptsEmail": true
  },
  "headcountBreakdown": {
    "total": 120,
    "departments": [{ "name": "Engineering", "count": 60, "percent": 50 }, … ],
    "countries": [{ "name": "US", "count": 100, "percent": 83.33 }, … ]
  },
  "creditsCharged": 2,
  "requestId": "req_…"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `found` | boolean | Something was found (and charged); false answers are free. |
| `creditsCharged` | integer | Credits this call cost. |
| `requestId` | string | ID of this call; the same as the X-Request-Id header. |
| `company` | object \| null | The company; null when not found. |
| `company.name` | string | Company name. |
| `company.domain` | string \| null | Primary domain. |
| `company.website` | string \| null | Website URL. |
| `company.linkedinUrl` | string \| null | LinkedIn company page. |
| `company.industry` | string \| null | Industry. |
| `company.type` | string \| null | e.g. Privately Held, Public Company. |
| `company.size` | string \| null | Headcount band, e.g. 51-200. |
| `company.employees` | integer \| null | Employee count. |
| `company.revenueRange` | string \| null | Revenue band, e.g. $10M-$50M. |
| `company.foundedYear` | integer \| null | Year founded. |
| `company.description` | string \| null | Short description (up to 300 characters). |
| `company.location` | object | Location: city, region (state), country (ISO 2-letter); each can be null. |
| `company.location.city` | string \| null | City. |
| `company.location.region` | string \| null | Region or state. |
| `company.location.country` | string \| null | ISO 3166-1 alpha-2 country code. |
| `company.followers` | integer \| null | LinkedIn followers. |
| `company.emailProvider` | string \| null | Who hosts the company's email (from its MX records). One of: `google_workspace`, `microsoft_365`, `zoho`, `proofpoint`, `mimecast`, `barracuda`, `other`. |
| `company.acceptsEmail` | boolean \| null | The domain has mail servers. |
| `headcountBreakdown` | object \| null | With includeBreakdown: headcount by department and by country (null when it could not be fetched; not charged then). |
| `headcountBreakdown.total` | integer \| null | Employees counted. |
| `headcountBreakdown.departments` | object[] | { name, count, percent } per department. |
| `headcountBreakdown.countries` | object[] | { name, count, percent } per country. |

- Personal mailbox domains (gmail.com, outlook.com …) are not companies: found is false and nothing is charged.

### People at a company

`POST /api/v2/enrich/company-contacts`

People who work at a company, filtered by seniority, department and country, with their work emails when we have them on record. 1 credit per person returned (emails included).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `domain / linkedinUrl` | string | no | Company domain, or its LinkedIn company URL (one of the two is required). |
| `seniority` | string[] | no | c_suite, vp, director, manager, staff, other. |
| `department` | string[] | no | sales, marketing, engineering, it, finance, operations, human_resources, legal, customer_service, management, research, purchasing, supply_chain, manufacturing, healthcare, education, public_sector, science, creative, construction, writing, other. |
| `country` | string[] | no | ISO 2-letter country codes, e.g. ["US", "GB"]. |
| `recentHires` | boolean | no | Only people who started in the last 90 days. |
| `limit` | number | no | People per page, 1–25 (default 10). Trimmed to what your balance covers. |
| `page` | number | no | Page number (default 1, up to 40). |
| `includeEmails` | boolean | no | Work emails (default true, no extra cost). |

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v2/enrich/company-contacts" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","seniority":["vp","director"],"department":["sales"],"limit":10}'
```

Response (200):

```jsonc
{
  "found": true,
  "company": { "name": "Example Inc", "domain": "example.com", "linkedinUrl": "https://www.linkedin.com/company/example" },
  "page": 1,
  "totalPages": 4,
  "people": [{
    "fullName": "Jane Doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "title": "VP Sales",
    "headline": "VP Sales at Example",
    "linkedinUrl": "https://www.linkedin.com/in/jane-doe",
    "location": { "city": "Austin", "region": "TX", "country": "US" },
    "startDate": "2023-04",
    "email": { "address": "jane.doe@example.com", "status": "valid" }   // null when none on record
  }],
  "creditsCharged": 1,
  "requestId": "req_…"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `found` | boolean | Something was found (and charged); false answers are free. |
| `creditsCharged` | integer | Credits this call cost. |
| `requestId` | string | ID of this call; the same as the X-Request-Id header. |
| `company` | object \| null | The company searched. |
| `company.name` | string \| null | Company name. |
| `company.domain` | string \| null | Company domain. |
| `company.linkedinUrl` | string \| null | LinkedIn company page. |
| `page` | integer | This page. |
| `totalPages` | integer | Pages available. |
| `people` | object[] | People on this page. |
| `people[].fullName` | string | Full name. |
| `people[].firstName` | string \| null | First name. |
| `people[].lastName` | string \| null | Last name. |
| `people[].title` | string \| null | Job title. |
| `people[].headline` | string \| null | Profile headline. |
| `people[].linkedinUrl` | string \| null | LinkedIn profile URL. |
| `people[].location` | object | Location: city, region (state), country (ISO 2-letter); each can be null. |
| `people[].location.city` | string \| null | City. |
| `people[].location.region` | string \| null | Region or state. |
| `people[].location.country` | string \| null | ISO 3166-1 alpha-2 country code. |
| `people[].startDate` | string \| null | Started at the company, YYYY-MM. |
| `people[].email` | object \| null | { address, status: valid } when we have a verified work email; null otherwise (the person is still charged). |

## Bulk jobs

Up to 25,000 rows per job, processed in the background. Poll the job or subscribe to the bulk_job.completed webhook. Each row is charged like a single call (1 credit when valid or risky), as it settles. A job is refused at submit only when your balance is 0; if credits run out mid-way it pauses (pauseReason insufficient_credits) and resumes when you top up.

### Start a bulk verification

`POST /api/v1/bulk-verify`

Verifies a list of addresses. Answers 202 with the job id. Paid plans.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `emails` | string[] | yes | 1 to 25,000 addresses. |
| `listName` | string | no | Optional job name (up to 120 characters), shown in the app and in bulk_job webhooks. |

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v1/bulk-verify" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["jane@example.com","john@example.org"]}'
```

Response (202):

```jsonc
{ "taskId": "6af89b4eb207737ad087338d", "status": "pending", "progress": { "total": 2, "processed": 0, "successful": 0, "failed": 0, "percentage": 0 }, "message": "Task created successfully. Use the taskId to check status and download results." }
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `taskId` | string | Job id for the task endpoints. |
| `status` | string | A new job starts pending. One of: `pending`. |
| `progress` | object | Row counts. |
| `progress.total` | integer | Rows in the job. |
| `progress.processed` | integer | Rows done so far. |
| `progress.successful` | integer | Rows processed without an error (not the same as valid). |
| `progress.failed` | integer | Rows that hit an error. |
| `progress.percentage` | integer | processed / total, 0–100. |
| `message` | string | Human-readable confirmation. |

### Start a bulk email find

`POST /api/v1/bulk-find`

Finds work emails for a list of people. Each row needs a first name and a domain or company. Answers 202 with the job id. Paid plans.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes | 1 to 25,000 rows: { firstName (required), lastName, domain or company }. |
| `listName` | string | no | Optional job name (up to 120 characters). |

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v1/bulk-find" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":[{"firstName":"Jane","lastName":"Doe","domain":"example.com"},{"firstName":"Li","company":"Acme"}]}'
```

Response (202):

```jsonc
{ "taskId": "6af89b51b207737ad087338e", "status": "pending", "progress": { "total": 2, "processed": 0, "successful": 0, "failed": 0, "percentage": 0 }, "message": "Task created successfully. Use the taskId to check status and download results." }
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `taskId` | string | Job id for the task endpoints. |
| `status` | string | A new job starts pending. One of: `pending`. |
| `progress` | object | Row counts. |
| `progress.total` | integer | Rows in the job. |
| `progress.processed` | integer | Rows done so far. |
| `progress.successful` | integer | Rows processed without an error (not the same as valid). |
| `progress.failed` | integer | Rows that hit an error. |
| `progress.percentage` | integer | processed / total, 0–100. |
| `message` | string | Human-readable confirmation. |

### Job status

`GET /api/v1/tasks/{taskId}`

Status and progress of a job (never the rows; use Job results). Unknown ids, or jobs of another account, answer 404 TASK_NOT_FOUND.

Request:

```bash
curl "https://api.skrap.ai/api/v1/tasks/TASK_ID" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{
  "taskId": "6af89b4eb207737ad087338d",
  "type": "bulk-verify",                 // bulk-verify | bulk-find
  "status": "completed",                 // pending | processing | paused | completed | failed | cancelled
  "progress": { "total": 2, "processed": 2, "successful": 2, "failed": 0, "percentage": 100 },
  "controls": { "canPause": false, "canResume": false, "canCancel": false, "stalled": false, "stopping": false },
  "input": { "method": "text" },
  "result": { "fileUrl": "https://…", "resultsExpired": false, "hasPartialResults": true },
  "metadata": { "creditsRequired": 2, "creditsUsed": 1, "creditsRefunded": 0, "startedAt": "2026-11-14T17:33:05.728Z", "completedAt": "2026-11-14T17:33:16.510Z", "apiKeyName": "Zapier" },
  "createdAt": "2026-11-14T17:33:02.579Z",
  "updatedAt": "2026-11-14T17:33:16.514Z"
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `taskId` | string | Job id. |
| `type` | string | Job type. One of: `bulk-verify`, `bulk-find`. |
| `status` | string | Job state. One of: `pending`, `processing`, `paused`, `completed`, `failed`, `cancelled`. |
| `progress` | object | Row counts. |
| `progress.total` | integer | Rows in the job. |
| `progress.processed` | integer | Rows done so far. |
| `progress.successful` | integer | Rows processed without an error (not the same as valid). |
| `progress.failed` | integer | Rows that hit an error. |
| `progress.percentage` | integer | processed / total, 0–100. |
| `controls` | object | What you can do with the job now. |
| `controls.canPause` | boolean | POST …/pause is allowed. |
| `controls.canResume` | boolean | POST …/resume is allowed. |
| `controls.canCancel` | boolean | POST …/cancel is allowed. |
| `controls.stalled` | boolean | No progress for a while; resume restarts it. |
| `controls.stopping` | boolean | A pause or cancel was requested and is finishing the current batch. |
| `input` | object | How the job was submitted: fileName (uploads), method (text \| file). |
| `result` | object | Results file. |
| `result.fileUrl` | string | Short-lived signed link to the results CSV, once stored (completed, cancelled or paused jobs). |
| `result.resultsExpired` | boolean | true once the results were deleted after the retention period. |
| `result.hasPartialResults` | boolean | Some rows are done and downloadable. |
| `error` | object | Only on failed jobs: { code, message }. |
| `metadata` | object | Credits and timing. |
| `metadata.creditsRequired` | integer | Most the job can cost (one per row). |
| `metadata.creditsUsed` | integer | Credits charged so far (valid and risky rows). |
| `metadata.creditsRefunded` | integer | Credits given back. |
| `metadata.startedAt / completedAt / pausedAt / cancelledAt` | string | ISO 8601 times, when they apply. |
| `metadata.pauseReason` | string | Why a paused job stopped. One of: `user`, `insufficient_credits`, `wave_timeout`. |
| `metadata.apiKeyName` | string | Name of the API key that started it. |
| `createdAt / updatedAt` | string | ISO 8601 times. |

### Job results (paged)

`GET /api/v1/tasks/{taskId}/results?offset=0&limit=50`

Result rows, 50 per call by default (offset / limit, limit up to 10,000). Works while the job runs, too.

Request:

```bash
curl "https://api.skrap.ai/api/v1/tasks/TASK_ID/results?offset=0&limit=50" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{
  "taskId": "6af89b51b207737ad087338e",
  "type": "bulk-find",
  "status": "completed",
  "offset": 0,
  "limit": 50,
  "total": 2,
  "statusCounts": { "valid": 1, "risky": 0, "invalid": 0, "unknown": 1 },
  "rows": [
    { "email": "jane.doe@example.com", "status": "valid", "recordIndex": 0, "firstName": "Jane", "lastName": "Doe", "company": "example.com", "domain": "example.com" },
    { "email": "", "status": "unknown", "recordIndex": 1, "firstName": "Li", "lastName": "", "company": "Acme", "domain": "" }
  ],
  "metadata": { "creditsUsed": 1, "creditsRequired": 2 },
  …
}
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `taskId` | string | Job id. |
| `type` | string | Job type. One of: `bulk-verify`, `bulk-find`. |
| `status` | string | Job state (results can be read while it runs). One of: `pending`, `processing`, `paused`, `completed`, `failed`, `cancelled`. |
| `progress` | object | Row counts. |
| `progress.total` | integer | Rows in the job. |
| `progress.processed` | integer | Rows done so far. |
| `progress.successful` | integer | Rows processed without an error (not the same as valid). |
| `progress.failed` | integer | Rows that hit an error. |
| `progress.percentage` | integer | processed / total, 0–100. |
| `controls` | object | What you can do with the job now. |
| `controls.canPause` | boolean | POST …/pause is allowed. |
| `controls.canResume` | boolean | POST …/resume is allowed. |
| `controls.canCancel` | boolean | POST …/cancel is allowed. |
| `controls.stalled` | boolean | No progress for a while; resume restarts it. |
| `controls.stopping` | boolean | A pause or cancel was requested and is finishing the current batch. |
| `offset` | integer | First row returned. |
| `limit` | integer | Rows asked for. |
| `total` | integer | Rows in the job. |
| `statusCounts` | object | Rows per status so far (rows not processed yet count as unknown). |
| `statusCounts.valid` | integer | Valid rows. |
| `statusCounts.risky` | integer | Risky rows. |
| `statusCounts.invalid` | integer | Invalid rows. |
| `statusCounts.unknown` | integer | Unknown or not-found rows. |
| `rows` | object[] | This page's rows. |
| `rows[].email` | string | Address verified, or found (empty when none was found). |
| `rows[].status` | string | Verification status (unknown for a find with no address). One of: `valid`, `risky`, `invalid`, `unknown`. |
| `rows[].recordIndex` | integer | Position of the row in your input, from 0. |
| `rows[].firstName` | string | Bulk find: first name sent. |
| `rows[].lastName` | string | Bulk find: last name sent. |
| `rows[].company` | string | Bulk find: company (or domain) sent. |
| `rows[].domain` | string | Domain of the address, or the domain searched. |
| `metadata` | object | creditsUsed, creditsRequired, startedAt, completedAt. |

### Download results as CSV

`GET /api/v1/tasks/{taskId}/download?inline=1`

inline=1 returns the CSV itself. Without it you get JSON { downloadUrl, expiresIn: 3600, message } once the results file is stored, or the CSV of the rows done so far for a running, paused or cancelled job. Columns: bulk verify Email, Status; bulk find First Name, Last Name, Company, Email, Status, Note. Results are kept at least 30 days; after the retention period the job answers 410 RESULTS_EXPIRED.

Request:

```bash
curl "https://api.skrap.ai/api/v1/tasks/TASK_ID/download?inline=1" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```text
Email,Status
"jane@example.com","valid"
"john@example.org","invalid"
```

### Pause, resume or cancel

`POST /api/v1/tasks/{taskId}/pause | resume | cancel`

Pause stops after the current batch; resume continues from the last saved row; cancel ends the job and keeps the rows done. Rows already processed stay charged; nothing else is.

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v1/tasks/TASK_ID/pause" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{ "message": "Task cancelled successfully", "taskId": "6af89b4eb207737ad087338d" }
```

- Not allowed in the job's state: 400 TASK_CANNOT_PAUSE / TASK_CANNOT_RESUME / TASK_CANNOT_CANCEL (with reason). Unknown job: 404 TASK_NOT_FOUND.

### List your jobs

`GET /api/v1/tasks?limit=20&offset=0`

Newest first, up to 500 per page. Filters: type (bulk-verify | bulk-find), status.

Request:

```bash
curl "https://api.skrap.ai/api/v1/tasks?limit=20&offset=0" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{ "tasks": [{ "taskId": "6af89b4eb207737ad087338d", "type": "bulk-verify", "status": "completed", "progress": { … }, "metadata": { … }, "createdAt": "…" }], "total": 1, "limit": 20, "offset": 0 }
```

## Lists

Save prospects and companies to lists and export them — the same lists you see in the app. Paid plans for changes; errors carry a code like every endpoint.

### Your lists

`GET /api/v1/lists?kind=prospect`

Names, kinds and lead counts.

Request:

```bash
curl "https://api.skrap.ai/api/v1/lists?kind=prospect" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{ "success": true, "lists": [{ "id": "6af89b88b207737ad0873395", "name": "Q2 outbound", "kind": "prospect", "leadCount": 42 }] }
```

### Create a list

`POST /api/v1/lists`

kind is prospect (people) or company. A name already used answers 409 CONFLICT.

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v1/lists" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q2 outbound","kind":"prospect"}'
```

Response (201):

```jsonc
{ "success": true, "list": { "id": "6af89b88b207737ad0873395", "name": "Q2 outbound", "kind": "prospect", "leads": [] } }
```

### A list with its leads

`GET /api/v1/lists/{id}`

Rename with PUT { name }, delete with DELETE, remove one lead with DELETE /api/v1/lists/{id}/leads/{leadId}.

Request:

```bash
curl "https://api.skrap.ai/api/v1/lists/ID" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{ "success": true, "list": { "id": "6af89b88b207737ad0873395", "name": "Q2 outbound", "kind": "prospect", "leads": [{ "id": "lead-123", "name": "Jane Doe", "email": "jane@example.com", "emailStatus": "valid", "company": "Example Inc", "jobRole": "CTO", "domain": "example.com" }] } }
```

### Add a lead

`POST /api/v1/lists/{id}/leads`

id, name and company are required, and on a prospect list an email too (find it first). A duplicate id or email answers 409 CONFLICT.

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v1/lists/ID/leads" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"lead-123","name":"Jane Doe","company":"Example Inc","email":"jane@example.com","emailStatus":"valid","jobRole":"CTO","domain":"example.com","location":"Austin, US","linkedinUrl":"https://linkedin.com/in/…"}'
```

Response (201):

```jsonc
{ "success": true, "message": "Lead added to list successfully", "lead": { … } }
```

- Fires the list.lead_added webhook.

### Copy or move leads

`POST /api/v1/lists/{id}/leads/transfer`

To another list of the same kind; leads already in the target are skipped.

Request:

```bash
curl -X POST "https://api.skrap.ai/api/v1/lists/ID/leads/transfer" \
  -H "x-api-key: $SKRAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetListId":"65f2…","leadIds":["lead-123"],"mode":"move"}'
```

Response (200):

```jsonc
{ "success": true, "mode": "move", "matched": 1, "added": 1, "skipped": 0 }
```

### Export as CSV

`GET /api/v1/lists/export?ids=all&kind=prospect`

One or more lists (ids=a,b or all). Leads on your do-not-contact list are left out unless includeSuppressed=1; the X-Skrap-Suppressed header says how many.

Request:

```bash
curl "https://api.skrap.ai/api/v1/lists/export?ids=all&kind=prospect" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```text
Name,Email,Email Status,Job Title,Company,Domain,Location,Industry,Headcount,LinkedIn,List
```

## Account

Who a key belongs to — handy as an integration's “test connection” call. Not counted against your rate limit.

### Key owner and balance

`GET /api/v2/account`

Email, plan, spendable credits and team of the key's owner.

Request:

```bash
curl "https://api.skrap.ai/api/v2/account" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{ "id": "6af896adf4b1515522cf96a9", "email": "you@company.com", "name": "Jane Doe", "plan": "pro", "credits": 4210, "team": { "id": "65f3…", "name": "Sales" }, "apiKey": { "id": "65f4…", "name": "Zapier" } }
```

Response fields:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | User id. |
| `email` | string | Account email. |
| `name` | string \| null | Account holder's name. |
| `plan` | string | Plan: free, pro (Professional), enterprise, basic (pay as you go without a subscription). One of: `free`, `pro`, `enterprise`, `basic`. |
| `credits` | number | Credits you can spend now (plan, packs and pay-as-you-go headroom). |
| `team` | object \| null | { id, name } when the key spends a team's credits. |
| `apiKey` | object \| null | { id, name } of the key used. |

## Usage

What your keys and your team spent, for finance, chargeback and reconciliation. Needs a key with the account scope (or full access). Team owners and admins see the whole team; members see their own usage.

### List usage

`GET /api/v2/usage?from=2026-11-01&to=2026-11-14&limit=100`

Single requests and bulk jobs, newest first, with the credits each one cost. Defaults to the last 30 days; a range can span up to 366 days. Page with nextCursor.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `from / to` | string | no | Dates (YYYY-MM-DD, UTC) or ISO timestamps. Default: the last 30 days. |
| `tool` | string | no | verify, find, search, enrichment or bulk. |
| `kind` | string | no | request (single calls) or bulk_job. |
| `apiKeyId` | string | no | Only calls made with this key. |
| `memberId` | string | no | Team owners and admins: only this member's usage. |
| `limit` | number | no | Items per page, 1–500 (default 100). |
| `cursor` | string | no | nextCursor from the previous page. |

Request:

```bash
curl "https://api.skrap.ai/api/v2/usage?from=2026-11-01&to=2026-11-14&limit=100" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```jsonc
{
  "items": [{
    "id": "65f1…",
    "kind": "request",            // request | bulk_job
    "timestamp": "2026-11-14T09:12:44.120Z",
    "endpoint": "/api/v2/verify-email",
    "tool": "verify",
    "status": "success",
    "credits": 1,
    "rows": null,                  // bulk jobs: rows in the job
    "apiKeyId": "65f4…",
    "apiKeyName": "Production",
    "userId": "65f0…",
    "userEmail": "you@company.com",
    "requestId": "req_…",
    "sandbox": false
  }],
  "nextCursor": null,
  "totals": { "credits": 874, "requests": 1200, "bulkJobs": 3 },
  "range": { "from": "2026-11-01T00:00:00.000Z", "to": "2026-11-14T23:59:59.999Z" }
}
```

### Export usage as CSV

`GET /api/v2/usage/export?from=2026-11-01&to=2026-11-14`

The same filters as List usage (no cursor or limit), as one CSV file of up to 100,000 rows. Columns: timestamp, kind, tool, endpoint, status, credits, rows, api_key_name, api_key_id, member_email, member_id, request_id, sandbox.

Request:

```bash
curl "https://api.skrap.ai/api/v2/usage/export?from=2026-11-01&to=2026-11-14" \
  -H "x-api-key: $SKRAP_API_KEY"
```

Response (200):

```text
timestamp,kind,tool,endpoint,status,credits,rows,api_key_name,api_key_id,member_email,member_id,request_id,sandbox
2026-11-14T09:12:44.120Z,request,verify,/api/v2/verify-email,success,1,,Production,65f4…,you@company.com,65f0…,req_…,false
```
