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 its set of fields are outlined below.

Core

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

Field	Description	Example	Required?
`ssn`	Social Security Number of the consumer, see section below for more details	`123-45-6789`	Required only if `date_of_birth` not present
`date_of_birth`	Date of birth for the consumer in the format of `yyyy-MM-dd` or `yyyyMMdd`	`1990-01-20`	Required only if `ssn` not present
`income`	Income of the consumer as a numeric whole number.	`100000`	❌
`ip_address`	A known IP address of the consumer, in either IPv4 or IPv6 format.	`192.168.5.255`	❌

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

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:

Field	Description	Example	Required?
`first_name`	First name of the consumer	John	✅
`middle_name`	Middle name of the consumer	Henry	❌
`last_name`	Last name of the consumer	Smith	✅

Normalization Rules

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

Letters are uppercased (ie. john -> JOHN)
Diacritics are stripped (ie. José -> Jose)
Non-Letter characters are replaced with spaces

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:

Field	Description	Example	Required?
`email_address`	The full email address string of the consumer	`john.doe@example.com`	✅
`type`	Type of email (`personal` or `work`)	`personal`	✅
`primary`	Indicator for primary email of consumer (`true` or `false`)	`true`	✅

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:

Field	Description	Example	Required?
`line1`	Address basic line info	`123 Street`	✅
`line2`	Address complementary info	`Apt 1`	❌
`city`	Postal city	`Boston`	✅
`state_code`	Postal state code	`MA`	✅
`zipcode`	Postal zip code	`12345`	✅
`type`	Type of address (`personal` or `work`)	`personal`	❌
`primary`	Indicator for primary address of consumer (`true` or `false`)	`true`	✅

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:

Field	Description	Example	Required?
`phone_number`	Phone number of the consumer	`+1 (123) 456-7890`	✅
`type`	Type of contact (`home`, `personal`, or `work`)	`work`	✅
`primary`	Indicator for primary contact of consumer (`true` or `false`)	`true`	✅

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)

Diagram

Examples of consumers in the Consumer API

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.