Receive loan leads by direct API with idempotent requests

Direct API delivery sends each loan lead as one real-time JSON request

With direct API delivery, a loan lead that passes screening reaches you as one real-time JSON request to an endpoint you host. Only applicants that pass the rules you set for each market and product are sent. The credit decision stays with you. To receive applicants on your own site instead, see referral delivery and postbacks.

Everything concrete below is illustrative. Endpoint, field names and header names are agreed with your team during onboarding.

POST /v1/applications HTTP/1.1
Host: api.lender.test
Content-Type: application/json
X-Api-Key: {sandbox or live key}
Idempotency-Key: "4f1c2a9e-6b0d-4e7a-9c1f-2d8e5b7a3c10"

# Applicant fields shown are a minimal set. Any contact or identity fields are agreed at mapping and limited to what your decision needs.
{
  "lead_id": "ld_7f3a9c",
  "market": "IN",
  "product": "personal_loan",
  "applicant": {
    "age_band": "25-34",
    "monthly_income_band": "INR_25k_50k"
  },
  "screening": { "result": "pass" },
  "source": { "channel": "search", "sub_id": "srch_pl_07" },
  "created_at": "2026-10-27T09:14:03Z"
}

# Response: 201 Created with your application ID

Each request ends in one of four outcomes

We send the POST with an idempotency key, and your API answers with one of four outcomes: accepted, duplicate, validation error or server error. A rejected key (401 or 403) is a set-up fault rather than an outcome: delivery stops until it is fixed. Later changes to a status or your capacity arrive by webhook.

Field mapping follows your schema

The mapping targets your schema. The two teams go through your application fields one by one and settle where each value comes from, its type and format, and what happens when it is missing.

• Names and types: your field names, enumerations and units, such as income bands or product codes.
• Required and optional: which absent fields make you reject a request.
• Formats: timestamps as RFC 3339 strings in UTC, like created_at above.
• Identifiers: lead_id ties an application to its webhooks and to the billable event agreed for it.
• Screening output: what, if anything, from screening travels with the application. Your own KYC and the credit decision stay with you.
• Source fields: channel and sub_id, so you can judge lead quality by source.
• Changes: how a new or changed field is announced and versioned.

Keep API keys in headers, separate for sandbox and live

Requests authenticate with an API key in a request header. Sandbox and live keys should be separate, so a sandbox key is refused by the live endpoint and the other way round.

Keep keys out of the URL: OWASP notes that a key in the URL can be captured in web server logs. OWASP also advises against relying on API keys alone for sensitive resources, and separately suggests mutually authenticated client certificates for highly privileged services, so agree what else guards the endpoint. Agree how keys are rotated, so a change leaves no gap in delivery.

Idempotency keys make retries safe

POST is not idempotent, and HTTP says a client should not automatically retry a POST unless it knows the request is idempotent in effect or can detect that the original was never applied. After a timeout the sender does not know whether your system created the application. The idempotency key settles it: the same key means the same request.

Each application gets its own key, typically a UUID, in the Idempotency-Key header. A retry reuses the key and the identical payload. The header is described in an IETF Internet-Draft, not yet a standard, so the exact behaviour is agreed rather than assumed.

A duplicate is a repeated request, not a second applicant

A duplicate is the same key arriving again with the same payload, typically a retry after a timeout. Your API returns a response consistent with the original request, normally the original result, and creates nothing new. The draft suggests 409 Conflict while the first request is still processing, and 422 when a key is reused with a different payload.

A second application from the same person comes under a new key, so it is not an idempotency question. Whether it counts as a repeat applicant is your rule; see recycled identities.

Retries use backoff and respect Retry-After

Retry network errors, timeouts and transient 5xx responses such as 500, 502, 503 and 504. Do not retry a 4xx that describes a payload problem, because the same request fails the same way. After each failure the sender waits longer, adds random jitter so retries do not arrive in step, and stops after a set number of attempts.

When your API sends Retry-After with a 429 or 503, the sender treats its value, a number of seconds or a date, as how long to wait before the next attempt. Agree a cut-off after which a late application is no longer worth delivering. Agree the request timeout too: too short and slow but successful requests are retried, too long and a stalled endpoint holds up delivery.

Webhooks carry status and capacity changes

