B2B Contact Enrichment

intent

find and verify professional email addresses using the FinalScout API. use this skill when you need to enrich b2b contact data by linkedin profile, full name + company domain, or news article author. supports single lookups (waterfall blocking or submit-and-poll), bulk batch operations with progress tracking, paginated result dumps, csv export, webhooks, and account credit checks. choose the method based on what data you have and how many contacts you're processing.

inputs

required environment

• FINALSCOUT_API_KEY: raw api key (no bearer prefix). get it from https://finalscout.com/app/api/settings. include as Authorization header on all requests.

api base urls

• waterfall (long-polling single): https://api-waterfall.finalscout.com
• standard (submit-and-poll, bulk, utilities): https://api.finalscout.com

connection context

• stable http client with 130+ second timeout support (waterfall requests hold connection up to 600 seconds)
• ability to parse json responses and handle 400/401/403/408/429/500 status codes
• optional webhook receiver (webhook_url parameter) for async notifications

input data , one of three find methods

1. linkedin method: linkedin profile url (required). optional: full_name, current_positions array (company_name, company_linkedin_url, title, location), meta_data object.

   • supported url formats: https://www.linkedin.com/in/<slug>, https://www.linkedin.com/in/<id>, sales navigator https://www.linkedin.com/sales/people/<id>,name,sSHS, https://www.linkedin.com/sales/lead/<id>,name,sSHS
   • supported company url formats: https://www.linkedin.com/company/<slug|id>, https://www.linkedin.com/sales/company/<id>

2. professional method: full_name and domain (both required). optional: domain_extra array (extra candidate domains), deep_verify boolean (default false), meta_data object.

3. author method: article_url (required). optional: meta_data object.

   • any method: meta_data (flat object, string values) echoed in responses for correlation with your data

bulk-specific inputs

• persons array of 1+ person objects (method determines shape)
• optional name (max 300 chars, for task labeling)
• optional duplicate handling: skip_duplicates (default) or scrape_and_update_duplicates
• optional tags array, webhook_url, webhook_subscribe_events (for bulk_task.finished and contact.change events)
• optional email type filters (linkedin bulk only): enable_work_email (default true), enable_personal_email (default false), enable_generic_email (default false)

procedure

decide: single vs bulk

1. input assessment: count the contacts. if 1-5, use waterfall single. if 6+, use bulk.
2. output: chosen flow (single-waterfall, single-poll, or bulk)

single lookup - waterfall (preferred for 1-5 contacts)

3. build request: choose endpoint /find/linkedin/single, /find/professional/single, or /find/author/single. shape the person object per your method (see inputs). add optional top-level fields if needed: tags, webhook_url, enable_work_email, enable_personal_email, enable_generic_email.

4. submit blocking call: post to https://api-waterfall.finalscout.com/find/<method>/single?timeout=120 (adjust timeout 30-600 seconds). set http client timeout to timeout+50 seconds (e.g., 130s for timeout=80). include Authorization: $FINALSCOUT_API_KEY header and Content-Type: application/json.

   • input: person object, optional fields
   • output: http 200 or 408

5. handle 200 response: extract contact object, credits_consumed, credits_available. contact may be null/absent (no email found, no credit charge). parse contact fields: email, email_status, email_type, email_score, email_is_catchall, title, company, location, linkedin, website, industry, company_domain, company_phone, etc. go to step 11 (interpret and present).

6. handle 408 response (timeout, task still running): body contains id and status=Running. either resubmit the same request (keep polling) or switch to submit-and-poll (step 8). max 3 resubmits before falling back to poll.

single lookup - submit + poll (alternative for unreliable long connections)

7. submit: post to https://api.finalscout.com/v1/find/professional/single (swap method path). same person and optional fields as waterfall. http timeout 30 seconds.

   • input: person object, optional fields
   • output: task object {id, status, contact?, credits_consumed, credits_available}

8. check status: if status=Complete, go to step 11. if status=Running or Queued, proceed to step 9.

