Skip to main content

​
Personal Loans Platform API Integration

The Personal Loans Platform API enables partners to submit a lead and receive a summary of prequalified offers (when available). This is a server-to-server integration: requests must originate from partner backend systems, and results are typically delivered asynchronously via callback (with optional polling via GET).
Key distinction vs student loan refi: Personal Loans leads are not associated with a Credible user account. If the same consumer later visits Credible organically with the same email, there is no linkage to the prior Platform API submission and they must submit a new prequalification form.

​
What You’re Building (High-Level)

A complete Platform API integration generally includes:
  • Auth: obtain and refresh OAuth2 access tokens
  • Lead submission: send a complete lead payload (borrower + loan + required context)
  • Async delivery: receive results via a partner callback endpoint
  • Lifecycle tracking: store partnerLeadId and lead uuid to correlate events
  • Offer rendering: display product ranges and required notices (including adverse action notice when applicable)
  • Selection tracking: when a user clicks a product’s lenderOfferUrl, the product is marked as selected

​
End-to-End Flow

​
Primary flow (async callback)

+------------------+         +------------------+         +----------------------+
| Partner Frontend |         | Partner Backend  |         | Credible Platform    |
+------------------+         +------------------+         +----------------------+
        |                             |                              |
        | 1) User enters info         |                              |
        |    (loan amount, purpose,   |                              |
        |     identity, income, etc.) |                              |
        |---------------------------->|                              |
        |                             |                              |
        | 2) POST /oauth2/token       |                              |
        |---------------------------->|                              |
        |<----------------------------|                              |
        |        accessToken          |                              |
        |                             |                              |
        | 3) POST /personal/v1/leads  |                              |
        |    (lead payload)           |----------------------------->|
        |                             |<-----------------------------|
        |                             |  201 { uuid, status=created }|
        |                             |                              |
        |          ...processing...   |                              |
        |                             |                              |
        | 4) Credible POST callback   |<-----------------------------|
        |    (final status + products)|                              |
        |                             |                              |
        | 5) Partner returns 2xx      |----------------------------->|
        |    (no body)                |                              |
        |                             |                              |
        | 6) Render products (or AAN) |                              |
        |    user clicks lenderOfferUrl                              |
        |------------------------------------------------------------>

Optional: polling fallback (if callback delayed)

Partner Backend ---- GET /personal/v1/leads/:uuid ----> Credible
      |<--------------- status transitions -------------|
(created -> in_progress -> finding_products -> offers_found/no_offers)

​
Async Delivery and Callback Requirements

Partners are required to use callbacks for asynchronous completion. Callback setup rules:
  • Callback URL is provided during onboarding and configured on Credible’s side.
  • Callback URL must include an unguessable random identifier.
  • Callbacks are sent over HTTPS.
  • Callback endpoint should return only an HTTP status code (2xx = success).
  • If the callback response is not 2xx, Credible will retry later.
Timeout behavior:
  • Callbacks usually arrive quickly; if none arrives within ~120 seconds, treat as timed out and use polling or user messaging.

​
Authentication Model

  • Use OAuth2 client credentials to obtain a Bearer token.
  • Cache tokens and refresh before expiry.
  • Use stage credentials in stage, production credentials in production.

​
No Credible account association

Platform API leads are standalone and used only for the prequalification result returned to the partner. They do not create or map to a Credible account. Before submitting a borrower’s data for the first time, partners must ensure the borrower accepted Credible terms and conditions appropriate for initiating prequalification. (How you store consent is partner-managed; by submitting the lead you are attesting to consent.)

​
Understanding Results: Statuses and What to Do With Them

Treat status as a state machine and map it to clear UX states.

​
Typical status progression

  • created → lead accepted
  • in_progress → processing
  • finding_products → searching for products
  • Terminal outcomes:
    • offers_found → products available
    • no_offers → no products available (may include adverse action notice)
    • timed_out → search timed out (no response for > ~2 minutes)
  • Post-offer interaction:
    • product_selected → user selected an offer (via lenderOfferUrl click)

​
UX guidance by status

StatusPartner behavior
created, in_progress, finding_productsShow “checking rates” state; keep session alive; optionally poll as fallback.
offers_foundRender products grouped by amount ranges; show lender + pricing summary; provide outbound links.
no_offersShow a clear “no offers found” outcome and surface adverseActionNotice if provided.
timed_outOffer retry or fallback messaging; optionally re-poll once or let user try again later.
product_selectedTreat as confirmation that the user clicked through; record conversion event.

​
Product Presentation: Amount Ranges

When offers are found, products may be grouped into up to three ranges:
  • higher-than-requested-amount
  • requested-amount
  • lower-than-requested-amount
Recommended presentation:
  • Default to requested-amount first.
  • If empty, show the closest range and explain why (e.g., “We found options near your requested amount.”).
  • Render each product with the key prequal summary (APR, monthly payment, term, total repayment/interest, lender name).

​
Offer Selection Tracking

Each product includes a lenderOfferUrl. When the user clicks it:
  • The product is treated as selected for the lead
  • Lead status can become product_selected
  • selectedProductId may be populated
Partner guidance:
  • Treat lenderOfferUrl as the canonical outbound destination.
  • Track the click event on your side for analytics, but do not rewrite the URL semantics.

​
“No Offers” and Adverse Action Notices

If no offers are found, the response may include an HTML formatted adverse action notice (adverseActionNotice). Partner guidance:
  • Provide a “Notice of Action Taken” link or expandable section.
  • Render HTML safely (sanitize/contain as needed for your environment).
  • Do not assume the notice is always present.
Also note: lenders may independently send adverse action notices outside the API flow.