Auditing and Editing a Person's Identities

Updated 4 months ago by Alexandra McIlraith

DotAlign has several ways of smartly deduplicating people, and automatically detecting when new information should be assigned to an existing contact vs. when a separate person should be created. While this is useful, it can make mistakes or show surprising information. When you see something unexpected about a person's identity, DotAlign's auditing tools are useful to look at to verify the source and trustworthiness of surprising information.

Auditing Identities

To audit information about a person's identities:

  1. Go to the person identity auditing endpoint in Swagger (GET api/people/{personId}/identifiers) and click to try it out
  2. Enter the following parameters:
    1. Any valid personId (also called an "identifier" or "identity"), e.g. name, email address, or relevant md5
    2. The number corresponding to the relevant team context (in most cases, this will be "1")
    3. The number of team members whose data contributions should be considered (in most cases, this number should match the number of members in the team so as to get all relevant information)
  3. Click "Execute". The API response will include information about each identifier associated with that person, as well as about each identifier pair ("tuple") involving those identities.

Some names and email addresses are not accepted as valid personIds, i.e. are not treated as being representative of a real, unique person. For example, "John Smith" is treated as a common name and will therefore instead be listed as a "disqualifier", helping the application avoid merging every "John Smith" into a single person.

The tuples indicate how each identifier is connected to the person's basket of identities, and are therefore most useful to examine when trying to verify the source and trustworthiness of surprising information. Each tuple consists of two identifiers (e.g. an email address and a name) and information about where those identifiers have been found together. Some tuples also include information about whether any data contributor has manually verified (or negated) that pair.

Editing Identities, Names, and Email Addresses

Identity Edits

There are a number of edits you can make related to person identities:

  • Merge separate people into a single record, as detailed here
  • Split a person into two or more entities, as detailed here
  • To add an identity that may be missing, submit it to the POST api/people/requalify endpoint
  • To remove an identity and mark it as unsuitable to identify any person, submit it to the POST api/companies/disqualify endpoint. Examples may include:
    • Automated sender email addresses that may have slipped through the system's filtering logic
    • Junk names, including typos

Name and Domain Edits

Any person might have multiple names and email addresses associated with them. DotAlign automatically determines what seems likely to be the best name and the best email address for the person, but you can override this. You can also mark an email address as stale and no longer current.

To choose the name that should be used as the best name for the person, submit one of the existing names for the person to the POST api/people/preferredname endpoint. If this is a common name that may be shared by multiple people, e.g. "John Smith", you can also specify an email address (or other identifier) that will help disambiguate which of the many "John Smith" contacts you are referring to.

Similarly, to set the best email address for a person, submit one of the existing emails for the person to the POST api/people/emailaddresses endpoint.

The POST api/people/emailaddresses endpoint also allows you to update an email address as stale or no longer reachable, despite being correctly associated with the person. To do this, simply specify the email in question and set the "isCurrent" boolean to false.

How Did We Do?