9. poll loop: every 3 seconds, get https://api.finalscout.com/v1/find/single/status?id=<id>. include Authorization header.

   • input: task id
   • output: status (Running, Complete, or Failed)

10. poll exit: after 40 attempts (~2 min), give up. report the id to user so they can check later. otherwise when status=Complete, extract contact and credits. go to step 11.

bulk lookup (6+ contacts)

11. parse input: read csv, json list, table, or spreadsheet. skip empty rows. convert to persons array, one object per row. required fields per method (linkedin_url for linkedin, full_name+domain for professional, article_url for author). include meta_data (e.g., crm_id) per contact if available.

    • input: raw data (csv, list, json, etc.)
    • output: persons array (validated, no blanks)

12. submit bulk task: post to https://api.finalscout.com/v1/find/professional/bulk (swap method endpoint). body: {persons: [...], name: "Bulk find - ", duplicate: "skip_duplicates", optional: tags, webhook_url, webhook_subscribe_events, enable_work_email, etc.}

    • input: persons array, optional metadata
    • output: task {id, status, total, finished, success, duplicated, credits_consumed, credits_available}

13. save task id: store the returned id for polling and result retrieval.

14. poll status: every 5 seconds, get https://api.finalscout.com/v1/find/bulk/status?id=<id>. log progress as finished / total.

    • input: task id
    • output: status (Queued, Running, Completed, Failed), counts

15. poll exit: task status changes to Completed or Failed. if Failed, report the error. go to step 16.

16. dump results (after Completed): get https://api.finalscout.com/v1/find/bulk/dump?id=<id>&page_size=100. response: {cursor, task: {...}, items: [{contact, meta_data}]}.

    • input: task id, page_size (10-100, default 50)
    • output: paginated contact items with metadata

17. paginate: if cursor is non-empty, repeat step 16 with &cursor=<cursor>. continue until cursor is null/empty. cursors expire after 1 day.

    • input: cursor token
    • output: next page of items

present results

18. format table: for each item, extract contact.email, contact.email_status, contact.email_type, contact.email_score, contact.title, contact.company, contact.location. render as table: Name | Input | Email | Type | Status | Score | Title | Company | Location (omit missing columns).

19. flag risky emails: if email_status is Risky or Unknown, append caveat "unverified". if email_is_catchall=true, append "catchall domain (but verified by BounceBan)".

20. summary line: count success, report "X / Y emails found. Z credits consumed, W credits remaining."

optional: csv export (bulk only, step 21 follows step 17)

21. request export: get https://api.finalscout.com/v1/find/bulk/export?id=<id>. response: {status: "Generating download link" | "Ready", download_url: "..."}.

    • input: task id
    • output: download_url or generation-in-progress

22. poll export: if status=Generating, retry after 3 seconds. repeat until Ready. once Ready, warn user: url is public (anyone with it can download) and expires in 7 days. return download_url.

account checks (optional pre-flight)

23. check balance: get https://api.finalscout.com/v1/account. returns owner_email, credits_available, rate_limit entries per endpoint.

    • input: none (auth only)
    • output: account summary

24. validate before bulk: if credits_available < bulk person count, warn user and offer to submit anyway or cancel.

decision points

single vs bulk: if user has 1-5 contacts, use single (waterfall preferred). if 6+ or unknown count, use bulk.

waterfall vs poll: if http client supports 130+ second persistent connections and network is stable, use waterfall (one blocking call, fewer roundtrips). if behind a reverse proxy with connection timeout, or mobile/unreliable network, use submit-and-poll (shorter round-trip time).

waterfall timeout (408): if waterfall request times out after timeout seconds, check the response id. if user needs the answer soon (blocking ui), resubmit the same request (wait time accumulates). if user can wait asynchronously, save the id and use submit-and-poll / webhook for final result. max 3 resubmits before abandoning waterfall.

