Handling multiple employments

The Contact Enrichment API is an employment API: it returns a person at a company. Job title, start date and work email all describe one specific employment, so we need to know which job you mean.

Most of the time that's obvious — the person has one role, or you told us the company. When someone holds more than one role and nothing in your request picks one out, we hand the choice back to you rather than guessing at it.

This is common among the kind of people you're most likely to look up: founders and directors of more than one company, advisors and board members alongside an operating role, consultants with several concurrent clients.

How we choose an employment

We work down this order and stop at the first thing that identifies exactly one employment:

1. selectedCompanyId, matched exactly.

2. The person has only one employment on record.

3. companyDomain, matched on the registrable domain — so careers.acme.com matches www.acme.com.

4. companyName, matched after ignoring case, spacing and a trailing Ltd, Inc, LLC and the like — so Acme, ACME Ltd and Acme, Ltd. all find the same company. Ignored if it matches more than one of their employers.

5. The domain of the workEmail you supplied.

Anything less exact than that returns the options rather than guessing. If both hints are supplied, the domain wins.

Tip — Sending companyDomain on the first request avoids this round trip in almost all cases. It's worth including whenever you have it — from the person's work email, the CRM record, or the form they filled in.

The response

When we can't narrow it down, the request still completes. found is false, reason is MULTIPLE_EMPLOYMENTS_FOUND, and we return who we identified along with every employment you could have meant:

{
  "found": false,
  "reason": "MULTIPLE_EMPLOYMENTS_FOUND",
  "linkedInUrl": "http://www.linkedin.com/in/some-handle",
  "firstName": "Sam",
  "lastName": "Rivers",
  "employments": [
    {
      "companyId": "abc-123",
      "companyName": "Acme Inc",
      "companyDomain": "acme.com",
      "jobTitle": "Head of Data",
      "startDate": "2024-01-15"
    },
    {
      "companyId": "def-456",
      "companyName": "Globex",
      "companyDomain": "globex.com",
      "jobTitle": "Advisor",
      "startDate": "2021-06-01"
    }
  ]
}

Each entry carries enough to tell the roles apart and to send one back:

Field	Notes
companyId	GoodFit's ID for the company. Send this back as selectedCompanyId.
companyName	The company's name.
companyDomain	The company's primary domain.
jobTitle	Their title in this role.
startDate	When this role started, as YYYY-MM-DD.

The person is identified, so you can show these options to a user, or match them against your own records and pick one automatically. Nothing is added to your dataset and no contact credit is charged.

Resubmitting with your choice

Submit a new request for the same person, naming the employment you want. Either:

• Pass the companyId of your chosen employment as identity.selectedCompanyId — the most precise option, since we return the exact value to send back; or

• Pass identity.companyDomain or identity.companyName for the employer you mean.

{
  "identity": {
    "linkedInUrl": "http://www.linkedin.com/in/some-handle",
    "selectedCompanyId": "abc-123"
  },
  "syncToCRM": true
}

The resubmission is a fresh request with its own requestId, and returns the contact at the employment you chose. Poll it exactly as you would any other request.

Send linkedInUrl back with your resubmission. We return it above precisely so you can. Resubmitting with only workEmail makes us look the person up from scratch, which is slower and — if you were found by email lookup — bills you a second time for an answer we already have.

Designing for it

If a person can reach this API from a webform or an event list, they can hit this case, so it's worth handling rather than treating as an error.

• Where someone is in the loop, present employments as a choice — the job titles and company names are usually enough for them to recognise the right one.

• Where nothing is, match companyDomain against whatever company context you already hold, and resubmit with selectedCompanyId. Fall back to logging the options for review rather than picking arbitrarily; the wrong employment means the wrong work email.

• Either way, send companyDomain on the first request whenever you can, and this path stays rare.