Skip to main content

​
Personal Loans Leads API (v2 vs v3)

The Personal Loans Leads API is for partners who already collect the required borrower dataset for a personal loan and want Credible to host the offers dashboard experience for the user. Partners submit a lead server-to-server and receive a handoff link (inviteUrl / “preview link”) that routes the user into Credible’s Personal Loans experience to view offers (or a decline experience).

​
How Leads API Differs From Platform API (Why You’d Choose It)

Leads API
  • Partner submits borrower dataset → Credible returns a handoff URL into Credible-hosted offers dashboard.
  • Leads are associated with an invited-user Credible account.
  • User can access results via handoff link without setting a password.
Platform API
  • Partner submits lead → partner receives offer summaries via callback/polling → partner renders offers in partner UI.
  • Leads are not associated to a Credible account.

​
v2 (partner passes consent text directly)

  • Partner includes HTML consent text in the lead payload (disclosuresText as a single HTML string).
  • Credible may return a warning if the captured consent language is out of date.

​
v3 (partner fetches partner-specific consent text from Credible, then passes it back)

  • Partner first calls a consents endpoint to retrieve the current, partner-specific consent text blocks.
  • Partner displays those consents to the user, captures acknowledgment, and sends them back in the lead payload as a structured object (disclosuresText.personal.consent, optionally disclosuresText.personal.tcpa.consent).
  • Consent text should be cached no longer than 24 hours.
Practical guidance: Prefer v3 when available because it reduces the risk of running outdated consent language and supports multiple consent blocks (e.g., TCPA).

​
End-to-End Flow

​
v2 flow (consent text provided by partner)

+------------------+         +------------------+         +---------------------+
| Partner Frontend |         | Partner Backend  |         | Credible Leads API  |
+------------------+         +------------------+         +---------------------+
        |                             |                             |
        | 1) Collect borrower data    |                             |
        |    + show partner-stored    |                             |
        |    Credible consent HTML    |                             |
        |---------------------------->|                             |
        |                             |                             |
        | 2) POST /oauth2/token       |---------------------------->|
        |<----------------------------|                             |
        |                             |                             |
        | 3) POST v2 lead (includes   |---------------------------->|
        |    disclosuresText HTML)    |                             |
        |<----------------------------|                             |
        |     { lead.status, inviteUrl, warning? }                  |
        |                             |                             |
        | 4) Redirect user to inviteUrl                              |
        |---------------------------------------------------------->|
        |                             |                             |
        | 5) User views offers/decline on Credible                  |

​
v3 flow (consent text retrieved from Credible)

+------------------+         +------------------+         +---------------------+
| Partner Frontend |         | Partner Backend  |         | Credible Leads API  |
+------------------+         +------------------+         +---------------------+
        |                             |                             |
        | 1) Start PL funnel          |                             |
        |---------------------------->|                             |
        |                             |                             |
        | 2) POST /oauth2/token       |---------------------------->|
        |<----------------------------|                             |
        |                             |                             |
        | 3) GET v3 consents          |---------------------------->|
        |    (cache <= 24h)           |                             |
        |<----------------------------|                             |
        |   { disclosuresText blocks }                              |
        |                             |                             |
        | 4) Display consents +       |                             |
        |    capture acknowledgement  |                             |
        |---------------------------->|                             |
        |                             |                             |
        | 5) POST v3 lead (includes   |---------------------------->|
        |    structured disclosuresText)                            |
        |<----------------------------|                             |
        |     { lead.status, inviteUrl, warning? }                  |
        |                             |                             |
        | 6) Redirect user to inviteUrl                              |
        |---------------------------------------------------------->|
        |                             |                             |
        | 7) User views offers/decline on Credible                  |

​
User Account Behavior (Invited Users)

Leads API submissions create/associate to a Credible invited-user:
  • If the user later comes to Credible organically with the same email, they may be prompted to set a password.
  • If the user follows the handoff link returned by the API, they can access the experience without entering a password.
Partner UX implication: treat the inviteUrl as the canonical way to access results from a partner flow.

​
Key Lifecycle States (Partner Interpretation)

Leads API returns a lead object with status. At a high level:
  • in_progress: lead accepted; processing underway (handoff link may already be available)
  • success: processing complete and user experience available via inviteUrl
  • failure: processing failed; no handoff available
  • timed_out: processing exceeded timeout window; treat as retry/fallback
Practical guidance: redirect to inviteUrl as soon as it is present rather than waiting to render offers yourself.

​
v2: partner-owned consent text

  • You store and render Credible’s required consent HTML on your side.
  • You may receive a warning response indicating your consent language is out of date.
  • You need an operational process to update consent HTML when Credible changes it.

​
v3: Credible-provided consent text (recommended)

  • Fetch current consent blocks via the v3 consents endpoint.
  • Render them verbatim (HTML) in your flow and record user acknowledgment.
  • Cache consent copy no longer than 24 hours.
  • Submit the same consent blocks back in the v3 lead request.
TCPA consent: v3 supports an optional personal.tcpa.consent block. If you collect phone/SMS consent, treat it as a distinct consent capture and display it separately from the main consent.

​
What to Log and Persist

To support reconciliation and debugging, record:
  • partnerLeadId (if provided)
  • lead.uuid
  • lead status
  • whether warning was returned
  • whether inviteUrl was issued and whether the user was redirected
  • timestamps for consent fetch (v3) and consent presentation (v2/v3)
  • Backend-only calls (no browser-originated API requests)
  • OAuth2 client credentials implemented with token caching/refresh
  • Choose v2 vs v3 (prefer v3 if available)
  • v3: implement consent fetch + cache policy (< 24 hours)
  • Render consent HTML as provided and capture acknowledgment before lead submission
  • Submit lead and redirect user using inviteUrl when present
  • Handle warning by alerting internal monitoring and updating consent implementation
  • Persist uuid + partnerLeadId for support and troubleshooting