Sending a Lead

POST /api/v2/lead is the Direct integration. You send the applicant once, and FincheckEngine validates them, matches them to eligible partners, and sends the lead to those partners in the background.

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

Before you begin#

• You have a v2 API key for the environment you are calling. See the Quickstart.
• You know the intent (product) the applicant wants. List them with GET /api/v2/intent.
• The applicant has consented to their data being processed (POPI).

1. Send the applicant#

curl -X POST "https://your-api-origin/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",
    "email": "thabo.molefe@example.com",
    "id_number": "8001015009087",
    "intent": "Personal Loans",
    "popi": true,
    "gross_income": 25000,
    "net_income": 18000,
    "loan_amount_required": 5000
  }'

Send every field with its JSON type: whole numbers for money fields (25000, not "25000"), true/false for yes-no fields, and strings for text, including id_number and cell_phone_number. A value of the wrong type is rejected with 422. Leave out any field you don't have, or send null: placeholder strings such as unknown or n/a are validated like real values, so "email": "unknown" is rejected. Send the body as Content-Type: application/json; anything else returns 415.

The API Reference lists every optional field, including employment, banking, and address details. Send what you have: more data gives partners more to match on.

2. Store the lead id#

A successful request returns HTTP 200:

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

Store id with your own applicant reference. You need it to track the lead and for any support query.

3. Handle validation errors#

If a field fails validation, the API returns HTTP 422 and names each field you need to correct:

{
  "message": "Validation failed.",
  "errors": {
    "id_number": ["must be a valid RSA ID number"],
    "gross_income": ["must be an integer"],
    "popi": ["Client must give consent."]
  }
}

The keys in errors are the JSON field names you sent. Correct those values and send the lead again. See Errors for business-rule failures such as an inactive intent.

Send to specific partners#

If Fincheck has agreed a targeted referral with you, send partner_ids to refer the lead only to those partners instead of the partners FincheckEngine would match:

{
  "first_name": "Thabo",
  "last_name": "Molefe",
  "cell_phone_number": "0821234567",
  "id_number": "8001015009087",
  "intent": "Personal Loans",
  "popi": true,
  "partner_ids": [227, 311]
}

The request waits for each referral and reports the outcome per partner:

{
  "id": "k3mN9pQx",
  "status": "Lead successfully added",
  "referred_partner_ids": [227],
  "errors": [{ "partner_id": 311, "message": "Partner not eligible" }]
}

You can send up to 50 partner ids. The singular partner_id field is rejected with 422; use partner_ids.

Duplicate submissions#

If you send the same applicant again inside the deduplication window, the API returns HTTP 200 with the existing lead id and does not create a second lead. Treat it as a success and keep the returned id. This makes it safe to retry a request that timed out.