ScraperCity logo

Lead Enrichment Tool API API Documentation

Lead Enrichment Tool API

Match a list of contacts against the B2B database and append email, phone, title, and company data. Match keys (priority order): email, social profile URL, mobile, company domain. Returns the highest-seniority person at a domain when matching by domain alone. Requires $149/mo plan.

Included with $149/mo planGET /api/v1/enrich

Database APIs are included with the $149/mo plan.

Parameters

NameTypeRequiredDescription
rowsobject[]RequiredArray of input rows. Each row needs at least one of: email, social, mobile, domain. Up to 1,000 rows per request.Example: [{"email":"john@acme.com"},{"domain":"tesla.com"},{"social":"<profile_url>"}]
previewbooleanOptionalIf true, returns match count + sample without counting toward your daily allowance. With replaceLeftContacts: true it also returns replacements.known_left (matched contacts already known to have left), replacements.unchecked (checked on a real call, so more may be found) and the price per replacement.Default: falseExample: false
replaceLeftContactsbooleanOptionalReplace contacts who have left the company with the person now in that role, with a verified email. $0.02 per replacement, charged from your credits only when a replacement is found (the match itself stays included in your plan). The match results come back right away; replacements finish shortly after (usually within 5 to 20 minutes, at most 60). The response adds replacements.run_id: poll GET /api/v1/scrape/status/{run_id}, then download /api/downloads/{run_id} for one row per contact (row_indexes, replaced_contact, status, and the new contact in the sc_* columns). Contacts not done in time come back unchanged and are not charged. If your balance does not cover the contacts already known to have left, replacements.status is NOT_STARTED with reason insufficient_balance.Default: falseExample: true

Examples

Enrich a list of email addresses

curl -X POST "https://app.scrapercity.com/api/v1/enrich" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"email":"john@acme.com"},{"email":"jane@stripe.com"}]}'

Enrich a mixed list (email + domain + social)

curl -X POST "https://app.scrapercity.com/api/v1/enrich" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"email":"john@acme.com"},{"domain":"tesla.com"},{"social":"<profile_url>"}]}'

Preview match count without consuming daily allowance

curl -X POST "https://app.scrapercity.com/api/v1/enrich" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"email":"john@acme.com"}],"preview":true}'

Enrich and replace contacts who have left the company

curl -X POST "https://app.scrapercity.com/api/v1/enrich" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"email":"john@acme.com"},{"email":"jane@stripe.com"}],"replaceLeftContacts":true}'

Use Cases

  • •Enrich incoming leads in real time as they sign up
  • •Append firmographic data to a CRM export before importing
  • •Find decision-makers at a list of target companies (domain match)
  • •Reverse-look-up phone numbers or social profile URLs to get full profiles
  • •Keep an old CRM list current: replace contacts who have left with the person now in their role

Best Practices

  • •Provide multiple match keys per row when you have them - email + social gives the best chance of a hit
  • •Use preview mode (preview: true) to estimate match rate before processing large lists
  • •Rate limit: 1,000 rows per request, 100,000 matches per day
  • •Daily limit resets at midnight UTC
  • •Domain-only rows return the highest-seniority person at that company (CEO > C-suite > VP > Director > else)
  • •Mobile match is country-code-agnostic - we compare on the last 10 digits
  • •Set replaceLeftContacts: true to swap contacts who have left for the person now in that role ($0.02 per replacement found); preview with replaceLeftContacts: true first to see how many are already known to have left
  • •Requires $149/mo plan

Every scrape returns a runId. Poll GET /api/v1/scrape/status/{runId} until it completes, then download via GET /api/downloads/{runId}?format=csv.

Authenticate every request with Authorization: Bearer YOUR_API_KEY. See the full API reference for authentication, rate limits and error codes.