Accepting an Offer

POST /api/v2/accept is the second step of the Comparisons integration. It commits the lead to the partner the applicant chose from the offers.

See POST /api/v2/accept in the API Reference →

1. Accept the chosen match#

Send the offer's lead id as hashid and the chosen match's id as partner_id:

curl -X POST "https://api.engine-v2.uat.fincheck.co.za/api/v2/accept" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hashid": "k3mN9pQx",
    "partner_id": 227
  }'

Only send a partner that appeared in the offer's matches.

2. Handle the response#

The partner determines which of three successful responses you receive. Check for each in this order.

A redirect

{
  "redirect": "https://partner.example.com/apply/k3mN9pQx"
}

Send the applicant to redirect. Always use the URL exactly as returned.

Partner details

{
  "id": "k3mN9pQx",
  "status": "success",
  "api": [
    {
      "id": 227,
      "company_name": "Example Lender",
      "partner_type": "api",
      "live_scoring_api": true,
      "end_to_end": false
    }
  ]
}

The partner received the lead directly. api describes the accepted partner. If the response also has a redirect, send the applicant there.

A link that is ready later

{
  "id": "k3mN9pQx",
  "status": "success"
}

For end-to-end partners the link may follow the acceptance. Fetch it with the lead id:

curl "https://api.engine-v2.uat.fincheck.co.za/api/v2/accept/k3mN9pQx/link" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Accept: application/json"

{
  "ready": true,
  "link": "https://partner.example.com/apply/k3mN9pQx"
}

When ready is false, wait two seconds and try again. Stop after about a minute and show the applicant that the partner will contact them. Never build or guess a partner URL.

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

The link endpoint answers with:

Applying end to end#

An end-to-end application lets the applicant apply with the partner without leaving your journey. Fincheck sends the partner the complete application, including the quote the applicant chose, and the partner returns a link where the applicant finishes, usually to sign.

All of these must be true:

1. End-to-end applications are enabled for your account.
2. You requested the offer with "application_method": "apply-now". See Quote or apply now.
3. The applicant chose a match with end_to_end: true.
4. If that match has live_scoring_api: true, it also has live_quotes.

Accept with type and the quote the applicant chose, copied from the match's live_quotes:

curl -X POST "https://api.engine-v2.uat.fincheck.co.za/api/v2/accept" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hashid": "k3mN9pQx",
    "partner_id": 301,
    "type": "apply-now",
    "live_quotes": { "id": 31, "LoanAmount": 5000, "TermAllowed": 6 }
  }'

The response is a link that is ready later: fetch it from GET /accept/{hashid}/link and send the applicant there.

If any condition is not met, the accept continues as a normal referral and you receive one of the other responses above, usually a redirect. Handle every response type, even when you send apply-now.

If the accept is rejected#

POST /accept can return:

Errors sent before your API key is identified (401, and 503 during maintenance) have no code: their body is only {"error": "…"}.

You can only accept your own leads. Any other hashid returns 404 lead_not_found.

If the chosen partner declines, the lead's state becomes declined and the applicant can accept a different match from the same offer.