Credit Reports

About Credit Reports

A CPE Credit Report is a single, stable, vendor-neutral JSON document describing a consumer's credit profile. CPE aggregates and normalizes consumer credit data from multiple upstream sources — including national credit bureaus — into one consistent shape. The same shape is returned by /pull, /phone, /getreport/json/{id}, and /getprofile/json/{profileid}.

A pull is the act of:

1. Authenticating the caller (apikey).
2. Resolving the caller's organization and entitlements.
3. Routing the request to the appropriate upstream source(s) based on the inputs you provided.
4. Normalizing the source response(s) into the CPE Credit Report schema.
5. Optionally attaching the CPE Score Forecast (when your organization is entitled).
6. Filtering tradelines by your organization's configured categories (when set).
7. Persisting the normalized report and generating shareable PDF / JSON / HTML URLs.
8. Returning the result.

Pull a Credit Report

Send the applicant's identity fields. The minimum required set is fname, lname, dob, city, and state — every other field, including ssn and address, is optional. CPE picks the optimal upstream request automatically based on what you provide.

Parameters

How CPE uses your inputs

CPE inspects your inputs and automatically routes the request through the strongest-match path within its upstream data network. There is no setting to flip on your side — the routing happens server-side:

• When an SSN is present, CPE uses the SSN as the primary match anchor.
• When there is no SSN but a street address is present, CPE uses the address as the match anchor.
• When only name + DOB + city/state are present, CPE matches on identity alone — the narrowest match window, but valid; it may return a thin file (reportStatus.code = "8").

The internal path that ran is echoed back in metadata.path for debugging / observability — it is not a value you set on the request.

Required fields at a glance

If any of the five minimum fields are missing, the request returns 402 Missing Parameters naming the missing fields.

Phone (Mobile) Method

Pull a credit report when all you have is the consumer's phone number and date of birth. Two endpoints, both under /phone. The general-purpose /pull endpoint is untouched — phone-driven pulls live entirely under /phone.

Step 1 — Authorize

Resolve the phone via the CPE phone-identity lookup, audit the lookup, SMS a 4-digit code to the consumer, and return an opaque auth_token.

Authorize response fields

Step 2 — Pull

Consume the token (verify the code, or accept a webhook-confirmed status) and pull the credit report.

You do not send dob, fname, lname, city, state, address, ssn, or zip — they were captured at /phone/authorize and ride along with the token. The token is bound to the identity captured at authorization time, so re-authorizing the same phone with a different identity cannot poison an earlier token.

Response. Identical shape to every other pull response (see Response Schema). The only phone-specific field is metadata.path = "phone".

Phone-flow errors

Repull & Caching

CPE deduplicates pulls to avoid double-charging:

• Each pull is fingerprinted by the consumer's stable profileid — a one-way identifier derived from name + DOB + city/state. SSN is intentionally excluded so the same consumer dedupes across SSN-bearing and SSN-less pulls.
• If you pull the same consumer again within 24 hours, the cached report is returned instead of issuing a new upstream pull.
• Cached responses are identical in shape to fresh ones; the files URLs point at the original report.
• Bypass rules: the cache expires 24 h after the original pull, and is bypassed automatically once the same consumer has been pulled three times within a 24-hour window — the next pull goes fresh upstream.
• /phone re-pull. The auth_token itself is a re-pull handle. POSTing the same token to /phone (no code needed) returns the cached report tied to that token until the 24 h dedup window closes.

Retrieve a Report by ID

Every completed pull returns a files block containing three ready-to-use URLs — one each for PDF, JSON, and HTML — that download the same report in different formats.

The {id} segment is an opaque, encrypted identifier issued by CPE. Use the URLs directly from the pull response's files block — do not construct them yourself. The encrypted URL itself is the access secret, so treat it like any other sensitive credential.

Retrieve a Report by profileid

Partners can hold a stable profileid for a consumer (returned in every pull/phone response under metadata.profileid) and use these URLs to fetch the most recent successful credit pull without tracking individual report IDs.

The profileid is a 32-character hex string that stays the same across every pull for the same consumer, so this endpoint always resolves to the freshest report without you tracking per-pull IDs.

Response Schema

A successful pull returns one JSON object. Top-level fields:

trades[] fields

CPE Score Forecast

The CPE Score Forecast is a proprietary predicted credit score (model cpe-heuristic-v4-v1) derived from the normalized CPE Credit Report. When your organization is entitled, the response includes a cpe_score block under creditScore. Non-entitled orgs see neither key.

Scorecard buckets

Report Filters

Each org can be configured to surface only certain tradeline categories. When a filter set is configured, the API restricts trades[] to matching accounts only. When no filter is configured, the full report is returned. Filters are set on your organization by your CPE account manager. The active filter set is echoed in metadata.report_filters.

Error Responses

Always read the message array on a 402 — it names exactly which field to fix.