A 2xx response only says the application was received. What happens next arrives by webhook: a status change on an application, or a change in your capacity for a market and product, so delivery can follow your caps. A decline under your own credit rules is an application status, not an HTTP error. A status webhook can be limited to lead_id, the status and its time; agree that it carries no further applicant or credit data. The teams agree which side hosts each endpoint and the event names. The rules below apply to whichever side receives the webhook.

• Verify every delivery: a signature over the payload, symmetric (HMAC) or asymmetric, and a timestamp within a set tolerance.
• Acknowledge with a 2xx, then process. Anything other than a 2xx, or a slow reply, counts as a failure, and the sender normally retries.
• Expect repeats. Treat the event ID as an idempotency key.
• Do not assume order. Event times can tie, so agree how a newer status is told from an older one.

These rules draw on the Standard Webhooks specification and Stripe's webhook documentation.

Map only the personal data your decision needs

Include only the fields your decision needs. The lender sets what the decision requires, and the two teams settle the list field by field during mapping. Which data protection obligations fall on each company depends on the applicable law and on the contract between them.

Each market's data protection law sets its own limits on what may be collected and passed on; the India, Kazakhstan and Peru pages summarise them. This is general information, not legal advice.

• Agree, before any live data is sent, how the applicant is told that their details go to you and how their consent to that is recorded.
• Prefer derived values to raw ones. In the illustrative request above, an age band stands in for a date of birth; where your decision needs the raw value, the mapping says so.
• Use TLS 1.2 or later on every connection. TLS 1.3 is current and TLS 1.0 and 1.1 are deprecated.
• Keep personal data out of URLs, and agree what each side may write to its logs.
• Agree in writing whether either side keeps request payloads, and for how long.

Run this sandbox checklist before go-live

The sandbox is a test environment with its own keys, where the two teams run the whole flow before any real applicant is sent. With sandbox keys, confirm each of these:

• A valid request returns the accepted response, and every mapped field lands correctly in your system.
• The same request sent twice with one key creates one record and returns the original result.
• The same key with a changed payload is refused.
• Leaving out each required field in turn produces a validation error that names it.
• Forcing a server error and a 429 with Retry-After produces retries with growing waits and no second record.
• A missing, wrong or live-environment key is rejected.
• A status webhook and a capacity webhook are accepted with a valid signature and rejected with a bad one or a stale timestamp, and a repeated delivery is ignored.
• Agree how both sides reconcile a delivery in doubt, such as comparing lists of delivered lead_id values.
• Timestamps, enumerations and bands pass your validation, edge values included.
• No personal data beyond the agreed fields appears in a payload, log line or URL.

Related guides

• Loan leads reach you by referral or by direct APIReferral with a server-to-server postback and a direct API deliver the same screened applicants; this page helps you choose and walks through a launch.
• Implement a referral redirect and S2S postback for loan leadsHow to store redirect parameters, verify the signature, send outcome statuses and handle retries and duplicates.
• How CPL, CPA and CPD price loan leadsHow CPL, CPA and CPD differ on risk and reporting, and which terms to fix in writing: billable event, validation window, caps.
• Screen loan leads for fraud and fit before they reach youFive checks, including fit to your own criteria, screen applicants before handoff. No single signal decides, and a stopped applicant is not delivered to you.

Sources

1. IETF: The Idempotency-Key HTTP Header Field, draft-ietf-httpapi-idempotency-key-header-08 (2026)
2. IETF: RFC 9110, HTTP Semantics (2022)
3. IETF: RFC 6585, Additional HTTP Status Codes (2012)
4. IETF: RFC 9457, Problem Details for HTTP APIs (2023)
5. IETF: RFC 3339, Date and Time on the Internet: Timestamps (2002)
6. IETF: RFC 9846, The Transport Layer Security (TLS) Protocol Version 1.3 (2026)
7. IETF: RFC 8996, Deprecating TLS 1.0 and TLS 1.1 (2021)
8. OWASP: REST Security Cheat Sheet (accessed October 2026)
9. Standard Webhooks: Standard Webhooks specification, version 1.0.0
10. Stripe: Receive Stripe events in your webhook endpoint (accessed October 2026)
11. Amazon Web Services: Timeouts, retries, and backoff with jitter (2019)