Fincheck

Duplicate Submissions

What happens when you send the same applicant again, and how to read the result.

FincheckEngine recognises when you send the same applicant again. Instead of creating a second lead, it either returns the lead you already have or creates a new one that only goes to partners the applicant has not been sent to. A partner does not receive the same applicant twice within its own repeat window.

These rules apply to POST /lead, POST /offer, and each row of POST /lead/batch on API v2.

When a submission counts as a repeat

A submission is a repeat when it has the same ID number and the same intent as an earlier lead you sent, within the intent's duplicate window. The window is set per intent, usually a few days; ask Fincheck for the value of the intents you use.

Only your own leads count. If another affiliate already sent the same applicant, you get your own new lead, and you never see the other affiliate's lead.

What happens

The outcome depends on whether the earlier lead has already been sent to a partner.

You send the applicant again…ResultResponse
Within about two minutes, and the earlier lead has not been sent to a partner yetThe earlier lead, unchanged. A safe retry.200, the earlier id, "result": "duplicate"
Within the window, and the earlier lead has not been sent to a partner yetThe earlier lead. The details you send replace the stored ones, and it is matched again with them.200, the earlier id, "result": "duplicate"
Within the window, and the earlier lead was already sent to a partnerA new lead, offered or sent only to partners that have not received the applicant recently200, a new id, "result": "created"
With the same partner_ids as an earlier lead, within the windowThe earlier lead. Nothing is sent again.200, the earlier id, "result": "duplicate"
With different partner_idsA new lead, sent only to the named partners that have not received the applicant recently200, a new id, "result": "created"
After the window has passedA new lead200, a new id, "result": "created"

When the earlier lead is returned with new details, only the fields you send are replaced. Fields you leave out keep their stored values, and the ID number never changes.

Reading the response

Every POST /lead and POST /offer response has a result field.

POST /lead also returns status. A duplicate looks like this:

JSON
{ "id": "k3mN9pQx", "status": "Lead already received", "result": "duplicate" }

POST /offer returns result and leaves out status. matches can still be present:

JSON
{
  "id": "k3mN9pQx",
  "matches": [
    { "id": 227, "company_name": "Example Lender", "rank": 1, "probability": 80 }
  ],
  "result": "duplicate"
}
  • created: a new lead. Store the id.
  • duplicate: a lead you already have. On POST /lead its status is Lead already received. Keep the id you stored before, and do not count it as a new lead.

When you send partner_ids, a named partner that already received the applicant appears in errors with the message already sent to this partner.

Accepting an offer

You can only accept your own leads:

SituationResponse
The lead is not yours404 {"code":"lead_not_found","message":"Lead not found."}
The lead was already sent to a partner422 {"code":"lead_already_accepted","message":"This lead has already been accepted."}
The chosen partner declinedThe applicant can accept a different match from the same offer.

Batch uploads

Each row follows the same rules, including against leads from your earlier batches. A repeat row gets the status duplicate and the existing lead's id, and is not sent again. Rows for the same applicant with different partner_ids are separate requests.

The partner column must be called partner_ids. A partner_id column with a value is rejected with "partner_id": "is not supported; use partner_ids"; rename it in your file, or map it with the map field.

What to do in your integration

  • Store the id from every response, and use result to decide whether it is a new lead.
  • After a timeout or network error, you can send the same request again. If the first lead has not been sent to a partner yet, you get it back as duplicate. If it has, you get a new lead for the remaining partners, so check result before counting it.
  • Do not resend an applicant to try more partners. A new request for an applicant already sent to a partner only reaches partners that have not received them.
  • For batches, poll the existing batch_id instead of uploading the file again.