Fincheck

Intent Fields

The products a lead can be sent for, and the fields and values each one accepts.

An intent is the product the applicant wants, such as Personal Loans. Every lead names one, with intent (its title) or intent_id. Each intent can require extra fields and narrow the values a field accepts, on top of the rules every lead follows.

A request is checked against the rules every lead follows plus the rules of the intent it selects. Together they are that request's validation contract, and GET /intent returns it. Read it from the environment you send to, and use it as the source of truth for required fields, limits and intent-specific fields instead of hardcoding an intent's rules: they can change without a new API version.

Select the intent

Send intent (the title, matched case-insensitively) or intent_id. If you send both, they must name the same intent.

SituationResponse
Neither is sent422 validation_failed, with intent listed as required: "send one of: intent, intent_id".
Both are sent and name different intents422 validation_failed, with intent listed as invalid_value: "must match intent_id".
No such intent422 intent_not_found.
The intent is not accepting leads422 intent_inactive.
The intent is temporarily unavailable503 intent_unavailable: "This intent is temporarily unavailable." Retry later with backoff.

The same applies to POST /offer, to the intent chosen for a POST /lead/batch, and to GET /intent/{id}. An intent that is temporarily unavailable is left out of the GET /intent list until it recovers.

List the intents

cURL
curl "https://api.engine-v2.uat.fincheck.co.za/api/v2/intent" \
  -H "Authorization: Bearer fce_your_key" \
  -H "Accept: application/json"
FieldRequiredTypeAllowed valuesDescription
intentsRequiredlist of objects—Active intents only. An intent that is temporarily unavailable is left out until it recovers; requesting it returns intent_unavailable.
intents[].idRequiredinteger—Intent id. Send it as intent_id. If you also send intent, both must name this intent.
intents[].schemaRequiredobject—The intent's data contract, as JSON Schema (draft 2020-12): the lead data fields, which are required, and each field's type, allowed values (enum), range (minimum/maximum), length and format. It includes the global rules and any limits set for this intent, and changes when those settings change. These are the data rules that POST /lead, POST /offer and each POST /lead/batch row are validated against. It does not include the request controls (intent, intent_id, partner_ids, fast_application, referee_id), which are documented on each endpoint's request schema. Some rules plain JSON Schema can't express are carried as extensions: x-not-greater-than (a field may not exceed another field), x-min-age / x-max-age (applicant age from id_number), and x-intent-required (the requirements this intent added to the base required fields: field names, or the title of an any-one-of group in allOf, e.g. credit_score). On POST /offer with fast_application true, exactly the x-intent-required requirements are not enforced; the base required fields and every other rule still are. Custom formats: sa_id_number, sa_mobile, person_name.
intents[].titleRequiredstring—Send this value as intent, or send id as intent_id.

Get one intent

To read a single intent, call GET /api/v2/intent/{id} with the intent's id from the list. It returns the same id, title and schema for that one intent, in an intent object:

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

An unknown id returns 404 intent_not_found, and an intent that is temporarily unavailable returns 503 intent_unavailable. Use the id, not the title: this call does not look intents up by name.

Each intent's schema is a JSON Schema document describing that intent's data contract: the lead data fields (the ones every lead has, plus any the intent adds), which are required, and each field's type, allowed values, limits and format. These are the data rules POST /lead, POST /offer and every POST /lead/batch row are validated against. Validate a lead's data against it before sending to catch problems early. Intents and their rules differ between environments, so read them from the environment you send to.

The schema does not include the request controls, which belong to the endpoints and are documented on each one in the API reference: intent / intent_id (choosing the intent), partner_ids (POST /lead and batch rows), fast_application (POST /offer) and referee_id. Together, the endpoint's request schema and the intent's schema are the complete request contract.

Some rules JSON Schema can't express are carried as extensions:

ExtensionMeaning
x-not-greater-thanThe field may not be greater than the named field, e.g. net_income may not exceed gross_income.
x-min-age, x-max-ageThe applicant's age, worked out from id_number, must be in this range.
x-intent-requiredThe requirements this intent added to the base required fields: field names, and the name of an any-one-of group such as credit_score (its alternatives are in the schema's allOf, titled with the same name). The base required fields (first_name, last_name, id_number, cell_phone_number, popi) are never listed. POST /offer with fast_application: true skips exactly these; every field in required still has to satisfy its limits when sent.

The custom formats sa_id_number (a valid South African ID number), sa_mobile (a South African mobile number: 06x, 07x or 081–084), person_name (letters, spaces, hyphens, apostrophes and full stops, with at least one letter) and email (an ASCII address with a dotted domain) are checked too.

Rules per intent

The fields each intent accepts in this environment, including the fields it requires and any narrower limits. This is the same information GET /intent returns. Each intent also has its own page, with an example request, that you can bookmark or print: use Page for this intent.