Concept

References

Every person, organisation and event has a UUID reference. Filters take references, never names.

What a reference is

A reference is a lowercase UUID, for example 3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01. It's stable: the same organisation keeps the same reference for as long as it's in the data, so you can store it in your CRM and look the record up again later.

Getting a reference from a name

Organisation, person and job title filters need a reference. There are two ways to get one.

You haveUseReturns
A company name or a job titleresolve_search_terms or GET /v1/search/suggestionsfield, value and label per match, ready to use as a filter
A person's namesearch_people or GET /v1/profilesMatching profiles, each with its reference
A company name, and you want the record itselfsearch_companies or GET /v1/organisationsMatching organisations, each with its reference
A suggestion, used as a filter
{
  "field": "Organisation",
  "value": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01",
  "label": "Halberd Industrial Group"
}

Matching is by substring

Name lookups match a substring of the stored name. A short, distinctive fragment finds more than a full legal name with a suffix. If nothing comes back, drop words like Limited or plc and try again.

Related