Contact Bulk Match API

Match a list of person names to contacts in bulk. Uses text search for fast matching, with optional full-data enrichment from the contacts database.

POST https://api.discolike.com/v1/contacts/bulk-match

With enrich, the task is priced before it is queued at the request fee plus limit records per query; one the remaining balance cannot cover is refused with a 403 INSUFFICIENT_BALANCE that names the largest number of queries that fits at that limit.

Parameters

Parameter	Type	Description
queries	Array	List of match queries (required, 1-500 items). Each item has: name (optional), email (optional), linkedin (optional LinkedIn profile URL or username), company_name (optional), domain (optional), person_country (optional ISO-3166-1 alpha-2 code). At least one of name, email or linkedin is required per item.
enrich	Boolean	Set to true to hydrate matches with full contact data from the contacts database. Counts toward usage. Defaults to false.
limit	Integer	Maximum matches per query, range 1-20 (optional, defaults to 10).

Queries with a linkedin URL or an email are looked up by exact match first, LinkedIn before email (returned with match_score 100, and full contact data when enrich is true); on a miss they fall back to the other key, then to name/company matching. LinkedIn values can be full profile URLs (https://www.linkedin.com/in/jane-doe), URLs without the scheme (linkedin.com/in/jane-doe) or bare usernames; a value that is not a profile URL is ignored for that row.

Examples

Request

curl -X POST "https://api.discolike.com/v1/contacts/bulk-match" \
  -H "x-discolike-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"name": "Jane Doe", "company_name": "Acme Corp"},
      {"name": "John Smith", "domain": "techstartup.io"},
      {"email": "jane.doe@acmecorp.com"},
      {"linkedin": "https://www.linkedin.com/in/jane-doe"}
    ],
    "enrich": false,
    "limit": 5
  }'

Initial Response

{ "task_id": "e362cb75-35e2-4006-a239-3d87a7472872" }

An account can have three DiscoGen, bulk match, contact bulk match and segment tasks running at once. Starting another answers 429 with Retry-After: 60 until one finishes or is cancelled; see limits on work in progress.

Check Status

curl "https://api.discolike.com/v1/contactmatch/status/{task_id}" \
  -H "x-discolike-key: API_KEY"

{ "status": "in_progress", "progress": 45 }

Final Response

When enrich is false, matches contain lightweight results (persona_id, name, title, domain, company_name, match_score):

{
  "status": "completed",
  "progress": 100,
  "results": [
    {
      "query": { "name": "Jane Doe", "company_name": "Acme Corp", "domain": null },
      "matches": [
        {
          "persona_id": 12345678,
          "name": "Jane Doe",
          "title": "VP of Sales",
          "domain": "acmecorp.com",
          "company_name": "Acme Corporation",
          "match_score": 95.2
        }
      ]
    }
  ]
}

When enrich is true, matches contain full contact data (email, phone, social URLs, seniority, department, skills, etc.), the same fields as Search Contacts results.