A lending decision rarely rests only on what the applicant writes in the form. Most decision flows ask a credit bureau what it knows about the person: existing loans, payment history, past inquiries, often a score. This article looks at credit bureau API integration from the lender's side: what you send and receive, the legal basis, what to do when the bureau does not answer, how to store reports, and how to test all of it.

It describes public sources as an overview, not legal advice. Data protection and consumer credit rules differ by country and change over time: check the current rules, and the contract with your bureau, before you build them into a process.

What the lender sends and receives

An inquiry identifies the person and says why you ask: identification data, the product or purpose, and your own application reference. The answer is a report, and sometimes a score. What a report contains depends on the bureau. Two public examples show the range.

In Romania, a bank's information notice on data processing in the Biroul de Credit system (BRD, 2019) describes Biroul de Credit as the private company that runs the system. Its participants are credit institutions, non-bank financial institutions, insurance companies, and debt collection companies that have signed a participation contract. The data includes:

  • identification data and the employer;
  • credit products: type, amounts, payment status, arrears, days overdue, closure date;
  • events in a product's life, such as restructuring, refinancing, or assignment;
  • co-debtors and guarantors, insolvency proceedings, and the number of inquiries.

The same notice says the bureau may calculate a FICO® Score between 300 and 850 for participants, and that data is kept for four years from its update.

In Germany, SCHUFA describes its credit checks as delivered in real time and integrated into the customer's processes, with data that comes from partners on a reciprocal basis.

Reciprocity matters for the design. An integration usually has two flows, not one: the inquiry at decision time, and the reporting of your own loans and payments back to the bureau over the life of the loan. Teams often plan the first and forget the second.

The interface details are not on the public pages cited here; expect them from the bureau during onboarding. Keep them behind an adapter: your decision logic works with your own report model, and only the adapter knows the bureau's format. A second bureau, or a new version of the first, then changes one component.

The legal basis for the inquiry depends on the country and the bureau. The BRD notice above, for example, bases the processing on the legitimate interest of the participants and the bureau. Record the basis that applies with every inquiry.

The decision itself has its own rules. Article 22 of the GDPR gives a person the right not to be subject to a decision based solely on automated processing, including profiling, that has legal or similarly significant effects. It allows exceptions: when the decision is necessary for a contract, authorised by law with safeguards, or based on explicit consent. For the contract and consent cases, the controller must offer at least human intervention, a way to express a point of view, and a way to contest the decision.

The Court of Justice of the EU applied this to credit scores. In case C-634/21 (SCHUFA, 7 December 2023), it held that a bureau's score is an automated individual decision when the lender gives it a determining role in granting credit.

The new EU Consumer Credit Directive, (EU) 2023/2225, applies from 20 November 2026. Its recitals say that the creditworthiness assessment should use at least income and expenses, should not use special categories of personal data or information from social networks, and, when it involves automated processing, should give the consumer human intervention, an explanation, and a review. They also say creditors should consult credit databases, and that a consumer refused on the basis of a database consultation should be told the result, the database, and the categories of data used.

For the software, this means:

  • every inquiry stores its legal basis and the application it belongs to;
  • the decision keeps the reasons, not only the outcome;
  • the flow has a human review step that can change the result;
  • the system can produce the explanation and the bureau details for a refused applicant.

Timeouts and fallbacks in a credit bureau API integration

The bureau call is a remote dependency on the critical path of every application. It will be slow or unavailable at some point, and the flow must say what happens then.

Do not retry blindly. The Romanian notice lists the number of inquiries among the data a bureau keeps, so a retried request can show up as a second inquiry in the person's record. Record the inquiry before the call, with your own inquiry reference, and check that record before you ask again. If an earlier inquiry is still pending or has timed out, the bureau may already have recorded it, so do not resend it automatically. Reconcile it with the bureau through the inquiry reference, where the bureau supports such a lookup; otherwise route the application to manual review.

Java
Optional<CreditInquiry> existing = inquiries.findByApplication(applicationId);
if (existing.isPresent()) {
  CreditInquiry earlier = existing.get();
  if (earlier.hasReport()) {
    return earlier.report();                     // a retry does not send a second inquiry
  }
  // pending or timed out: the bureau may have recorded it, so never resend automatically
  return reconciler.lookUp(earlier.reference())  // empty if not found or no lookup exists
      .map(body -> inquiries.complete(earlier, body))
      .orElseThrow(() -> new ManualReviewRequired(earlier.id()));
}
CreditInquiry inquiry = inquiries.save(CreditInquiry.pending(applicationId, legalBasis));
HttpRequest request = HttpRequest.newBuilder(bureauUri)
    .timeout(Duration.ofSeconds(10))             // an example value, set per bureau and product
    .POST(HttpRequest.BodyPublishers.ofString(mapper.toBureauRequest(inquiry)))
    .build();
try {
  HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
  return inquiries.complete(inquiry, response.body());   // the raw body is stored as received
} catch (HttpTimeoutException e) {
  inquiries.markTimedOut(inquiry);               // the bureau may still have recorded it
  throw new BureauUnavailable(inquiry.id(), e);
}

What happens after the timeout is a business decision, not a technical one. The usual options:

  • Check again later, with a limit, while the application waits: reconcile the open inquiry by its reference, where the bureau supports that, instead of sending a new one.
  • Manual review: a person decides with the data available.
  • Decline only if the policy says so. Refusing because a remote system was down affects the applicant, so treat it as a rule that someone has approved, not as a default.

In a BPMN decision flow, this is a service task with an interrupting timer boundary event that leads to a user task for review. Add a circuit breaker in front of the adapter so that an outage sends applications to the fallback at once, instead of making each one wait for its own timeout.

Storing reports

A decision must be explainable months later, so store what it was based on:

  • the raw response exactly as received, never changed;
  • the parsed fields, with the version of the mapping that produced them;
  • the time of the inquiry, the inquiry reference, and the legal basis;
  • a link from the decision to the report it used.

A report is personal data about a person's finances. Limit access to the roles that need it, log who opened it, encrypt it at rest, and keep it out of application logs. Set your own retention period from your obligations: the bureau's retention period is the bureau's, not yours. Decide also how long a report stays valid for a decision, and when the flow must ask again.

Testing against a sandbox

Whether a bureau offers a test environment and test persons is something to ask during onboarding. Either way, never test with the data of real people.

Most tests do not need the bureau at all:

  • Adapter tests with synthetic responses: a full report, no record found, a thin file, arrears, several possible matches, a malformed answer.
  • Decision flow tests with a fake bureau that can be told to be slow, fail, or time out, to check that every fallback path is reached.
  • Reporting tests for new loans, payments, arrears, corrections, and closures.

Run a small set against the bureau's test environment, if there is one, before every release that touches the adapter.

How we can help

We build lending software with credit bureau integration: requests to a credit bureau and the reports that come back, where the bureau offers an interface, kept behind a clear adapter, and decision flows with timeouts and human review.