Contact Information Standardization Details

A guide to the mostly simple, occasionally convoluted standardization process.

Phones

Nols-api uses a library for phone standardization.

Default Case

  • Standardization happens by default on phone create or update, invalid phones are saved as is. This is typically used in a non-interactive setting.
  • Standardization only happens when calling information (phone_number, extension) is changed not meta information (type, is_current, etc).
  • If the calling information can be standardized, is_standardized = True. If not, is_standardized = False. Any value of is_standardized in input will be overridden.
  • In all cases standardization_attempted_at is set to current date/time in UTC.

Raise Error for Invalid Input

  • You can raise errors on invalid input by setting raise_error_for_invalid = True. This is typically used in an interactive setting where the user has the opportunity to update input and attempt again.
  • Valid input will be saved as above, invalid input will return a validation error (HTTP code 400).

Skipping Standardization

  • You can skip standardization altogether by setting skip_standardization = True; is_standardized will be set from input value (default is False). This is typically used in an interactive setting when the user explicitly wants to save invalid input.
  • If you skip standardization, standardization_attempted_at will be set to current date/time in UTC when is_standardized is False, null when is_standardized is True: null marks 'standardized' but unverified entries.

Periodic Standardizing Attempts on Existing Phones

  • Standardization is skipped when is_standardized is True unless calling information changed.
  • Standardization is skipped when standardization_attempted_at happened 'recently' (default is within 30 days) unless calling information changed.
  • If you want to standardize an existing phone without resorting to modifying calling information, update the phone with is_standardized set (value doesn't matter, it will be overridden anyway).

Emails

Nols-api uses a library for email standardization.

Default Case

  • Standardization happens by default on email create or update, invalid emails are saved as is. This is typically used in a non-interactive setting.
  • Standardization only happens when address information is changed not meta information (note, is_current, etc).
  • If the email address can be standardized, is_standardized = True. If not, is_standardized = False. Any value of is_standardized in input will be overridden.
  • In all cases standardization_attempted_at is set to current date/time in UTC.

Raise Error for Invalid Input

  • You can raise errors on invalid input by setting raise_error_for_invalid = True. This is typically used in an interactive setting where the user has the opportunity to update input and attempt again.
  • Valid input will be saved as above, invalid input will return a validation error (HTTP code 400).

Skipping Standardization

  • You can skip standardization altogether by setting skip_standardization = True; is_standardized will be set from input value (default is False). This is typically used in an interactive setting when the user explicitly wants to save invalid input.
  • If you skip standardization, standardization_attempted_at will be set to current date/time in UTC when is_standardized is False, null when is_standardized is True: null marks 'standardized' but unverified entries.

Periodic Standardizing Attempts on Existing Emails

  • Standardization is skipped when is_standardized is True unless calling information changed.
  • Standardization is skipped when standardization_attempted_at happened 'recently' (default is within 30 days) unless calling information changed.
  • If you want to standardize an existing email without resorting to modifying delivery information, update the phone with is_standardized set (value doesn't matter, it will be overridden anyway).

Addresses

Nols-api uses a web service to standardize mailing addresses. The service only standardizes addresses from United States and Canada; for other countries it skips standardization and saves input data as is.

Default Case

  • Standardization happens by default on address create or update, invalid addresses are saved as is. This is typically used in a non-interactive setting.
  • Standardization only happens when delivery information (line1, city, etc) is changed not meta information (type, end_date, etc).
  • US and Canada addresses get is_standardized = True if valid. If not, is_standardized = False. Any value of is_standardized in input will be overridden. standardization_attempted_at is set to current date/time in UTC.
  • Non-US, non-Canada addresses get is_standardized = False, standardization_attempted_at = null.

Raise Error for Invalid Input

  • You can raise errors on invalid input by setting raise_error_for_invalid = True. This is typically used in an interactive setting where the user has the opportunity to update input and attempt again.
  • There are four possible outcomes:
    • Service returns one standardized result: information is saved with is_standardized = True and standardization_attempted_at = current date/time in UTC.
    • Service returns one non-standardized result: api returns a validation error (HTTP code 400).
    • Service returns more than one result: api returns a list of possible matches (HTTP code 300). There may be zero or more standardized addresses in the list.
    • There were network/service issues: api saves the input as is and marks it for later standardization (is_standardized = False, standardization_attempted_at = null).

Skipping Standardization

  • You can skip standardization altogether by setting skip_standardization = True; is_standardized will be set from input value (default is False). This is typically used in an interactive setting when the user explicitly wants to save invalid input or input from a list of possibilities.
  • If you skip standardization, standardization_attempted_at will be set to current date/time in UTC when is_standardized is False, null when is_standardized is True: null marks 'standardized' but unverified entries.

Periodic Standardizing Attempts on Existing Addresses

  • Standardization is skipped when is_standardized is True unless delivery information changed.
  • Standardization is skipped when standardization_attempted_at happened 'recently' (default is within 30 days) unless delivery information changed.
  • If you want to restandardize an existing address without resorting to modifying delivery information, update the address with is_standardized set (value doesn't matter, it will be overridden anyway).