Fincheck

Accepting an Offer

Commit the lead to the applicant's chosen partner and handle each response.

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
curl -X POST "https://your-api-origin/api/v2/accept" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hashid": "k3mN9pQx",
    "partner_id": 227
  }'
FieldRequiredUse
hashidRequiredThe top-level id from POST /offer.
partner_idRequiredThe id of the match the applicant chose.
live_quotesOptionalThe quote the applicant chose, when the match returned live_quotes.
bankOptionalThe applicant's bank, when your agreement with Fincheck includes it.

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

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

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

Partner details

JSON
{
  "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

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

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

cURL
curl "https://your-api-origin/api/v2/accept/k3mN9pQx/link" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Accept: application/json"
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 →

If the accept is rejected

HTTP 422 means the request was valid but this partner cannot be accepted now:

MessageWhat it meansWhat to do
lead is not in matched, declined, or failed stateThe lead already went to a partner, or it was not created by POST /offer.Check the lead with GET /lead/{hashid}.
partner not assigned to this intentThe partner does not take leads for this intent.Choose a partner from the offer's matches.
partner is not currently a valid choice for this leadThe partner no longer qualifies for this applicant.Let the applicant choose another match.
partner has no redirect_url configuredThe partner cannot receive the applicant yet.Let the applicant choose another match, and tell support.

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