Tracking a Lead

Read a lead's state and know what each state means for you.

Every lead has a state that moves as FincheckEngine processes it. Read it with the lead id returned when you created the lead.

See GET /api/v2/lead/{hashid} in the API Reference →

Read the lead

cURL

curl "https://your-api-origin/api/v2/lead/k3mN9pQx" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Accept: application/json"

JSON

{
  "state": "dispatched",
  "added": "2026-09-29T08:15:42Z",
  "first_name": "Thabo",
  "last_name": "Molefe",
  "intent": "Personal Loans"
}

The response also returns the applicant data stored for the lead. You can only read your own leads: ones created for your account, or submitted with your API key. An unknown id, or another affiliate's lead, returns HTTP 404.

Lead states

Processing

State	What it means	What to do	Final
`received`	The lead was accepted and is waiting to be processed.	Nothing. Check again later.	No
`validated`, `enriched`	FincheckEngine is preparing the lead for matching.	Nothing. Check again later.	No

Direct outcomes

State	What it means	What to do	Final
`dispatched`	The lead was sent to at least one partner.	Nothing. The partner takes it from here.	Yes
`unmatched`	No partner currently accepts leads for this applicant and intent.	Keep the `id` for reporting. Do not resend the same applicant unchanged.	Yes
`validation_failed`	The intent stopped accepting leads before the lead was processed.	Check the active intents with `GET /intent` and send new leads to an active one.	Yes
`manual_queue`	Processing could not complete automatically, and Fincheck is reviewing the lead.	Nothing. Contact support if it stays here.	No

Comparisons outcomes

State	What it means	What to do	Final
`matched`	Offers were returned and the lead is waiting for an accept.	Call `POST /accept` when the applicant chooses a partner.	No
`offer_failed`	Matching could not complete.	Request offers again. Contact support if it keeps failing.	No
`accepted`	The chosen partner accepted the lead.	Send the applicant to the partner if you received a link.	Yes
`declined`	The chosen partner declined the lead.	The applicant can choose another match from the offer.	No
`referral_failed`	The lead could not be delivered to the chosen partner.	The applicant can choose another match, or you can try again later.	No
`dropped`	The applicant did not choose a partner in time.	Request new offers if the applicant returns.	Yes

A lead can also be marked rejected or uninterested when a partner or the applicant closes it. Both are final.

How often to check

Check a Direct lead a few minutes after creating it, then at longer intervals. Most leads leave received quickly.
Stop checking once the lead reaches a final state.
Keep polling bounded. A 404 means the id is wrong or belongs to the other environment, so fix the id rather than retrying.
Single leads have no completion webhook. For many leads at once, use Batch Import, which supports one.