To integrate a credit bureau report into your decisioning engine, you do four things in order: pull the report (bureau API or file), parse the response into structured fields, map bureau attributes to the policy variables your rules read, and define fallbacks for no-hit and thin-file cases through a data waterfall. Done right, a credit officer can change which bureau attribute drives a rule without filing an engineering ticket. This guide walks each step for consumer and commercial bureaus, and shows where the work usually breaks.
If you only take one thing: the hard part is not the API call. It's the mapping and the fallbacks. The API returns in seconds. Getting a consistent policy variable out of three bureaus that each name, scale, and structure the same concept differently is where teams lose weeks. So we'll spend most of the time there.
Step 1: Pull the bureau report (API vs file)
There are two ways to get a bureau report into your stack, and most lenders end up running both.
Bureau API (real-time pull)
You send an inquiry with the applicant's identifiers (name, national ID or SSN, date of birth, address; for commercial, the business registration number or DUNS), the bureau matches a subject, and returns a report synchronously. This is the path for instant decisioning. Consumer bureaus (Experian, Equifax, TransUnion) and commercial bureaus (D&B, Experian Business, Equifax Commercial) all expose REST or SOAP endpoints, usually returning XML or JSON.
What you handle at the API layer: authentication (mutual TLS or OAuth client credentials, often IP-allowlisted), the inquiry payload shape, permissible-purpose and consent flags, retries with idempotency so a network hiccup doesn't double-pull (bureau pulls cost money and can register as inquiries), and timeouts. Set an aggressive timeout (2 to 5 seconds) and treat a slow bureau as a no-hit for waterfall purposes rather than hanging the application.
File pull (batch / flat file)
Some bureaus, portfolios, and commercial data providers deliver via batch: you submit a list, they return a file (fixed-width, delimited, or XML) over SFTP. This suits portfolio monitoring, pre-screen, and markets where real-time API access isn't available. The parsing problem is the same; only the transport and latency differ.
| Dimension | Bureau API (real-time) | File pull (batch) |
|---|---|---|
| Latency | Seconds, synchronous | Minutes to hours |
| Use case | Application-time decisioning | Pre-screen, monitoring, backfill |
| Transport | REST / SOAP over TLS | SFTP, fixed-width or XML |
| Cost control | Per-inquiry, needs idempotency | Per-batch, easier to budget |
| Failure mode | Timeout, throttle | File late, schema drift |
Step 2: Parse the bureau response
A raw bureau report is dense and nested. A consumer file carries the score and reason codes, tradelines (accounts, balances, limits, payment history strings), public records, inquiries, and fragments of identity data. A commercial report carries the business score (PAYDEX or equivalent), payment experiences, financial stress and failure scores, legal filings, UCC liens, and corporate linkage. Parsing turns this into a flat, typed object your rules can read.
Three things break naive parsers:
- Nested and repeating structures. Tradelines and payment experiences are arrays of varying length. Your parser needs to aggregate them (count of accounts 90+ DPD in 24 months, total revolving utilization) rather than just read field one.
- Coded values. Bureaus encode status, account type, and reason in lookup codes. "DLA" or a numeric narrative code means nothing to a rule until you've resolved it against the bureau's code dictionary. Maintain those dictionaries as versioned reference data.
- Schema drift. Bureaus revise layouts. A file-pull parser that hard-codes column positions will silently misread the day a column moves. Validate every parse against an expected schema and fail loud, not silent.
The output of this step is a normalized bureau object: typed fields, resolved codes, and a set of derived attributes (utilization, worst delinquency, inquiry velocity, age of file). That derived layer is what your policy actually reads, which brings us to mapping.
Step 3: Map bureau attributes to policy variables
This is the step that decides whether your decisioning is maintainable. Your decisioning engine evaluates rules against named policy variables: credit_score, worst_delinquency_24m, revolving_utilization, months_since_oldest_trade, business_failure_score. Mapping is the contract that says: this policy variable is populated by that bureau attribute, transformed this way.
The reason this is hard across multiple bureaus: the same concept has different names, scales, and directions at each one. A consumer score might be 300 to 850 at one bureau and 0 to 999 at another. A commercial "risk" score might run high-is-good (PAYDEX, where 80 is prompt payment) or high-is-bad (a failure-probability score). If your rules read raw bureau fields, every policy change has to know which bureau it came from, and you've coupled credit policy to vendor plumbing. That coupling is the thing to design out.
The fix is a canonical attribute layer. You define policy variables once, in lender terms, and map each bureau's fields into them with explicit transforms (rescale, invert, bucket, default). Rules read the canonical variable and never touch a bureau field name. Swap a bureau, change one mapping, and the policy is untouched. This is the same separation that makes a decision engine outlast a hand-coded rules engine: policy logic sits above the data plumbing.
| Policy variable | Consumer bureau source | Commercial bureau source | Transform |
|---|---|---|---|
| credit_score | FICO / bureau score | Business risk score | Rescale to common band |
| risk_grade | Score bucket | PAYDEX / failure score | Bucket; invert if high-is-good |
| worst_delinquency_24m | Tradeline history strings | Payment experiences | Aggregate max DPD |
| utilization | Balance / limit across revolving | Balance vs terms | Sum and divide |
| file_age_months | Oldest trade open date | Business start / first filing | Date diff to today |
| inquiry_velocity | Hard inquiries 6m | Recent inquiries | Count, windowed |
Doing this without engineering tickets
In most stacks, every new bureau attribute or mapping change is a code change: a developer edits a parser, writes a transform, ships a release. Credit and risk teams wait in a backlog to adjust their own policy. That latency is why bureau integrations ossify.
Floowed ingests bureau data through the integration layer and exposes the mapping as configuration, not code. Credit and risk teams map a bureau attribute to a policy variable, set the transform (rescale, invert, bucket, default), and use it in a rule, in the same no-code surface where the rest of the policy lives. No release cycle to point a rule at a different bureau field. If you want the deeper pattern for authoring policy this way, see our no-code credit policy builder guide.
Step 4: Handle no-hit, thin-file, and fallbacks (the data waterfall)
Not every applicant returns a usable bureau report. Three cases you must design for explicitly:
- No-hit: the bureau can't match the subject. Common for new-to-country, young, or newly registered businesses.
- Thin-file: a match, but too little history to be meaningful (one tradeline, a brand-new business with no payment experiences).
- Stale or partial: a match with dated or incomplete data, or a timeout you've chosen to treat as a miss.
A data waterfall is the ordered fallback your decisioning engine walks when the primary source comes up empty. Try bureau A; on no-hit or low confidence, try bureau B; then an alternative-data source; then internal/cash-flow signals; then a defined terminal action (manual review or decline with a clear reason). The waterfall is itself policy, so it belongs in the same engine that runs your rules, with each branch logged.
A practical waterfall checklist
- Define what counts as a usable hit (minimum tradelines, minimum file age, score present).
- Order sources by hit rate, cost, and predictive lift, not just by contract.
- Set per-source timeouts; a slow source becomes a miss and the waterfall continues.
- Cap total bureau spend per application; stop the waterfall once you have enough to decide.
- For thin-file and no-hit, route to alternative signals before declining. Bank-statement cash-flow underwriting often decisions an applicant the bureau can't see at all.
- Record which source produced each policy variable, so the decision is auditable.
The thin-file path is where document intelligence earns its place. When the bureau is blank, the applicant's own paperwork (bank statements, financials, a photographed passbook) still carries income, cash-flow, and obligation signals. Floowed's document intelligence reads and analyses those documents at any quality, handwritten, scanned, photographed or skewed, into the same decision-ready variables your rules already read: average daily balance, DSCR, normalized income. So a no-hit doesn't force a manual queue; it triggers the next branch of the waterfall automatically. This is the kind of input that US-built IDPs tuned for pristine documents (Ocrolus, Rossum, Hyperscience) tend to choke on, and it's exactly the input thin-file lending depends on.
Step 5: Use bureau attributes in rules (score-agnostic)
Once a bureau attribute is mapped to a canonical policy variable, it's just another input to a rule. Your engine can threshold on it (credit_score < 600 declines), combine it (bureau score AND cash-flow DSCR), or route on it (thin-file to a different policy tree). Reason codes from the bureau flow through to the adverse-action explanation, because the engine records which variable and which value drove the call.
A core principle: stay score-agnostic. Bring any bureau score, or your own model, and the engine absorbs it unchanged as an input. Floowed orchestrates scores; it does not compete with scoring vendors. CredoLab, Zest, a bureau's own score, or your internal model all land as policy variables the same way. If you're weighing where the bureau score ends and the decision begins, our piece on credit decisioning vs credit scoring draws the line, and orchestrating a bureau score with your own model covers running them together.
This is the shape of it in production. Rene de Jesus, founder of Alon Capital: "Floowed reads the documents, runs our credit policy, and surfaces a decision in minutes." Bureau pull, document analysis, policy, and decision are one flow, not four tickets.
Consumer vs commercial bureaus: what changes
The four-step shape is identical. What differs is the data model. Consumer bureaus center on the individual: score, tradelines, delinquencies, inquiries. Commercial bureaus center on the entity: D&B's PAYDEX and DUNS-based linkage, Experian Business and Equifax Commercial scores, payment experiences across suppliers, UCC filings, and failure or stress scores. For commercial, identity matching is harder (legal name variants, registration numbers, corporate hierarchy), and a single applicant may be a guarantor whose consumer file you also pull. A good waterfall handles both: commercial bureau first for the entity, consumer bureau for the principal, document analysis for the cash flow, all mapped into one policy.
FAQ
What's the difference between a bureau API and a file pull?
An API returns a report synchronously in seconds, suited to application-time decisioning. A file pull delivers a batch over SFTP in minutes to hours, suited to pre-screen, monitoring, and markets without real-time access. Parsing and mapping are the same for both; only transport and latency differ.
How do you map attributes across bureaus that name things differently?
Define a canonical attribute layer: policy variables named in lender terms, populated by each bureau's fields through explicit transforms (rescale, invert, bucket, default). Rules read the canonical variable, never the raw bureau field, so swapping a bureau is a one-line mapping change, not a policy rewrite.
What is a data waterfall in bureau integration?
An ordered fallback the decisioning engine walks when the primary source returns no-hit or low-confidence data: bureau A, then bureau B, then alternative data, then internal cash-flow signals, then a terminal action. It is policy, so it lives in the engine and every branch is logged.
How do you decision a no-hit or thin-file applicant?
Route to alternative signals before declining. Document intelligence reads the applicant's bank statements and financials into cash-flow variables (average daily balance, DSCR, normalized income), letting you decision someone the bureau can't see. The waterfall triggers this branch automatically instead of dropping to a manual queue.
Do I have to use a specific bureau score?
No. A score-agnostic engine absorbs any bureau score or your own model unchanged as a policy variable. Floowed orchestrates scores rather than competing with scoring vendors, so you can run a bureau score and an internal model side by side in the same rules.
Get bureau data into your policy without a ticket
Pulling a bureau report is the easy part. The leverage is in mapping attributes to policy variables your credit and risk teams own, and in a waterfall that decisions the applicants the bureau can't see. Floowed does both in one no-code surface: bureau integration, document intelligence on thin-file inputs, and an audit-grade decisioning engine running your policy on all of it. Start free to wire a bureau attribute into a live rule, or book a demo to see the waterfall run end to end.