Quickstart

This quickstart takes you from credentials to a first successful request. It uses a fictional applicant and placeholder keys.

1. Get v2 credentials#

Email support@finch-technologies.com to request your keys. Say which integration you are building (Direct, Comparisons, or both) and which environments you need.

Keep keys on your server. Never put one in browser JavaScript, a mobile app, or a public repository.

2. Know your environments#

The key decides the environment and works only against that environment's origin. Data never crosses between environments. The commands below use UAT.

Compare the environments →

3. Check your key#

Paste your key into Not authenticated in the docs header and select Test authentication. The docs confirm the key without storing it.

To check from your own server, list the intents your key can submit to:

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

A 200 response confirms the key and returns the active intents. Each intent's title is the value you send as intent, for example Personal Loans. A 401 response means the key is missing, mistyped, expired, or belongs to a different environment.

4. Send your first request#

Choose the integration you are building. The two flows are separate: use one or the other for each applicant.

Direct: send a lead

FincheckEngine matches the lead and sends it to partners in the background.

curl -X POST "https://api.engine-v2.uat.fincheck.co.za/api/v2/lead" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Thabo",
    "last_name": "Molefe",
    "cell_phone_number": "0821234567",
    "id_number": "8001015009087",
    "intent": "Personal Loans",
    "popi": true
  }'

{
  "id": "k3mN9pQx",
  "status": "Lead successfully added"
}

Store id. Use it to track the lead.

Comparisons: show offers, then accept one

Request the partners that qualify for the applicant:

curl -X POST "https://api.engine-v2.uat.fincheck.co.za/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",
    "id_number": "8001015009087",
    "intent": "Personal Loans",
    "popi": true
  }'

{
  "matches": [
    { "id": 227, "company_name": "Example Lender", "rank": 1, "probability": 80 }
  ],
  "id": "k3mN9pQx"
}

When the applicant chooses a partner, accept it with the lead id and the match 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 }'

Next steps#

• Sending a Lead: the fields, consent, and deduplication rules.
• Requesting Offers and Accepting an Offer: every Comparisons response.
• Errors: what to correct, what to retry, and when to contact support.
• API Reference: every endpoint and schema.