B2b Contact Enrichment

Find professional email addresses by full name and company domain using the FinalScout API. Supports single lookup and bulk batch processing.

FinalScout Professional Email Finder

Find a professional email address when you have a person's full name and company domain. Supports single lookups and bulk batches of any size.

Base URL: https://api.finalscout.com Auth header: Authorization: $FINALSCOUT_API_KEY

---

Single lookup

Use when the user provides one name + domain pair.

Endpoint: POST /v1/find/professional/single

Request body:

json

{
  "person": {
    "full_name": "<full name>",
    "domain": "<company domain, e.g. microsoft.com>",
    "deep_verify": false
  }
}

Step 1 — Submit:

bash

curl -s -X POST https://api.finalscout.com/v1/find/professional/single \
  -H "Authorization: $FINALSCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person":{"full_name":"<name>","domain":"<domain>","deep_verify":false}}'

Save the returned id. If status is already Complete, skip step 2.

Step 2 — Poll until complete:

bash

curl -s "https://api.finalscout.com/v1/find/single/status?id=<id>" \
  -H "Authorization: $FINALSCOUT_API_KEY"

Repeat every 3 seconds until status is Complete. Stop after 10 attempts (30 seconds total); report timeout if still running.

Result interpretation:

• contact.email present and contact.email_status is Valid → email found, show it
• contact.email_status is Risky or Unknown → show the email with a caveat
• No contact field in response → no email found for this person
• credits_available in response → show remaining credits as a note

Optional parameters (add to request body if user specifies):

• "enable_personal_email": true — also look for personal emails (Gmail, etc.)
• "enable_generic_email": true — also look for generic emails (info@, support@)
• "tags": ["tag1"] — tag the contact in FinalScout
• "webhook_url": "<url>" — get notified async instead of polling

---

Bulk lookup

Use when the user provides multiple name + domain pairs (CSV, list, table, or JSON).

Endpoint: POST /v1/find/professional/bulk

Step 1 — Parse input into an array of objects:

json

[
  {"full_name": "Bill Gates",  "domain": "microsoft.com"},
  {"full_name": "Elon Musk",   "domain": "tesla.com"}
]

Strip empty rows. Each item requires full_name and domain.

Step 2 — Submit bulk task:

bash

curl -s -X POST https://api.finalscout.com/v1/find/professional/bulk \
  -H "Authorization: $FINALSCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persons": [<array from step 1>],
    "name": "Bulk find - <date>",
    "duplicate": "skip_duplicates"
  }'

Save the returned id.

Step 3 — Poll status:

bash

curl -s "https://api.finalscout.com/v1/find/bulk/status?id=<id>" \
  -H "Authorization: $FINALSCOUT_API_KEY"

Poll every 5 seconds. Report progress as finished / total on each poll. Stop polling once status is Completed or Failed.

Step 4 — Fetch results (after Completed):

bash

curl -s "https://api.finalscout.com/v1/find/bulk/dump?id=<id>&page_size=100" \
  -H "Authorization: $FINALSCOUT_API_KEY"

If response contains a non-null cursor, fetch the next page:

bash

curl -s "https://api.finalscout.com/v1/find/bulk/dump?id=<id>&page_size=100&cursor=<cursor>" \
  -H "Authorization: $FINALSCOUT_API_KEY"

Repeat until cursor is null. Collect all items across pages.

Step 5 — Present results as a table:

Name	Domain	Email	Status	Score
Bill Gates	microsoft.com	[e-mail]	Valid	95
...	...	no email found	-	-

Show summary: X / Y emails found. Z credits consumed.

Optional bulk parameters:

• "enable_personal_email": true
• "enable_generic_email": true
• "tags": ["tag1"]
• "webhook_url": "<url>" — webhook fires contact.change per email found and bulk_task.finished at the end
• "duplicate": "scrape_and_update_duplicates" — re-process contacts already in the account

---

Error handling

HTTP status	Meaning	Action
401	Bad API key	Ask user to check FINALSCOUT_API_KEY
403	No credits	Report credits_required vs credits_available
429	Rate limited	Wait 2 seconds and retry once
500	Server error	Retry once; if it fails again, report the error

---

Credits

Each email successfully found costs 1 credit. No charge if no email is found. Show credits_available after each operation so the user knows their balance.