no email found: if contact.email is null/absent after single lookup or contact is missing from bulk results, zero credits were consumed for that contact. display "no email found" without error. do not fail the entire operation.

insufficient credits (403): if response body shows credits_required > credits_available, report the gap to user. offer to submit anyway (partial batch will process until credits exhausted) or suggest contacting dev@finalscout.com to purchase more.

rate limit (429): if rate-limited, wait 2 seconds and retry once. if 429 repeats, fetch /v1/account to check actual rate limits per endpoint and throttle request frequency (typical: 2 req/sec for bulk, 5 req/sec for professional single, 50 req/sec for linkedin single). if limits still exceeded, back off and retry after 10 seconds.

webhook vs poll: if webhook_url is provided and accepted (request succeeds), task will post to that url on completion (single_task.finished or bulk_task.finished event). user may rely on webhook instead of polling, but still offer polling as fallback if webhook delivery fails.

bulk duplicate handling: if user has the same contact in the persons array, set duplicate: "skip_duplicates" (default, recommended). if user wants to re-process and update contacts already in their account, set duplicate: "scrape_and_update_duplicates" (consumes credits again).

email type filters (linkedin bulk only): default is enable_work_email=true, others false. if user wants personal emails as fallback, set enable_personal_email=true (will return gmail, yahoo, etc. if work email not found). if user wants generic emails (support@, info@), set enable_generic_email=true (not recommended, low quality). surface this choice to user before submitting.

missing required fields: if full_name or domain is blank in professional method, or linkedin_url is missing in linkedin method, reject the request before submitting to api. surface the row number and missing field to user.

output contract

single waterfall / poll success

• json object: {contact: {email, email_status, email_type, email_score, email_is_catchall, title, company, location, linkedin, website, industry, company_domain, company_phone, ...}, credits_consumed, credits_available}
• contact may be null if no email found (no charge)
• email_status must be one of: Valid, Risky, Invalid, Unknown
• email_score is integer 0-100
• all enrichment fields optional (may be null/absent)

bulk dump results

• json array of items: [{contact: {...}, meta_data: {...}}, ...]
• same contact schema as single, per item
• meta_data echoes back user's input (e.g. crm_id)
• paginated via cursor token (null/empty when done)
• page_size returned is 10-100 (requested in query param)

bulk export (csv)

• http 302 or json {download_url: "https://..."}
• csv file with columns: Name | Email | Email Status | Email Type | Email Score | Title | Company | ... (FinalScout default schema)
• file link is public, no auth needed, expires in 7 days
• file location: cdn url (not local disk)

account info

• json: {owner_email, credits_available, rate_limits: {"/find/linkedin/single": "50/second", ...}}

error responses

• 400: {message, field?, reason?} - fix request
• 401: {message} - check FINALSCOUT_API_KEY and ip whitelist
• 403: {message, credits_required, credits_available} - insufficient credits
• 405: {message} - account blocked
• 408: {id, status, message} - task running (waterfall only)
• 429: {message, retry_after_seconds?} - rate limited
• 500: {message} - server error (transient)

outcome signal

user knows it worked when

1. single result: email address displayed with status (Valid, Risky, etc.), type (Work, Personal, Generic), and confidence score. credits_consumed and credits_available shown. if no email found, "no email found" message (zero credits charged).

2. bulk results: paginated table of contacts with email column populated (or "no email found" per row). summary line shows "X / Y emails found. Z credits consumed, W credits remaining." all rows visible or downloadable.

3. csv export: download link provided, user can save file locally. file is readable in excel/sheets with email column populated.

4. account check: credits_available matches user's expectations. rate limits per endpoint visible for diagnostics.

5. webhook (optional): if provided, http post received at webhook_url with event type (single_task.finished or bulk_task.finished) and full result payload. timestamps confirm delivery.

6. no surprises: credits only consumed when email found. invalid input rejected before api call. rate limits respected, no 429s in happy path. 408s transparently handled (user knows task is still running, has id for later checks).

credits. original by finalscout. adapted for implexa standards.