Create a BOOK Transfer from Subledger¶

As of 2026 the API now has a feature to programmatically create BOOK transfers, populating the transaction data with data from the subledger.

This example will demonstrate how to transfer funds between two Subclient Accounts. As described here, Subclient Accounts can be virtual, core, or external accounts. It is important to note that BOOK transfers can only be between accounts that are core or virtual (virtual accounts being part of a core account).

This example will create a BOOK transfer between two core accounts. The process is almost identical when using virtual accounts, except for the steps where the Subclient Account is made - Follow this link for steps to create a Subclient and virtual account.

NOTE - This example uses the same Subclient for both accounts. You can also make BOOK transfers between accounts owned by different Subclients.

Prerequisites¶

The code snippets provided in this scenario require the following variables:

BASE_API_URL - The target GIB API domain, which can be found in the API-Reference.
API_KEY - The API key setup by the client for using the API. Can be generated using the Dashboard.
CORE_ACCOUNT_NUMBER_A - The account number for one of the user's core user accounts.
CORE_ACCOUNT_NUMBER_B - The account number for another of the user's core user accounts.

Step 1 - Create Subclient To Represent Core Accounts¶

Create a Subclient for your company if one does not already exist. If one exists, query the ID using the Subclient: Get endpoint or the API Dashboard.

url = f"{BASE_API_URL}/subclient"

payload = {
    "name": "Test Fintech",
    "external_key": "ABC-123-0001",
    "type": "business",
    "data": {
        "type": "business",
        "legal_name": "Test Fintech LLC",
    },
    "address": {
        "street_address_1": "123 Somewhere St",
        "city": "Sometown",
        "country_alpha_2_code": "US",
    },
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)
response.raise_for_status()

SUBCLIENT_ID = response.json()["id"]

Step 2 - Create First Subclient Account¶

Once a Subclient is created, Subclient Account information can be attached. In this case the subclient_account will be for a core user_account.

url = f"{BASE_API_URL}/subclient/{SUBCLIENT_ID}/account"

payload = {
    "type": "core",
    "account_number": f"{CORE_ACCOUNT_NUMBER_A}",
    "routing_number": "091208154",  # Primary GIB Routing Number
    "description": "Test Fintech Account A",
    "active": True,
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)
response.raise_for_status()

subclient_account = response.json()
SUBCLIENT_ACCOUNT_ID_A = subclient_account["id"]

Step 3 - Create Second Subclient Account¶

Repeat Step 2 but for account B.

url = f"{BASE_API_URL}/subclient/{SUBCLIENT_ID}/account"

payload = {
    "type": "core",
    "account_number": f"{CORE_ACCOUNT_NUMBER_B}",
    "routing_number": "091208154",  # Primary GIB Routing Number
    "description": "Test Fintech Account B",
    "active": True,
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)
response.raise_for_status()

subclient_account = response.json()
SUBCLIENT_ACCOUNT_ID_B = subclient_account["id"]

Step 4 - Create BOOK Transfer Using Subclient Accounts¶

url = f"{BASE_API_URL}/transaction/from-subledger"

payload = {
    "type": "book",
    "origin_subclient_account_id": SUBCLIENT_ACCOUNT_ID_A,
    "destination_subclient_account_id": SUBCLIENT_ACCOUNT_ID_B,
    "amount": 700,  # In cents
    "test": False,
    "simulate": False,
}

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("POST", url, json=payload, headers=headers)
response.raise_for_status()

For Future Transfers - Querying Subclient and Subclient Account IDs¶

If you want to make another BOOK transfer in the future using the same accounts, you would not need to re-create the Subclient or the Subclient Accounts, you will only need to query for the existing IDs.

Use the external key to find the Subclient.

external_key = "ABC-123-0001"
url = f"{BASE_API_URL}/subclient?external_key={external_key}"

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("GET", url, headers=headers)
response.raise_for_status()

subclient_account = response.json()["items"][0]
SUBCLIENT_ID = subclient_account["id"]

Then you can query the Subclient Accounts.

url = f"{BASE_API_URL}/subclient/{SUBCLIENT_ID}/account"

headers = {
    "Content-type": "application/json",
    "Authorization": f"{API_KEY}"
}

response = requests.request("GET", url, headers=headers)
response.raise_for_status()

subclient_accounts = response.json()["items"]
for subclient_account in subclient_accounts:
    if subclient_account["account_number"] == CORE_ACCOUNT_NUMBER_A:
        SUBCLIENT_ACCOUNT_ID_A = subclient_account["id"]
    elif subclient_account["account_number"] == CORE_ACCOUNT_NUMBER_B:
        SUBCLIENT_ACCOUNT_ID_B = subclient_account["id"]

Resources¶

For more information on the endpoints used in this scenario see these API docs: