# US Consumer Reports

The US Consumer Reports API provides access to comprehensive credit information for individual consumers in the United States. This service allows you to retrieve consumer credit reports, trade lines, negative information (collections, bankruptcies), and employment details.

## Data Dictionary

Use the data dictionary to understand all fields available in US Consumer Reports:

| Report Type | Data Dictionary Files | View Online | Download |
|  --- | --- | --- | --- |
| US Consumer Report | Standard | View Online | Download PDF |


The data dictionary provides detailed information about:

- All available fields in the response
- Field descriptions and data types
- Possible values for enumerated fields
- Nested object structures


## Overview

US Consumer Reports are available through the `/consumers/tryReport` endpoint with two template options that determine the type and depth of information returned:

### Report Templates

#### **Basic Template**

- **Purpose:** Pre-screening and preliminary assessments
- **Credit Score:** Not included
- **Footprint:** No inquiry left on consumer's credit file
- **Use Cases:**
  - Pre-qualification checks
  - Marketing and offer targeting
  - Initial credit evaluations that don't require a full hard inquiry


**Key Benefit:** Does not impact the consumer's credit score or leave a record of the inquiry on their credit file.

#### **HardCheck Template**

- **Purpose:** Credit decisioning and formal credit applications
- **Credit Score:** Included in response
- **Footprint:** Leaves an inquiry on the consumer's credit file
- **Use Cases:**
  - Formal credit applications (loans, mortgages, credit cards)
  - Employment background checks
  - Tenant screening (when credit score is required)
  - Any credit decision requiring a full credit assessment


**Important:** This template leaves a record (footprint) on the consumer's credit file that other lenders can see. Use only when making an actual credit decision.

## Selecting a Template

Specify the template using the `template` query parameter:

```
GET /v1/consumers/tryReport?countries=US&template=basic&firstName=John&lastName=Doe...
```

**Values:**

- `basic` (default) - Returns report without credit score, no footprint
- `hardcheck` - Returns report with credit score, leaves footprint


If no template is specified, `basic` is used by default.

## Required Search Criteria

To retrieve a US Consumer Report, provide:

**Mandatory:**

- `countries=US` - Country code
- `firstName` - Consumer's first name
- `lastName` - Consumer's last name


**Highly Recommended (for accurate matching):**
At least one of the following to ensure unique consumer identification:

- `personNumber` - Social Security Number (SSN)
- `dateOfBirth` - Date of birth (YYYY-MM-DD format)
- Complete address (`street`, `city`, `postalCode`, `province`)


**Optional:**

- `telephone` - Telephone number


## Response Structure

The response includes:

- **Consumer Information** - Name, date of birth, gender, consumer ID, current address
- **Contact Information** - Current and previous addresses with dates
- **Credit Score** (HardCheck only) - Current credit rating information
- **Negative Information** - Collections, bankruptcies, delinquencies, charge-offs, repossessions
- **Trade Lines** - Account history including credit cards, loans, mortgages with payment history
- **Additional Information**:
  - Active account summaries (revolving, installment, other accounts)
  - Employment information
  - Inquiry history
  - Search criteria used


## Search Criteria Discovery

Use the `/consumers/tryReport/searchcriteria` endpoint to discover available search parameters and validation rules for US consumer reports:

```
GET /v1/consumers/tryReport/searchcriteria?countries=US
```

This endpoint returns the complete list of supported search criteria fields, their types, and validation requirements.

## Best Practices

1. **Choose the Right Template:**
  - Use `basic` for pre-screening and marketing purposes
  - Use `hardcheck` only when making actual credit decisions
2. **Provide Sufficient Search Criteria:**
  - Always include SSN or date of birth for accurate matching
  - Include full address when SSN is not available
3. **Handle Missing Data:**
  - Not all fields are available for every consumer
  - Implement your integration to gracefully handle missing or partial data
  - Check for field presence before accessing nested properties
4. **Regulatory Compliance:**
  - Ensure you have proper consent before running a `hardcheck` report
  - Comply with the Fair Credit Reporting Act (FCRA) requirements
  - Maintain records of consumer consent and permissible purpose


## Service Lines

- **Basic Template:** `csc_con_rep_US`
- **HardCheck Template:** `csc_con_rep_US_hardcheck`


Ensure your account has the appropriate service line enabled for the template you wish to use.

## Related Endpoints

- **[GET /consumers/tryReport](/connect-apis-catalog/product-catalog/consumermisc/consumerandmisc)** - Retrieve US consumer report
- **[GET /consumers/tryReport/searchcriteria](/connect-apis-catalog/product-catalog/consumermisc/consumerandmisc)** - Discover available search criteria


## Support

For questions about US Consumer Reports or to enable this service on your account, contact your Creditsafe account manager.