## 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:
1. Letters are uppercased (ie. `john` -> `JOHN`)
2. Diacritics are stripped (ie. `José` -> `Jose`)
3. 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.