Leads and enrichment

Search the pool

curl -s -X POST "$API/leads/search" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"q":"engineer","limit":3}'

{
  "success": true,
  "data": {
    "items": [
      {
        "pool_id": "9c1d4e07-2a55-5b83-9f16-4d8e0b73ca21",
        "full_name": "Dana Keller",
        "title": "Marketing Director",
        "seniority": "director",
        "department": "marketing",
        "email_masked": "d•••@northwind.example",
        "email_status": "verified",
        "has_email": true,
        "phone_count": 1,
        "location": "Edinburgh, GB",
        "score": { "value": 62 },
        "company": {
          "name": "Northwind Systems",
          "domain": "northwind.example",
          "industry": "Computer Software",
          "industries_more": 0,
          "employee_count": 350,
          "employee_range": "201-500",
          "keywords": ["devops", "automated deployment"],
          "keywords_more": 1
        },
        "email_revealed": true,
        "email": "[email protected]",
        "phone": "+44 20 7946 0102",
        "linkedin_url": "https://www.linkedin.com/in/example-profile",
        "phone_available": true,
        "saved_lead_id": "6b2f8a14-77c3-4de9-b105-3ea9c5148d77"
      }
    ],
    "next_cursor": "NjI.36d9e92d-4545-5df1-9ac0-99f2a50aa6e7",
    "result_type": "person",
    "sort": { "field": "score", "desc": true },
    "total": 260,
    "total_display": "260",
    "total_is_estimate": false,
    "search_backend": "go-node"
  }
}

• email is only present when email_revealed is true. Otherwise you get email_masked, and phone and linkedin_url come back null even when phone_available is true. The raw value never leaves the server unless it has been paid for.
• saved_lead_idis non-null when your org already saved this person — useful for rendering “already in your list” without a second query.
• Paginate with next_cursor, not an offset. Pass it back as cursor on the next request.
• total_is_estimate tells you whether total can be trusted as an exact count.
• search_backend is go-node when the query was answered by the Go pool engine and fastapi-ormwhen it fell through to the Python path. Both read the same database, so it is a performance detail, not a data one — but see the note below for the one case where the choice is not about performance at all.

Read email_status before you mail anyone

Facets

Facets return counts per value for the same filter set, which is what makes a search refinable rather than a lottery.

curl -s -X POST "$API/leads/facets" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"q":"engineer"}'

{
  "success": true,
  "data": {
    "seniority": [
      { "value": "director", "count": 134 }, { "value": "manager", "count": 47 },
      { "value": "founder", "count": 33 },   { "value": "c_suite", "count": 33 },
      { "value": "vp", "count": 13 }
    ],
    "department": [
      { "value": "marketing", "count": 136 }, { "value": "sales", "count": 63 },
      { "value": "executive", "count": 33 },  { "value": "engineering", "count": 28 }
    ],
    "country": [
      { "value": "GB", "count": 91 }, { "value": "AU", "count": 65 },
      { "value": "PH", "count": 56 }, { "value": "CA", "count": 24 },
      { "value": "NL", "count": 13 }, { "value": "SG", "count": 7 },
      { "value": "AE", "count": 4 }
    ],
    "email_status": [
      { "value": "unverified", "count": 114 }, { "value": "verified", "count": 100 },
      { "value": "guessed", "count": 46 }
    ],
    "industry": [
      { "value": "Computer Software", "count": 230 },
      { "value": "Computer & Network Security", "count": 30 }
    ],
    "search_backend": "go-node"
  }
}

Saving a search

curl -s -X POST "$API/lead-searches" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"CMOs in software, AU + GB",
       "filters":{"seniority":["c_suite"],"department":["marketing"],"country":["AU","GB"]}}'

{"success":true,"data":{"id":"4cca8e98-1493-484f-976f-9c51c720b58b",
                        "name":"CMOs in software, AU + GB"}}

Reveal, and what it costs

Reveals are metered per organisation per calendar month, and the allowance is a real limit: the plan sets it. The free Self-Hosted tier includes 50 a month. The paid tiers carry a per-seat figure that pools across the workspace, so what you actually get is the plan’s quota multiplied by the seats you pay for. Past the allowance a reveal is refused with 402 rather than served.

A per-tenant override (ss_org_settings.lead_reveal_quota) can only tighten that number, never lift it. The ordering is deliberate: support sets an override to contain a workspace abusing the pool, and a plan upgrade must not quietly undo a limit somebody applied for a reason. Check the meter before you spend:

curl -s "$API/leads/quota" -H "Authorization: Bearer $TOKEN"

{"success":true,"data":{"used":27,"allowance":2500000,"unlimited":false,"remaining":2499973,"display":"27 / 2500000"}}

curl -s -X POST "$API/leads/reveal" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"pool_person_id":"4a7e6d20-9b31-5c48-8e02-1f5b7c93da60"}'

{
  "success": true,
  "data": {
    "pool_id": "4a7e6d20-9b31-5c48-8e02-1f5b7c93da60",
    "email": "[email protected]",
    "phone": "+1 555 0147",
    "linkedin_url": "https://www.linkedin.com/in/example-profile",
    "quota": {
      "used": 27, "allowance": 2500000, "unlimited": false,
      "remaining": 2499973, "display": "27 / 2500000"
    }
  }
}

