Consumers

Overview

The Consumer API allows you to manage account data, including creating, reading, updating, and deleting records for a specific consumer belonging to an organization. The Consumer Service is core to the Bloom Platform and is used across other features such as Data Access, MLA, and Furnishing.


Endpoints / Models

Consumer

A consumer represents a single, unique, real-world human being.

Consumers can be affiliated with multiple organizations within Bloom, but no effort will be made to have a single canonical consumer that spans organizations. In other words, there may be one representation of John Doe for Organization A, and another separate representation of John Doe for Organization B.

Consumer Attributes

Consumers have multiple categories of attributes associated with them: Core, Name, Email Addresses, Addresses, Phone Numbers

The consumer object has each set of fields nested under it. Each category and it's set of fields are outlined below.

Core

The Core fields are the top-level fields of the consumer object, and they are the following:

FieldDescriptionExampleRequired?
ssnSocial Security Number of the consumer, see section below for more details123-45-6789Required only if date_of_birth not present
date_of_birthDate of birth for the consumer in the format of yyyy-MM-dd or yyyyMMdd1990-01-20Required only if ssn not present
incomeIncome of the consumer as a numeric whole number.100000:x:
ip_addressA known IP address of the consumer, in either IPv4 or IPv6 format.192.168.5.255:x:
Social Security Numbers

Social security numbers provided to the API must have 9 digits and only use either a space ( ) or hyphen/dash (-) as a delimiter for each part.

Valid examples of a Social Security Number accepted are:

  • 123-45-6789
  • 123 45 6789
  • 123456789

๐Ÿšง

Invalid SSNs

SSN with the first group of three digits (area group) between the range of 900-999 are considered invalid as described in SSA's documentation of SSN Randomization.

Partial Social Security Numbers

Partial SSN can be provided by zero filling the first 3 digits, the first 5 digits, or the last 4 digits.
Valid examples of partial SSNs that can be provided are:

  • 000-45-6789
  • 123-00-6789
  • 123-45-0000
  • 000-00-6789

Name

The Name (name) nested object within the consumer contains the following set of fields, with their respective descriptions:

FieldDescriptionExampleRequired?
first_nameFirst name of the consumerJohn:white-check-mark:
middle_nameMiddle name of the consumerHenry:x:
last_nameLast name of the consumerSmith:white-check-mark:
Normalization Rules

The following rules are applied to all fields of the Named object:

  1. Letters are uppercased (ie. john -> JOHN)
  2. Diacritics are stripped (ie. Josรฉ -> Jose)
  3. Non-Letter characters are replaced with spaces

๐Ÿ“˜

Character Sets

All consumer name fields accept characters in the following character sets:

Emails

The Emails (emails) field contains an array of email addresses that the consumer has. Each object in the array has the following set of fields:

FieldDescriptionExampleRequired?
email_addressThe full email address string of the consumer[email protected]:white-check-mark:
typeType of email (personal or work)personal:white-check-mark:
primaryIndicator for primary email of consumer (true or false)true:white-check-mark:

๐Ÿ“˜

Format & Character Sets

The email address field supports the format described by the IEFT RFC 5322 standard.

In short, a valid email address consists of a local and domain section, separated by an @ character.

Addresses

The Addresses (addresses) field contains an array of addresses that the consumer is associated with. Each object in the array has the following set of fields:

FieldDescriptionExampleRequired?
line1Address basic line info123 Street:white-check-mark:
line2Address complementary infoApt 1:x:
cityPostal cityBoston:white-check-mark:
state_codePostal state codeMA:white-check-mark:
zipcodePostal zip code12345:white-check-mark:
typeType of address (personal or work)personal:x:
primaryIndicator for primary address of consumer (true or false)true:white-check-mark:

๐Ÿ“˜

Character Sets

All consumer address fields accept the characters from:

๐Ÿšง

Invalid Symbols

Below are a list of symbols that are not accepted for addresses:

  • ! @ $ % & * < > ? | } { [ \ ] \ ^ ( ) = + ; : " รท
  • Leading spaces

Phones

The Phones (phones) field contains an array of phone numbers that the consumer has access to. Each object in the array has the following set of fields:

FieldDescriptionExampleRequired?
phone_numberPhone number of the consumer+1 (123) 456-7890:white-check-mark:
typeType of contact (home, personal, or work)work:white-check-mark:
primaryIndicator for primary contact of consumer (true or false)true:white-check-mark:

Valid phone numbers must adhere to the NANP structure in 10-digit notation.

  • May be prefixed with country code
    • Note that only US phone numbers are accepted, as is by US credit bureaus (country codes other than +1 or 1 are rejected)
  • Phone number may have the area code (first 3 digits) parenthesized.

Some possible variations of this format are outlined below:

  • 1234567890
  • 123-456-7890
  • 123 456 7890
  • (123) 456 7890
  • (123) 456-7890
  • (123)456-7890
  • 123.456.7890
  • 123 456-7890
  • +1123 456-7890
  • 1123 456-7890
  • +1(123) 456-7890
Normalization Rules

The following rules are applied to the phone_number fields of the Phones object:

  1. Country code is stripped (ie. 1 123 456-7890 -> 123 456-7890)
  2. Non-numeric characters are stripped (ie. 123 456-7890 -> 1234567890)

Diagram


image

Examples of consumers in the Consumer API

๐Ÿ“˜

To start using the Consumer Hub, you must create a consumer.

To get information on how to create a consumer user Consumer Hub please refer to Create or update Consumer section of the API Reference tab.

Once you have created a consumer, you can manage their personal identification information.


Credit Bureaus and Reporting

When accessing historical consumer credit information, the major bureaus perform a โ€œfuzzy matchโ€ based on the information that has been submitted.

The bureaus report the following success rate in identifying the correct matching credit record based on being provided with the following information:

  • 83% Name + Address
  • 90% Name + Address + DOB
  • 82% Name + Address + Last 4 SSN
  • 91% Name + Address + DOB + Last 4 SSN
  • 93% Name + Address + Full SSN
  • 93% Name + Address + DOB + Full SSN

Because of the above, credit bureaus will search for a matching consumer record in their repositories based on any combination of two or more of the above.