Skip to main content

Introduction

Get started with your Falu integration

We recommend you read this guide to:

  • help us make your initial integration and testing experience as smooth as possible
  • check some best practices on how to manage your integration
  • get guidance on going live for the first time

Falu brings you an integrated infrastructure comprising four main services: messaging, identity verification, and payments. You can configure and manage these services using either the Falu Dashboard or through our APIs.

note

Check the Dashboard section of this guide to manage your account, team, and services.

Using the Falu APIs

In this release, we have exposed API endpoints for accessing the above four services. The APIs are built on REST; data entities are represented as HTTP resources and are accessed using HTTP requests. Request parameters and responses - including errors - are encoded in JSON.

The APIs response status and error codes comply with HTTP status codes as defined in RFC 2616. You can invoke our API endpoints using REST clients, such as Postman or Reqbin, and command line tools like Curl. To get you started, we have provided code samples in various languages, such as Curl and C#. Sample JSON responses for each APIs request have also been availed.

Some preliminary steps

Before you can use the APIs, it is recommended that you test them and your keys. Below, we outline how you can achieve this exercise using Reqbin.

  • Step 1: Get API Keys You can get two types of API keys from your Dashboard depending on its configuration: Sandbox keys for testing and live keys to generate live requests.
Sandbox keys

You can use the sandbox to test your technical integration to simulate API requests.

You should test with a sandbox API key before going live. Sandbox requests return templated responses and you won't be charged. To generate sandbox keys:

  • Go to your Dashboard
  • Toggle the button on the top right corner to 'Test' mode.
  • Select Developers
  • Select API Keys
  • Select Create API Key

introduction-docs_intro1

Make sure you are using the right API key. Read the API Keys guide for more details.

Live keys

Typically, live tokens are issued after completion and verification of integration testing. You can generate live API keys following the same procedure as when getting Sandbox keys, but with your Dashboard in live mode. Note that new live mode keys are redacted from your Dashboard after you have accessed them for the first time.

tip

Keep your keys secure:

Your keys are modifiable in the API Keys section of the Dashboard. For each public or secret key, you can click on Roll/ update secret under Actions to generate a new key.

  • Step 2: Test the API and keys

As stated before, our APIs are built on REST and can be invoked using clients such as Postman. Below is a sample test-run of our messages API endpoint.

  • Create, configure, and get your API keys

From your Dashboard, create a private key to allow you to access the messages API from the public domain. Also, configure the Allowed Endpoints to the type of API you want to use.

introduction-docs_intro2

  • Create a test call to the API

Copy the key and go to your preferred API client to test it. In this example, we use Reqbin to do a GET request to the messages API. Visit our API reference to view the structure of our API request headers, including the base URL and the status messages and their meanings.

introduction-docs_intro3

The test call above can give you some insights into how Falu API calls work and how to manage them. For example, checking the Headers section of the response will show you that the rate limits is capped at 100 per minute. Read more about this in the rate limits guide.

To lower the possibility you'll be rate-limited, we recommend:

  • Running non essential or routine batch API jobs outside your peak hours
  • Throttling batch jobs
  • Prioritizing requests that are essential to your application.