Fincheck

Requesting Offers

Show the applicant the partners that currently qualify for them.

POST /api/v2/offer is the first step of the Comparisons integration. It validates the applicant, creates the lead, and returns the partners that currently qualify, so the applicant can choose one.

Nothing is sent to a partner until you accept an offer.

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

1. Request offers

The request body uses the same applicant fields as Sending a Lead:

cURL
curl -X POST "https://your-api-origin/api/v2/offer" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Thabo",
    "last_name": "Molefe",
    "cell_phone_number": "0821234567",
    "email": "thabo.molefe@example.com",
    "id_number": "8001015009087",
    "intent": "Personal Loans",
    "popi": true,
    "gross_income": 25000,
    "net_income": 18000,
    "loan_amount_required": 5000
  }'

2. Send the fields the intent needs

Some intents need extra data before partners can be matched, for example income or loan amount. Each intent's fields in GET /api/v2/intent lists what it requires. If any are missing, the API returns HTTP 422:

JSON
{
  "message": "intent schema validation failed",
  "missing_fields": ["gross_income", "loan_amount_required"]
}

Add the fields in missing_fields and request offers again.

3. Show the matches

JSON
{
  "matches": [
    {
      "id": 227,
      "company_name": "Example Lender",
      "company_logo_url": "https://partner.example.com/logo.png",
      "partner_type": "url",
      "rank": 1,
      "probability": 80,
      "end_to_end": false
    }
  ],
  "id": "k3mN9pQx"
}

The top-level id is the lead id. Each item in matches is one partner the applicant can choose. Show them in rank order.

FieldHow to use it
idThe partner's id. Send it as partner_id when accepting.
company_name, company_logo_urlWhat to show the applicant. Use company_mini_logo_url or company_wide_logo_url for other layouts.
rankFincheck's ordering, starting at 1.
probabilityA likelihood score for display, usually between 0 and 100. 0 means no estimate is available.
live_quotesThe partner's live quote, when it provides one. Pass the chosen quote back when accepting.
probability_conditionsThe partner's probability rules, as a JSON array. For information only.
end_to_endtrue when accepting may return a link that is ready a little later.

The API Reference lists every field in the response.

No matches

An empty matches array with HTTP 200 is a valid result: the applicant was evaluated, and no partner currently qualifies.

JSON
{
  "matches": [],
  "id": "k3mN9pQx"
}

Tell the applicant no offers are available. Do not retry with the same data or invent a partner id.

Next step

When the applicant chooses a partner, accept the offer with the lead id and the match id.