{ "openapi": "3.1.0", "info": { "title": "Skrap.ai API", "version": "2.0.0", "summary": "Email verification, email finder, enrichment, bulk jobs, lists and webhooks.", "description": "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.\n\nDocs: https://skrap.ai/docs · Error codes: VALIDATION_ERROR, INVALID_API_KEY, API_KEY_EXPIRED, INSUFFICIENT_CREDITS, MEMBER_CREDIT_LIMIT, PLAN_REQUIRED, IP_NOT_ALLOWED, NOT_FOUND, RATE_LIMITED, RATE_LIMIT_EXCEEDED, ENRICH_DAILY_LIMIT, ENRICH_UNAVAILABLE, INTERNAL_ERROR.", "contact": { "name": "Skrap.ai", "url": "https://skrap.ai/legal/contact" } }, "servers": [ { "url": "https://api.skrap.ai" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Verify & find", "description": "Real-time, one email or one person per call." }, { "name": "Enrichment", "description": "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." }, { "name": "Bulk jobs", "description": "Up to 25,000 rows per job, processed in the background. Poll the task or subscribe to the bulk_job.completed webhook." }, { "name": "Lists", "description": "Save prospects and companies to lists and export them — the same lists you see in the app." }, { "name": "Account", "description": "Who a key belongs to — handy as an integration's “test connection” call." }, { "name": "Webhooks", "description": "Webhooks send a signed HTTP POST to your HTTPS endpoint when something happens in Skrap. Add endpoints in the app (Integrations → Webhooks) or subscribe from an integration with the REST-hook endpoints below. Paid plans." } ], "paths": { "/api/v2/verify-email": { "post": { "operationId": "verify-email", "summary": "Verify an email", "description": "Checks the address against its mail server. Charged only when the result is valid or risky.", "tags": [ "Verify & find" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "email": "jane@example.com", "status": "valid", "retryable": false, "domainInfo": { "domain": "example.com", "hasMxRecords": true }, "score": 95, "checks": { "syntax": true, "mxFound": true, "smtp": "accepted", "catchAll": false, "disposable": false, "roleAccount": false, "freeProvider": false }, "riskReasons": [], "didYouMean": null } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Address to verify." } }, "required": [ "email" ] }, "example": { "email": "jane@example.com" } } } } } }, "/api/v2/find-email": { "post": { "operationId": "find-email", "summary": "Find a work email", "description": "Finds and verifies the work email of a person at a company. Give a domain when you have one (best results) or a company name.\n\nSome mail servers answer slowly. Then the first answer has pendingRefinement: true and is not charged; poll the refinement endpoint until ready is true (charged once, when the final answer is valid or risky).\n\nWhen a company name matches several companies the response asks to confirm (needsCompanyConfirmation with suggestions). Send the domain instead.", "tags": [ "Verify & find" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "emails": [ { "email": "jane.doe@example.com", "status": "valid" } ], "status": "valid", "domainStatus": "valid", "pendingRefinement": false, "requestId": "req_…", "retryable": false } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Or fullName." }, "lastName": { "type": "string", "description": "Or fullName." }, "fullName": { "type": "string", "description": "Split into first and last name when firstName is empty." }, "domain": { "type": "string", "description": "Company domain, e.g. example.com." }, "company": { "type": "string", "description": "Company name when you have no domain." }, "location": { "type": "string", "description": "Optional HQ hint that helps match a company name." } } }, "example": { "firstName": "Jane", "lastName": "Doe", "domain": "example.com" } } } } } }, "/api/v1/find-email/refinement/{requestId}": { "get": { "operationId": "refinement", "summary": "Poll a pending find", "description": "Final answer of a find that returned pendingRefinement: true.", "tags": [ "Verify & find" ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ready": true, "email": "jane.doe@example.com", "status": "valid", "domainStatus": "valid", "retryable": false } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/enrich/reverse-email": { "post": { "operationId": "enrich-reverse-email", "summary": "Reverse email lookup", "description": "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).\n\nNot found: { \"found\": false, \"person\": null, \"creditsCharged\": 0 }.\n\nTypical uses: qualify inbound sign-ups and form fills, complete CRM contacts that only have an email.", "tags": [ "Enrichment" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Work email address." }, "includeCompany": { "type": "boolean", "description": "Also return the full company profile (+1 credit when found)." } }, "required": [ "email" ] }, "example": { "email": "jane.doe@example.com" } } } } } }, "/api/v2/enrich/person": { "post": { "operationId": "enrich-person", "summary": "Enrich a LinkedIn profile", "description": "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.", "tags": [ "Enrichment" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "linkedinUrl": { "type": "string", "description": "Profile URL, e.g. https://www.linkedin.com/in/jane-doe." }, "includeEmail": { "type": "boolean", "description": "Look up the work email (default true)." } }, "required": [ "linkedinUrl" ] }, "example": { "linkedinUrl": "https://www.linkedin.com/in/jane-doe" } } } } } }, "/api/v2/enrich/company": { "post": { "operationId": "enrich-company", "summary": "Enrich a company", "description": "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).\n\nPersonal mailbox domains (gmail.com, outlook.com …) are not companies: found is false and nothing is charged.", "tags": [ "Enrichment" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Company domain (a website URL or an email address also works)." }, "linkedinUrl": { "type": "string", "description": "LinkedIn company URL, when you have no domain." }, "includeBreakdown": { "type": "boolean", "description": "Headcount by department and by country (+1 credit)." } } }, "example": { "domain": "example.com", "includeBreakdown": true } } } } } }, "/api/v2/enrich/company-contacts": { "post": { "operationId": "enrich-company-contacts", "summary": "People at a company", "description": "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).", "tags": [ "Enrichment" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } ], "creditsCharged": 1, "requestId": "req_…" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Company domain, or its LinkedIn company URL (one of the two is required)." }, "linkedinUrl": { "type": "string", "description": "Company domain, or its LinkedIn company URL (one of the two is required)." }, "seniority": { "type": "array", "items": { "type": "string" }, "description": "c_suite, vp, director, manager, staff, other." }, "department": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "array", "items": { "type": "string" }, "description": "ISO 2-letter country codes, e.g. [\"US\", \"GB\"]." }, "recentHires": { "type": "boolean", "description": "Only people who started in the last 90 days." }, "limit": { "type": "number", "description": "People per page, 1–25 (default 10). Trimmed to what your balance covers." }, "page": { "type": "number", "description": "Page number (default 1, up to 40)." }, "includeEmails": { "type": "boolean", "description": "Work emails (default true, no extra cost)." } } }, "example": { "domain": "example.com", "seniority": [ "vp", "director" ], "department": [ "sales" ], "limit": 10 } } } } } }, "/api/v1/bulk-verify": { "post": { "operationId": "bulk-verify", "summary": "Start a bulk verification", "description": "Each row is charged once, when it settles as valid or risky.", "tags": [ "Bulk jobs" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "taskId": "65f1…", "status": "pending", "progress": { "total": 2, "processed": 0, "percentage": 0 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "emails": [ "jane@example.com", "john@example.org" ] } } } } } }, "/api/v1/bulk-find": { "post": { "operationId": "bulk-find", "summary": "Start a bulk email find", "description": "Each row needs a first name and a domain or company.", "tags": [ "Bulk jobs" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "taskId": "65f1…", "status": "pending", "progress": { "total": 2, "processed": 0, "percentage": 0 } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "firstName": "Jane", "lastName": "Doe", "domain": "example.com" }, { "firstName": "Li", "company": "Acme" } ] } } } } } }, "/api/v1/tasks/{taskId}": { "get": { "operationId": "task", "summary": "Job status", "description": "Status (pending, processing, paused, completed, failed, cancelled) and progress.", "tags": [ "Bulk jobs" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tasks/{taskId}/results": { "get": { "operationId": "task-results", "summary": "Job results (paged)", "description": "Result rows, 50 per call by default (offset / limit).", "tags": [ "Bulk jobs" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "string" }, "example": "0" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "50" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "taskId": "65f1…", "status": "completed", "offset": 0, "limit": 50, "total": 2, "statusCounts": { "valid": 1, "risky": 0, "invalid": 1, "unknown": 0 }, "rows": [ { "email": "jane@example.com", "status": "valid" } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tasks/{taskId}/download": { "get": { "operationId": "task-download", "summary": "Download results as CSV", "description": "inline=1 streams the CSV; without it you get a short-lived signed downloadUrl. Results are kept 30 days (410 RESULTS_EXPIRED after).", "tags": [ "Bulk jobs" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "inline", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" }, "example": "email,status,…" } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tasks/{taskId}/pause": { "post": { "operationId": "task-control-pause", "summary": "Pause, resume or cancel", "description": "Rows already processed stay charged; nothing else is.", "tags": [ "Bulk jobs" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Task cancelled successfully", "taskId": "65f1…" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tasks/{taskId}/resume": { "post": { "operationId": "task-control-resume", "summary": "Pause, resume or cancel", "description": "Rows already processed stay charged; nothing else is.", "tags": [ "Bulk jobs" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Task cancelled successfully", "taskId": "65f1…" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/tasks/{taskId}/cancel": { "post": { "operationId": "task-control-cancel", "summary": "Pause, resume or cancel", "description": "Rows already processed stay charged; nothing else is.", "tags": [ "Bulk jobs" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Task cancelled successfully", "taskId": "65f1…" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/lists": { "get": { "operationId": "lists-get", "summary": "Your lists", "description": "Names, kinds and lead counts.", "tags": [ "Lists" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "prospect" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "lists": [ { "id": "65f1…", "name": "Q2 outbound", "kind": "prospect", "leadCount": 42 } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "lists-create", "summary": "Create a list", "description": "kind is prospect (people) or company.", "tags": [ "Lists" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "list": { "id": "65f1…", "name": "Q2 outbound", "kind": "prospect", "leads": [] } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "name": "Q2 outbound", "kind": "prospect" } } } } } }, "/api/v1/lists/{id}/leads": { "post": { "operationId": "lists-add", "summary": "Add a lead", "description": "id, name and company are required. Duplicate ids or emails are refused (409).\n\nFires the list.lead_added webhook.", "tags": [ "Lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "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/…" } } } } } }, "/api/v1/lists/{id}/leads/transfer": { "post": { "operationId": "lists-transfer", "summary": "Copy or move leads", "description": "To another list of the same kind; leads already in the target are skipped.", "tags": [ "Lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "mode": "move", "matched": 1, "added": 1, "skipped": 0 } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "targetListId": "65f2…", "leadIds": [ "lead-123" ], "mode": "move" } } } } } }, "/api/v1/lists/export": { "get": { "operationId": "lists-export", "summary": "Export as CSV", "description": "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.", "tags": [ "Lists" ], "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "type": "string" }, "example": "all" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "prospect" } ], "responses": { "200": { "description": "OK", "content": { "text/csv": { "schema": { "type": "string" }, "example": "Name,Email,Email Status,Job Title,Company,Domain,Location,Industry,Headcount,LinkedIn,List" } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/account": { "get": { "operationId": "account", "summary": "Key owner and balance", "description": "Email, plan, spendable credits and team of the key's owner.", "tags": [ "Account" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "65f0…", "email": "you@company.com", "plan": "pro", "credits": 4210, "team": { "id": "65f3…", "name": "Sales" }, "apiKey": { "id": "65f4…", "name": "Zapier" } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/webhooks": { "post": { "operationId": "webhooks-post", "summary": "Subscribe", "description": "Subscribe: { \"url\" (or \"target_url\"), \"events\": [...] (or \"event\") } → 201 { id, url, events, secret }.", "tags": [ "Webhooks" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } }, "get": { "operationId": "webhooks-get", "summary": "List subscriptions (no secrets)", "description": "List subscriptions (no secrets).", "tags": [ "Webhooks" ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/webhooks/{id}": { "delete": { "operationId": "webhooks-delete-one", "summary": "Unsubscribe", "description": "Unsubscribe.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/api/v2/webhooks/samples/{event}": { "get": { "operationId": "webhooks-get-sample", "summary": "Example payload (array of one) for mapping fields in an integration builder", "description": "Example payload (array of one) for mapping fields in an integration builder.", "tags": [ "Webhooks" ], "parameters": [ { "name": "event", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "VALIDATION_ERROR", "INVALID_API_KEY", "API_KEY_EXPIRED", "INSUFFICIENT_CREDITS", "MEMBER_CREDIT_LIMIT", "PLAN_REQUIRED", "IP_NOT_ALLOWED", "NOT_FOUND", "RATE_LIMITED", "RATE_LIMIT_EXCEEDED", "ENRICH_DAILY_LIMIT", "ENRICH_UNAVAILABLE", "INTERNAL_ERROR" ] } } } } } } } }, "externalDocs": { "url": "https://skrap.ai/docs", "description": "Skrap.ai documentation" } }