Most integration conversations start the same way. Someone asks whether the API supports soft pulls and hard pulls, we say yes, and everyone writes down “configurable inquiry type” as though the difference were a boolean on a request body.

It is not, and the teams that discover this late tend to discover it during implementation review, when the cost of restructuring a flow is highest.

The inquiry type is the smallest of four differences. The other three are what actually shape the integration.

The purpose comes first, not the flag

A soft inquiry supports qualification. A hard inquiry belongs to an application. That is not a preference about score impact — it is a statement about why the consumer’s file is being accessed at all, and it has to be established before the request is made, not attached to it afterward.

In practice this means the branch in your system happens earlier than most architectures put it. By the time you are assembling a request payload, you have already committed to a purpose, a disclosure, and a consent record. A design where the same endpoint is called with inquiry_type swapped at the last moment is a design where the disclosure the consumer saw and the inquiry that ran can drift apart under a refactor.

Put the branch where the consumer’s intent changes — the moment they move from “what might I qualify for” to “I am applying” — and the rest follows.

Both flows capture permission. They do not capture the same permission.

A qualification disclosure describes a non-score-impacting inquiry for the purpose of showing options. An application authorization describes a credit report pull in connection with a specific request for credit. Different text, different scope, and — this is the part that surprises people — a different retention story, because the second one is the artifact a downstream review will ask you to produce.

Design the consent event as its own record with its own identifier, and attach that identifier to the inquiry. The alternative, which we see often, is a boolean column named something like consented next to the applicant row. That column can tell you that someone agreed to something. It cannot tell you what.

The response is consumed by different systems

A prequalification response goes back into your own experience. You decide what to show, how to frame options, and whether to invite the consumer forward. The loop closes in your product.

A credit extension response goes into underwriting. It leaves the consumer experience entirely and enters a system with its own states, its own queue, and usually its own owner inside the business.

That asymmetry matters more than the payload shape. Prequalification wants low latency and a synchronous answer, because a person is waiting. Origination wants durability and traceability, because a process is waiting — and processes can tolerate a webhook far better than people can tolerate a spinner.

Building both on the same synchronous request/response assumption is how teams end up holding an HTTP connection open across an underwriting handoff.

The failure modes are not symmetric

When a qualification flow fails, the consumer sees a worse experience. When an origination flow fails, an application is in an ambiguous state, and somebody has to reconcile it.

So the two flows want different error handling. Qualification can degrade — fall back to a generic next step, invite the consumer to continue another way, keep the experience moving. Origination cannot silently degrade; an inconclusive result needs to become an explicit state that a human can act on, with enough event history attached to explain how it got there.

Teams that treat these as one code path usually inherit qualification’s error handling, because that is the flow they build first. Then origination fails quietly.

What this looks like when it is done well

The implementations that go smoothly share a shape:

  • Two entry points, not one endpoint with a flag. The purpose is encoded in which flow you are in.
  • Consent as a first-class record, referenced by the inquiry rather than implied by it.
  • Synchronous qualification, event-driven extension. Match the transport to who is waiting.
  • Shared identity resolution upstream of both, so the applicant is already resolved before either branch runs. This is the one piece that genuinely is common, and pulling it forward simplifies both sides.

None of this is exotic. It is mostly a matter of deciding the shape before the first integration sprint rather than during the third.

A note on what we are describing

The workflows above are how Revery Credit is designed to support these patterns. Which inquiry types, disclosures, and data elements apply to your product is a question for your legal and compliance teams, and the specifics get confirmed during technical discovery rather than assumed from a blog post.

If you are scoping this now, the useful conversation is not “does the API do soft and hard pulls.” It is “where in our journey does purpose change, and what do we have to be able to prove about it later.”