POST/v3/live/person/asynchronous/deep-match

Submit a Deep Match batch

Submit up to 1,000 rows of signals - name, location, emails, phones, employers, healthcare identifiers - and resolve each row to a subject: a person in the AggKnowledge dataset, a person we can identify but hold no record for, or a healthcare professional. Every criterion is evaluated for every row and the ones that fired are reported on the row's match trail. A row the signals cannot narrow to one subject comes back MULTIPLE_CANDIDATES with up to three candidates, each with its own evidence. Resolution is asynchronous; poll GET /person/asynchronous/deep-match/{id} for results. Billed one credit per row that resolves to a subject, however much evidence that row returned. Rows that come back NO_MATCH, MULTIPLE_CANDIDATES, SUPPRESSED or FAILED are not charged.

Version
v3
Rate limit
Tier 3 · 10–200 rps by plan
Billing
DEEP_MATCH · Submit a Deep Match batch

Request body

  • rowsobject[]Optional
    Rows to resolve. At most 1,000 per batch.
    • aggkCompanyIdsstring[]Optional
      AggKnowledge company IDs of employers, current or past.
    • collegeNamesstring[]Optional
      Schools the person attended. Accepted and recorded, but not yet used in matching — supplying a college neither improves nor degrades a row's result today.
    • countrystringOptional
      Country the person is based in.
    • emailsstring[]Optional
      Known email addresses. The strongest signal available.
    • employerDomainsstring[]Optional
      Employer web domains, current or past.
    • employerNamesstring[]Optional
      Employer names, current or past.
    • fullNamestringOptional
      Full name, as one string.
    • gmcsstring[]Optional
      GMC reference numbers (UK General Medical Council).
    • socialProfilestringOptional
      Professional social profile URL.
    • metadataobjectOptional
      Your own identifiers for this row, echoed back verbatim on the create response and on every result. Never matched on, so it cannot change how a row resolves. At most 10 properties, each value at most 500 characters and 4096 bytes in all as JSON.
    • npisstring[]Optional
      National Provider Identifiers. Resolves the row to a healthcare professional directly, whether or not that professional has a person record.
    • orcidsstring[]Optional
      ORCID researcher identifiers.
    • phonesstring[]Optional
      Known phone numbers, in any format. Normalised before matching.
    • rppssstring[]Optional
      RPPS numbers (Répertoire Partagé des Professionnels de Santé).
    • stateOrProvincestringOptional
      State or province the person is based in.
Headers
x-api-key Required · API key for authentication

Response

  • batchIdstring
    Batch identifier, to poll for results.
  • rowCountinteger (int32)
    Rows accepted. Credits are charged per row that resolves to a subject, so this is an upper bound on what the batch will cost.
  • rowsobject[]
    One entry per submitted row, in submission order, carrying the rowId to join results on.
  • statusenum DeepMatchBatchStatus
    Batch status at submission.

Status codes