FinX lead api usage

The FinX lead api allows a lender using FinX to receive potential borrowers from a third party provider directly in his instance.

A provider needs to have his account created by a FinX agent in the lender instance they want to send leads to.

To help FinX agent configure his account, the provider must answer the following questions: - What is the webhook url that api will send postbacks to? - Which postback events provider wants to register to? - Is provider managing the term & conditions acceptance? - Is provider sending leads from a server side app or from a web page? - Which rejection rules are to be applied?

Once the account is created, provider will receive the api key required to send leads to that instance.

Testing api key and retrieving documentation

Once provider has his account and api key created, it is possible to download the open_api documentation file describing end points, accepted data structures and api responses. The api key must be set in the request headers to authorize the download.

Fetching documentation example:

curl --location 'https://{{ LENDER_DOMAIN_NAME }}/api/leads/client/v1/openapi.json' --header 'Authorization: api-key {{ API_KEY_VALUE }}'

If key is valid, this will return a json file that can be viewed with Swagger (or other application that reads open api format).

Sending leads to api

In order to send a lead to a lender’s FinX instance, a post request must be made to the /api/leads/v1/create/ end point. The lead data should be contained in the request body as a json string. The api will accept or reject a lead based on data validation and rejections rules defined on the lender’s instance. When a lead is accepted, an application is created on the lender’s instance. The api returns a redirect_url that the borrower can visit to either complete the ibv process (Instant Bank Verification) directly or accept terms & conditions first (if provider account has provides_terms_and_conditions set to false)

Submitting a lead example:

curl --location 'https://{{ LENDER_DOMAIN_NAME }}/api/leads/v1/create/' --header 'Authorization: api-key {{ API_KEY_VALUE }}' 
--header 'Content-Type: application/json' --data-raw '{"fields":{"first_name":"John","last_name":"Doe","email":"[e-mail]",
"address_line1":"15990 Test Street","city":"Townville City","state":"AB","zip_code":"L1L 1L1","gender":0,"birth_date":"1988-01-01",
"phone_1":"0003775941","bank":"004","pay_frequency":"2weeks","first_pay_date":"2025-08-15","income_source":"CSST"}}'

Where {{ LENDER_DOMAIN_NAME }} is the target FinX instance domain name (ex: clients.lender.com).

Fields

Payload fields are described in the openapi.json file. Here is supplemental information regarding some of them.

source_id The value of the field should be a reference to the lead in provider’s own database. It will apear in the postback payload sent to provider webhook when the lender’s instance reports activity on that lead.

requested_loan_amount The application will be created with a product closest to this amount. Otherwise the lender’s default product will be used.

tag This field optionally qualifies the lead in the lender’s instance. It can be used as price tag for the lead in billing results.

kiipr_terms_token This is the value returned by kiipr embed (see terms and conditions workflow). If supplied and valid the terms are considered accepted for that lead without further interraction with the borrower.

flinks When submitting a lead, provider has the option to send flinks ibv data via the ­flinks schema. We expect the payload to contain the same data structure returned by the flinks api get-account-detail end point 200 response status. See https://docs.flinks.com/api/connect/endpoints/account-linking/get-accounts-detail

fields/gender Must be supplied with one these values: 0 for male, 1 for female and 2 for other.

fields/product_code An alternative way of automatically associating a product to an application is to provide a unique product code in this field. This supercedes the requested_loan_amount logic.

fields/language When the lead becomes a request in FinX, the borrower’s profile language will be set to this value. His FinX client space and communications will occur in the selected language. This does not affect anonymous visits to FinX which use the browser’s language.

fields/bank This fields accepts a bank institution number.

Rejections rules

On his instance, the lender sets none or some of the following rules to automatically reject a lead if:

• A customer with the same email already exists
• A customer with the same SIN already exists
• A customer with a similar address already exists
• A customer with a similar email address already exists
• A customer with the same name and date of birth already exists
• A customer with the same primary phone already exists
• A customer with the same secondary phone already exists

If a lead is rejected, the api response will specify which rules were broken.

The /api/leads/v1/validate/ end point can be used to test if a lead would be accepted on lender’s instance. This only checks data validation and rejection rules without creating any application. It expects the same headers and payload as the /api/leads/v1/create/ end point. The validation response is not final. When the lead is actually submitted to /api/leads/v1/create/, the validation checks will occur again to take into account the changes in the lenders database since the first validation was requested.

Terms acceptance workflow

To validate that the terms acceptance is comming from the actual user, the api must receive a token generated by the target FinX instance. Provider aquires this token by embeding a FinX iFrame into the page the user is visiting. This iframe presents a generic ‘acceptance button’ to the user that, when clicked, fetches the token.

Embedded terms acceptance on lead provider side

1. Iframe src example

<iframe
    id="id_kiipr-iframe"
    src="{{ base_url }}/kiipr/embed/terms-and-conditions/?lang=fr"
    width="100%"
    frameborder="0"
></iframe>

Where base_url is the lender’s FinX instance domain name

2. JS event listener example

window.addEventListener(
    "message",
    (message) => {
        if (message.data.type === 'KiiprTermsAccepted') {
            const token = message.data.token;
            /*
                * ===========================================================================
                * |                         Handle the token here                           |
                * ===========================================================================
                */
        } else if (message.data.type === 'KiiprTermsError') {
            const status_code = message.data.status_code;
            /*
                * ===========================================================================
                * |                     Your error handling goes here                       |
                * ===========================================================================
                */
        } else if (message.data.type === 'KiiprTermsResize') {
            /*
                * ===========================================================================
                * | Ignore this event if you want to manage the size of the iframe yourself |
                * ===========================================================================
                */
            const kiiprTermsIFrame = document.querySelector('#id_kiipr-iframe');
            if (kiiprTermsIFrame !== null) {
                kiiprTermsIFrame.setAttribute('height', message.data.height);
            }
        }
    }
);

Handling the token

There are 2 available approaches to submit token, which provider need to choose depending on their application workflow.

1. If lead information is collected on the same page as the embed terms acceptance button embed, provider can include obtained token in a kiipr_terms_token field of the lead API call (/api/leads/v1/create/)

2. If embed terms acceptance button apears on a separate page after lead has been submitted, provider will need to send the token to URL provided in kiipr_terms_url field from /api/leads/v1/create/ response payload.

Postbacks

To be notified about activity occuring on a lead, a provider must give FinX a webhook url and choose which event(s) they want to hear about.

Events notifications that can be sent: - lead_received - ibv_completed - application_accepted - application_rejected - first_loan_granted - subsequent_loan_granted

All events postbacks provide a json payload consisting of these two fields: - source_id the source_id that was received with the lead - event_type one of the preceding events strings

The first_loan_granted and subsequent_loan_granted events payload have this additionnal field: - loan_amount the loan amount.

Validating FinX signature

To confirm the data that we are sending comes from FinX, the postback request has a X-FinX-Signature header. It is a hash combining the provider api key and the request boby codified by hmac sha256.

Here is a Python example of how the request can be validated by the provider:

    secret = bytes(provider_api_key)
    body_hash = hmac.new(secret, request.body, hashlib.sha256)
    signature = base64.urlsafe_b64decode(
        request.headers.get('X-Finx-Signature', '')
    )
    is_valid = hmac.compare_digest(signature, body_hash.digest())