Save, then convert

1. 1

   Save — a snapshot, costing nothing

   POST/leads/save

   ExecutedCopy

   curl -s -X POST "$API/leads/save" \
     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"pool_person_ids":["4a7e6d20-9b31-5c48-8e02-1f5b7c93da60"]}'
   
   {"success":true,"saved":1,"already_saved":0}

   A saved lead is frozen at save time. Title, company and score do not move underneath you when the pool is re-crawled, which is what makes a qualified list stay qualified.

2. 2

   Inspect the lead and any drift

   GET/leads/{lead_id}

   Real response (trimmed)Copy

   {
     "id": "6b2f8a14-77c3-4de9-b105-3ea9c5148d77",
     "pool_person_id": "9c1d4e07-2a55-5b83-9f16-4d8e0b73ca21",
     "full_name": "Dana Keller",
     "title": "Marketing Director",
     "email": "[email protected]",
     "email_status": "verified",
     "status": "converted",
     "erasure_pending": false,
     "converted_contact_id": "aebb8a37-9ed8-4fbb-9017-3a22e44a0892",
     "converted_at": "2026-08-05T19:06:59.127291+00:00",
     "pool": {
       "pool_id": "9c1d4e07-2a55-5b83-9f16-4d8e0b73ca21",
       "is_active": true,
       "email_revealed": true,
       "email_status": "verified",
       "title": "Marketing Director",
       "company_name": "Northwind Systems",
       "quality_score": 62,
       "last_verified_at": null
     },
     "drift": []
   }

3. 3

   Convert — the only way a record becomes mailable

   POST/leads/convert-from-poolpool → contact in one step

   ExecutedCopy

   curl -s -X POST "$API/leads/convert-from-pool" \
     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -d '{"pool_person_ids":["4a7e6d20-9b31-5c48-8e02-1f5b7c93da60"]}'

   Real response — the same person a second timeCopy

   {
     "converted": 0,
     "revealed_now": 0,
     "already_converted": 1,
     "skipped_no_quota": 0,
     "skipped_no_email": 0,
     "skipped_erased": 0,
     "contact_ids": ["86df14c8-c914-4151-b6d6-a96819ed7b1c"],
     "quota": {
       "used": 27, "allowance": 2500000, "unlimited": false,
       "remaining": 2499973, "display": "27 / 2500000"
     },
     "success": true
   }

   The other conversion routes: POST /leads/{lead_id}/convert for a single saved lead, and POST /leads/bulk-convert for many at once. They do not return the shape above. The full accounting block — and in particular the quota meter and contact_ids — exists only on convert-from-pool, because it is the only one of the three that can spend a reveal. Read resp["quota"] after bulk-convert and you get a KeyError.

   Executed — the other two shapes, in fullCopy

   POST /leads/bulk-convert   -d '{"lead_ids":["7e1daee4-…"]}'
   {"success":true,"converted":0,"skipped_no_email":0,"already_converted":1}
   
   POST /leads/7e1daee4-…/convert   -d '{}'
   {"success":true,"already_converted":true,"contact_id":"c9cf967b-…"}

   So: bulk-convert reports four counters and no quota, no contact_ids, no revealed_now, no skipped_no_quota and no skipped_erased— it operates on leads you already saved, whose emails are already revealed or already absent, so there is nothing left to meter. The single-lead route reports one contact and whether it reused one. Only convert-from-pool reaches into the pool, and only it has a meter to report.

Enrichment

There are two different things called enrichment here.

The site crawler

Crawls a company’s own website and folds what it finds back into the pool. This was executed live against a real domain:

curl -s -X POST "$API/leads/enrich" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}'

{
  "success": true,
  "company_id": "9f76e889-bfdb-4852-a5ca-499b3e20f322",
  "company_created": true,
  "crawled": 1,
  "changed": ["company created", "keywords"],
  "people_found": 0,
  "people_added": 0,
  "people_already_known": 0,
  "people_skipped_erased": 0,
  "elapsed_ms": 124,
  "note": null
}

The rules it enforces are worth knowing, because they are unusual:

• It only fills gaps.An existing description, keyword set or address is never overwritten by a crawl. A curated or verified value outranks a scrape, and a “refresh” that quietly replaced good data with worse data would be impossible to notice and impossible to undo.
• Erasure is checked before every insert. Without that, the next crawl would resurrect exactly the people you were asked to forget. people_skipped_erased counts them.
• Provenance is recorded— which URL, which fields, when. “Where did this come from” stays answerable.
• Nothing is invented. A name is derived from an address only when the local part is plausibly a name; role accounts (info@, sales@) are dropped entirely; and every discovered address is recorded as unverified, because finding a string on a web page is not verification.

Contact enrichment on your own key

Separately, POST /contacts/enrich fills gaps on contacts you already have. It uses Hunter.io when your organisation has connected a Hunter key as an enrichment integration, and otherwise falls back to deterministic email-pattern inference.

curl -s -X POST "$API/contacts/enrich" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"contact_ids":["86df14c8-c914-4151-b6d6-a96819ed7b1c"]}'

Erasure

Common problems

Next