Skip to main content

BYOD 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). 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.

BYOD

In order for Beam to analyse an applicant, we need their personal info and banking data. Beam can gather that data either through our Connect frontend or through a set of backend endpoints if you already have that data. We call the latter flow BYOD or 'Bring Your Own Data'.

Connect Example

Here we will walk you through an example of creating an application 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": "64bce09f80164e84cc37ba70",
    "redirect_url": "http://example.com/success2",
    "proxy_id": "4YCpWJT75mBQu7kFn5oPce5j2tTImnzoHqTV0VmfIpA",
    "connect_url": "https://connect.beamlend.com/application/4YCpWJT75mBQu7kFn5oPce5j2tTImnzoHqTV0VmfIpA"
}

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

You can view the reference for this endpoint here.

3. Personal Info​

Since you already have personal details for your user, you can call the endpoint /v1/personal_info/<personal_info_connections>/prefill.

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.

4. Bank BYOD​

Make a PUT request to /v1/bank_connections/<application_id>/byod with the following body:

{
    "accounts": [
        {
            "account_number": "12345678912311",
            "account_name": "Test Account",
            "account_type": "savings",
            "balance": 1000,
            "currency": "ZAR",
            "bank_slug": "fnb",
            "account_holder_name": "Test User",
            "transactions": [
                {
                    "account_number": "111111111",
                    "datetime": "2024-06-18T22:00:00Z",
                    "amount": 900.0,
                    "description": "Test transaction 2024-06-19",
                    "reference": null,
                    "currency": "ZAR",
                    "balance": 405450.0,
                },
                {
                    "account_number": "222222222",
                    "datetime": "2024-06-18T22:00:00Z",
                    "amount": 900.0,
                    "description": "Test transaction 2024-06-19",
                    "reference": null,
                    "currency": "ZAR",
                    "balance": 405450.0,
                }
            ]
        }
    ]
}

You can view the reference for this endpoint here.

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:

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