Customer API Reference

The Customer object ties all of Lean's products together giving a single reference point across all of our services.

You should map Customer's to your own users on a one-to-one basis.

Create a new Customer

A Customer object is a container for all the billing details for your customer and should map on a one-to-one basis with users in your platform. To create a Customer object, make a call to the Customer API endpoint with your application token in the header and the related user ID in your own database.

A new Customer object will be returned, and the customer_id should be saved in your own database.

Request

app_user_id String

The user ID in your own user table. This is to allow you to easily reconcile users and customers in the future.

Please note, this value has a unique constraint, no two Customers can share the same app_user_id

Response

app_user_id String

The user ID you assigned the customer during creation.


customer_id String

A UUID identifying the customer for future calls.


Was this section helpful? 

bash

curl -X POST 'https://sandbox.leantech.me/customers/v1/' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_user_id": "001"
}'

json

{
app_user_id: "001",
customer_id: "f08fb010-878f-407a-9ac2-a7840fb56185"
}

Fetch Customer from app_user_id

If you lose the customer_id for an app_user_id you can fetch the customer_id with a GET request.

Request

app_user_id String

The user ID in your own user table.

Response

app_user_id String

The user ID you assigned the customer during creation.


customer_id String

A UUID identifying the customer for future calls.


Was this section helpful? 

bash

curl -X GET 'https://sandbox.leantech.me/customers/v1/app-user-id/{app_user_id}' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \

json

{
"customer_id": "07b547a6-e516-4eb1-8c2e-1e8b96ab115d",
"app_user_id": "jdoe@leantech.me"
}

Fetch Entities for a Customer

Retrieve a list of all connected Entities for a Customer

Query parameters

customer_id String

The id of the customer who's entities you're querying.

Response

Entities Array

Returns an array of Entities.

View Entity attributes

id String

The entity_id.


customer_id String

The customer_id attached to the entity.


bank_identifier String

The Lean identifier for the bank connected. This is an enum value.


permissions Array

The granted permissions for this entity.


Was this section helpful? 

bash

curl -X GET 'https://sandbox.leantech.me/customers/v1/{customer_id}/entities' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005'

json

[
{
"id": "3bd4e44b-7cb9-3251-b205-c6fa6bac3244",
"customer_id": "497b457c-4a4b-42fb-b093-dbf9f303d63e",
"bank_identifier": "LEANMB1_SAU",
"permissions": {
"identity": true,
"accounts": true,
"balance": true,
"transactions": true
}
},
{
"id": "469e0b2c-012c-40e3-b2d5-474f974a5609",
"customer_id": "497b457c-4a4b-42fb-b093-dbf9f303d63e",
"bank_identifier": "LEANMB2_SAU",
"permissions": {
"identity": true,
"accounts": true,
"balance": true,
"transactions": true
}
}
]

Fetch Payment Sources for a Customer

Retrieve a list of all connected Entities for a Customer

Query parameters

customer_id String

The id of the customer who's payment sources you're querying.

Response

Returns an array of Payment Sources attached to the Customer. The attributes for each payment source can be seen in the Querying a single Payment Source section below.

Was this section helpful? 

bash

curl -X GET 'https://sandbox.leantech.me/customers/v1/{customer_id}/payment-sources' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \

json

[
{
"id": "838af9d4-d77d-4a1e-bc9d-e4f6067ec9a3",
"customer_id": :"6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"bank_identifier": "ENBD_UAE",
"status" : "AWAITING_BENEFICIARY_COOL_OFF",
"beneficiary_cool_off_expiry": "2020-12-13T13:10:17.670087Z",
"accounts": [
{
"id": "9acde98e-9d19-495d-934c-b2ff966262c8",
"account_id": "1457d23a-c1f8-4aee-bc6f-2a253b2e617f",
"account_name": "CURRENT ACCOUNT",
"account_number": "1015746273641",
"iban": "AE340260001015746273641",
"balance": 5748.15,
"currency": "AED",
"balance_last_updated": "2020-12-12T13:10:17.670087Z"
},
{
"id": "47a70bd7-bdfd-4d64-a310-d12c3545ae25",
"account_id": "0d7ece34-6250-4afb-94dd-084cf8138142",
"account_name": "CURRENCY PASSPORT SAVINGS AC",
"account_number": "0318493758374",
"iban": "AE790260000318493758374",
"balance": 12332.00,
"currency": "USD",
"balance_last_updated": "2020-12-12T13:10:17.670087Z"
}
]
} , {
"id": "ca57728d-a196-4edb-868f-9f2034b40403",
"customer_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"bank_identifier": "HSBC_UAE",
"status" : "ACTIVE",
"beneficiary_cool_off_expiry": "2020-12-13T11:20:34.938963Z",
"accounts": [
{
"id": "9acde98e-9d19-495d-934c-b2ff966262c8",
"account_id": "1457d23a-c1f8-4aee-bc6f-2a253b2e617f",
"account_name": "CURRENT ACCOUNT",
"account_number": "1012019344469",
"iban": "AE340260001012019344469",
"balance": 2436.15,
"currency": "AED",
"balance_last_updated": "2020-12-13T11:20:34.938963Z"
},
]
}
]

Querying a single Payment Source

Once a payment source is created, you can monitor the status of the source with the payment-source endpoint.

Request

customer_id String

The id of the customer who the payment source belongs to.


payment_source_id String

The payment source you want to check the status of.


Response

id String

The ID of the payment source requested.


customer_id String

The customer ID for the requested payment source.


bank_identifier String

The Lean identifier for the bank in which this payment source is held.


status ENUM

The current status of the payment source.

View statuses

ACTIVE The payment source is active and able to make transfers.


AWAITING_BENEFICIARY_COOL_OFF The payment source is in a cooling-off period mandated by the bank. It can take up to 24 hours.


INACTIVE The payment source is no longer active. This could be because your customer removed you as a beneficiary from their account or Lean has lost access to the account.


beneficiary_cool_off_expiry DateTime

When this payment source will be active and ready to make payments


accounts Array

List of accounts within this payment source.

View Account attributes

id String

The id for this account. You can use this to skip the payment sources list when initiating payments in the Link SDK.


account_id String

Warning: Deprecated

The account_id should not be used in your application and will be removed in future versions of the Lean API


account_name String

The display name of this account. This is what your user sees as the name for this account in their bank portals.


account_number String

The bank account number for this account.


iban String

The IBAN for this account.


balance Double

How much balance remains in this account as of the last balance refresh initiated by your customer. Note that this is not a realtime balance of the account and can only be updated by your user during the payment intiiation flow.


currency String

ISO 4217 currency code representing the currency of the balance. A dataset of all countries and their associated codes can be found here.


balance_last_updated DateTime

The timestamp of the last time the balance was updated.

Was this section helpful? 

Endpoint

sandbox.leantech.me/customers/v1/{customer_id}/payment-sources/{payment_source_id}

json

{
"id": "ca57728d-a196-4edb-868f-9f2034b40403",
"customer_id": :"6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"bank_identifier": "HSBC_UAE",
"status" : "ACTIVE",
"beneficiary_cool_off_expiry": "2020-12-13T11:20:34.938963Z",
"accounts": [
{
"id": "9acde98e-9d19-495d-934c-b2ff966262c8",
"account_id": "1457d23a-c1f8-4aee-bc6f-2a253b2e617f",
"account_name": "CURRENT ACCOUNT",
"account_number": "1012019344469",
"iban": "AE340260001012019344469",
"balance": 2436.15,
"currency": "AED",
"balance_last_updated": "2020-12-13T11:20:34.938963Z"
},
]
}