> For the complete documentation index, see [llms.txt](https://docs.goodfit.io/goodfit-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goodfit.io/goodfit-docs/apis/enrichment-api/contacts/handling-multiple-employments.md).
# Handling multiple employments
The [Contact Enrichment API](/goodfit-docs/apis/enrichment-api/contacts.md) 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:
```json
{
"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.
### Picking from the request
Send the `companyId` you picked to the original request:
```
POST /enrichment/enrich-contact/request/{requestId}/resolve
```
```json
{ "selectedCompanyId": "abc-123" }
```
This starts a new request for the employment you picked, with the original identity, `enrichPhoneNumber`, `syncToCRM` and external ids. It returns a new `requestId`; poll it as you would any other request. We resolve the person through their LinkedIn profile, so you aren’t billed for a second email lookup.
You get a `409` if the request hasn’t finished or didn’t end in `MULTIPLE_EMPLOYMENTS_FOUND`, and a `400` if the id isn’t one we offered.
### Resubmitting with your choice
You can also 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.
```json
{
"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.