Skip to main content

Connect Walkthrough

Beam allows you leverage diverse data sources, including traditional credit bureau scores, bank account data, KYC identity services, and more, to pull data for an individual.

The core functionality of Beam allows you, an organization, to generate an application for an applicant (which is an individual). This process, known as Connect, involves the applicant entering their details to compile information from various data sources. In this system, a single organization can have multiple applicants, and each applicant can have multiple applications.

At the moment, all applications include the end-user's personal info and bank data. In the future, other data points will be added. Users of the API will be able to create an application configuration to specify which data points they need to pull.

Creating an Application

In order to create an application, an applicant is required. From there you will receive a connect url where you can redirect the user to begin providing their details. Once the user hits the connect page, they will be prompted to enter the information needed to establish each connection and collect each data point from external data sources. Once complete, they will be redirected back to a url specified on application creation. This process is analgous to a merchant website redirecting a user to a payment gateway. The payment gateway handles gathering credit card info (in this case Connect) and then sends the browser back to the merchant (in this case your site/app) along with the status of the payment.

Connect Example

Here we will walk you through an example of creating an application with a Connect link for an applicant.

We will refer to endpoints without the host here. If you are in production use, https://api.beamlend.com, otherwise use https://sandbox.api.beamlend.com. See the auth docs for more info

1. Create an Applicant​

Now, make a POST to /v1/applications/applicants. The body should be empty:

{}

Your response will look like

{
    "id": "64bce09f80164e84cc37ba70",
    "organisation": "64b518b3840ca8664c9ff262"
}

You should save the id in your db, linking it to one of your users. It represents the id of the applicant. You will need it in the future if you wish to create another application for the same user (applicant).

You can view the reference for this endpoint here.

2. Create an Application​

You are now ready to create an application. Once this is done you will be able to redirect your user to the Connect flow and we can begin fetching their data for you.

Make a POST request to /v1/applications/ with the following body:

{
    "applicant_id": "64bce09f80164e84cc37ba70",
    "redirect_url": "https://yourdomain.com/beam/success"
}

Here is what these fields mean:

  • applicant_id: id of the applicant created above.
  • redirect_url: where we should send the user on completion (to your site/app).

You will receive a response like this:

{
    "id": "669fdc7c73f454d820e8e37d",
    "applicant": "669fd7a72f89af7c4fe8e077",
    "redirect_url": "http://example.com/success2",
    "proxy_id": "4YCpWJT75mBQu7kFn5oPce5j2tTImnzoHqTV0VmfIpA",
    "connect_url": "https://connect.beamlend.com/application/4YCpWJT75mBQu7kFn5oPce5j2tTImnzoHqTV0VmfIpA",
    "connect_iframe_url": "https://connect-iframe.beamlend.com/4YCpWJT75mBQu7kFn5oPce5j2tTImnzoHqTV0VmfIpA",
}

You should save the id field as you will need it when querying the status of the application later.

Redirect or iframe​

Beam's Connect is hosted as a standalone site as well as an iframe. You should use the iframe if you prefer to host the user within your environment. The data collected in the two processes is equivalent.

Redirect​

You should redirect the user to connect_url. Once the user has completed the process, we will send the user back to your supplied redirect_url with a POST containing the id of the original application. You will then need to make a GET to /v1/applications/<:id> (replace id with the id field returned when making a POST to /v1/applications/). Using the example above, it will be /v1/applications/64bd0ef30f227a042fd82114. For security, we do not send data back to redirect_url. You must explicitly query it or receive it via webook.

You can view the reference for this endpoint here.

iframe​

Follow the below steps to embed the connect iframe within your environment.

1. Add the Wrapper Element: Place the below empty <div> where you want the iframe to appear:

<div id="connect_wrapper"></div>

2. Add the script: Place the script tag in the <head> section of your HTML file or at the beginning of the <body> tag. This ensures the script is loaded correctly when the page is rendered.

<script src="https://connect-iframe.beamlend.com/<proxy_id>"></script>

This will insert the iframe element into the empty <div> from above. Use the connect_iframe_url parameter from the create application call.

3. Customize Dimensions (Optional) The iframe's max width and height are controlled by parameters in the script URL. You can adjust the width and height query parameters in the script tag to change this. For example, to make the iframe 800 pixels wide and 400 pixels tall, update the script URL as follows: 

<script src="https://connect-iframe.beamlend.com/<proxy_id>?width=800px&height=400px&proxy_id=<proxy_id>"></script>

If you don't provide width and height parameters, the iframe will have the dimensions of the root div by default (

). The following units of measurement are available: px (pixels), vh (viewport height), vw (viewport width), dvh (dynamic viewport height), or dvw (dynamic viewport width).

Auto Resizing Based on Screen Dimensions: The width and height parameters set the maximum dimensions for the iframe. When the iframe is displayed, it will scale to fit within these maximum dimensions based on the current screen size.

Maximum Dimensions: The specified width and height determine the maximum size of the iframe. The iframe will not exceed these dimensions.

Dynamic Scaling: To make sure the iframe adapts to different screen sizes, it will calculate how much of the screen it occupies and scale proportionally. This ensures that the iframe maintains a consistent appearance relative to the viewport size.

How It Works: When the iframe is rendered, it calculates its size as a percentage of the available screen space. It then adjusts its width and height proportionally based on the screen size while respecting the maximum dimensions specified.

5. Server-Side Rendering with Next.js (Optional): If you are using Next.js and want to include the iframe script dynamically, you can use the next/script component to avoid server-side rendering issues.

import React from 'react';
import Script from 'next/script';

export default function Page() {
  return (
    <div id="connect_wrapper">
      {/* The iframe will be added dynamically by the script */}
      <Script
        src="https://connect-iframe.beamlend.com/<proxy_id>"
        strategy="lazyOnload" 
      />
    </div>
  );
}
CORS Whitelisting​

Please contact the Beam development team to whitelist your origin(s), otherwise you will receive CORS related errors from your browser. For local development, the origins http://localhost:3000 and http://localhost:3001 are pre-whitelisted.

Skipping The Personal Info Form​

If you already have personal details for your user, you can call the endpoint /v1/personal_info/<personal_info_connections>/prefill. The personal info form will then not be shown in the personal info form step.

Make a PUT request to /v1/personal_info_connections/<application_id>/prefill with the following body:

{
    "first_names": "John",
    "last_names": "Smith",
    "date_of_birth": "2003-01-01",
    "gov_id": "03010171731810",
    "id_country": "South Africa",
    "id_type": "ID",
    "nationality": "South Africa",
    "email": "email@email.com",
    "phone": "0987654321"
}

All fields are required.

Note that if id_country is South Africa, the API will run the Luhn algorithm to verify that it is a valid South African id number. If it is not, you will receive an error.

Fetching Banking Data​

See the bank connection docs for info on how to retrieve transactions, scores etc.

Webhooks​

Processing bank data takes time. If you attempt to hit a bank data endpoint straight after a user completes the Connect process, you will likely receive a 400 error (check the API reference for specifics) indicating that the application is still processing. You can find the available webhooks here.

Beam uses Svix to send webhooks to your application. Please check their docs on receiving webhooks to learn about how these are set up. For security, please make sure to verify the signature supplied by Svix. The methodology for this can also be found in their docs.

For this tutorial, you probably want to subscribe to the following endpoints:

  • connect.complete
  • bank.affordability_calculated
  • bank.expense_insights_calculated
  • bank.income_analysis_calculated
  • bank.liquidity_score_calculated
  • bank.risk_insights_calculated
  • bank.transactions_labelled