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:

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:

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:

• Basic Latin
• Latin-1 Supplement
• Latin Extended-A

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:

📘

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:

📘

Character Sets

All consumer address fields accept the characters from:

• Basic Latin
• Latin General Punctuation Block

🚧

Invalid Symbols

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

• ! @ $ % & * < > ? | } { accept \ ^ ( ) = + ; : " ÷
• 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:

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

📘

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.