Light APIv1.0.0

API / Reference / Bank Accounts

Create bank account

POST https://api.light.inc/v1/bank-accounts

Creates a bank account along with its linked ledger (chart-of-accounts) entry in a single transaction. The ledger account code must be a unique 6-digit integer within the company's chart of accounts.

The ledger account is created with fixed attributes you cannot choose: type BANK, active, revalued for FX at end-of-month rates, in the bank account's currency, scoped to the one companyEntityId. Its label defaults to the bank account's name, not the bank name as the description says. code must be exactly six digits (LEDGER_ACCOUNT_CODE_LENGTH) and unused (BANK_ACCOUNT_LEDGER_ACCOUNT_CODE_ALREADY_EXISTS; nothing is created). bankProvider: OTHER requires bankName; other providers fill it in. The response's type and paymentSchedulingEligibility are derived from the provider (only Airwallex accounts are VIRTUAL; only providers Light can pay through are INTERNAL, everything else INELIGIBLE). Company-admin role only.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

Request body

application/json;charset=UTF-8

  • companyEntityId string · uuidrequired

    ID of the company entity this bank account belongs to.

  • name stringrequired

    Bank account display name.

  • bankProvider stringrequired

    Bank provider. Use OTHER if no specific provider applies.

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of ABANCA ABN_AMRO AGRICULTURAL_BANK_OF_CHINA AIRWALLEX AKTIA_BANK ALANDS_BANKEN ANZ_GROUP ARBEJDERNES_LANDSBANK ARION_BANK BANCA_MARCH BANCA_NAZIONALE_DEL_LAVORO BANCO_BPM BANCO_BRADESCO BANCO_DO_BRASIL BANCO_SABADELL BANCO_SANTANDER BANK_NORWEGIAN BANK_OF_AMERICA BANK_OF_BEIJING BANK_OF_CHINA BANK_OF_COMMUNICATIONS BANK_OF_JIANGSU BANK_OF_MONTREAL BANK_OF_NINGBO BANK_OF_SHANGHAI BANK2 BANKINTER BANQUE_PALATINE BARCLAYS BAYERNLB BBVA BCC_MILANO BN_BANK BNP_PARIBAS BNY_MELLON BOURSORAMA CAIXA_ECONOMICA_FEDERAL CAIXABANK CANADIAN_IMPERIAL_BANK_OF_COMMERCE CAPITAL_ONE CHARLES_SCHWAB CHINA_CITIC_BANK CHINA_CONSTRUCTION_BANK CHINA_EVERBRIGHT_BANK CHINA_GUANGFA_BANK CHINA_MERCHANTS_BANK CHINA_MINSHENG_BANK CHINA_ZHESHANG_BANK CITIGROUP COMMERZBANK COMMONWEALTH_BANK CREDIT_AGRICOLE CREDIT_DU_NORD CREDIT_MUTUEL CULTURA_SPAREBANK DANSKE_BANK DBS_GROUP DEUTSCHE_BANK DNB DNB_BANK DZ_BANK ERSTE_GROUP FELLOW_BANK GOLDMAN_SACHS GRASSHOPPER GROUPE_BPCE HANA_FINANCIAL HANDELSBANKEN HDFC_BANK HELABA HSBC HSBC_FRANCE HUAXIA_BANK HYPO IKANO_BANK INDUSTRIAL_AND_COMMERCIAL_BANK_OF_CHINA INDUSTRIAL_BANK INDUSTRIAL_BANK_OF_KOREA ING_DIBA ING_GROUP ING_SPAIN INSTABANK INTESA_SANPAOLO ISLANDSBANKI ITAU_UNIBANCO JAPAN_POST_BANK JPM_CHASE JYSKE KB_FINANCIAL_GROUP KBC_GROUP KFW_BANK KUTXABANK LA_BANQUE_POSTALE LANDKREDITT_BANK LANDESBANK_BADEN_WURTTEMBERG LANDESBANK_BADEN_WURTTEMBERG_LBBW LANDESBANK_BERLIN LANDSBANKINN LANSFORSAKRINGAR_BANK LLOYDS_BANK LLOYDS_BANKING_GROUP MERCURY MITSUBISHI_UFJ_FINANCIAL_GROUP MIZUHO_FINANCIAL_GROUP MONZO MORGAN_STANLEY NATIONAL_AUSTRALIA_BANK NATIONAL_BANK_OF_CANADA NATIONWIDE_BUILDING_SOCIETY NATWEST NATWEST_GROUP NOMURA_HOLDINGS NONGHYUP_BANK NORDEA NORDLB NORINCHUKIN_BANK NYKREDIT_BANK OCBC OP_BANK OTHER PARETO_BANK PAYPAL PING_AN_BANK PNC_FINANCIAL_SERVICES POP_PANKKI POSTAL_SAVINGS_BANK_OF_CHINA QATAR_NATIONAL_BANK RABOBANK RAIFFEISEN_GROUP RESONA_HOLDINGS REVOLUT RINGKJOBING_LANDBOBANK ROYAL_BANK_OF_CANADA S_PANKKI SANTANDER SANTANDER_UK SAXO_BANK SBANKEN SBERBANK_RUSSIA SCOTIABANK SEB SHANGHAI_PUDONG_DEVELOPMENT_BANK SHINHAN_FINANCIAL SMBC_GROUP SOCIETE_GENERALE SPAR_NORD_BANK STANDARD_CHARTERED STARLING_BANK STATE_BANK_OF_INDIA STOREBRAND_BANK STRIPE SUMITOMO_MITSUI_TRUST SVB SVENSKA_HANDELSBANKEN SWEDBANK SYDBANK TORONTO_DOMINION_BANK TRUIST_FINANCIAL TSB_BANK UBS UNICAJA_BANCO UNICREDIT UNICREDIT_BANK_HYPOVEREINSBANK UNITED_OVERSEAS_BANK US_BANCORP VEKSELBANKEN VIRGIN_MONEY WELLS_FARGO WESTPAC WISE WINTRUST_BANK WOORI_FINANCIAL YA_BANK ZKB

  • currency stringrequired

  • bankCountry stringrequired

    Bank country (ISO 3166-1 alpha-2).

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

  • ledgerAccount objectrequired

    Ledger account (chart of accounts entry) created and linked to this bank account.

    • code integer · int32required

      Ledger account code. Must be a unique 6-digit integer within the company's chart of accounts.

    • label string

      Ledger account label. Defaults to the bank name when omitted.

  • iban string

    IBAN. Required (with BIC) for IBAN countries.

  • bic string

    BIC / SWIFT code. Required (with IBAN) for IBAN countries.

  • domesticBankAccountNumber string

    Domestic bank account number. Used for non-IBAN countries; must be paired with domesticBankCode.

  • domesticBankCode string

    Domestic bank code (e.g. routing/sort code). Must be paired with domesticBankAccountNumber.

  • bankName string

    Bank name.

  • bankCity string

    Bank city.

  • bankAddress string

    Bank street address.

  • bankZipcode string

    Bank ZIP / postal code.

  • bankState string

    Bank state / region.

  • defaultChargeBearerCode string

    Default charge bearer for international transfers. OUR = sender pays all fees, SHAR = fees shared.

    • OUR - Sender pays all fees
    • SHAR - Fees are shared between sender and receiver

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of OUR SHAR

Response

  • id string · uuid

    Unique identifier for the bank account object

  • companyId string · uuid

    ID of the company

  • companyEntityId string · uuid

    ID of the entity

  • name string

    Bank account display name

  • type string

    Type of the bank account (physical or virtual)

    • PHYSICAL - A physical bank account
    • VIRTUAL - A virtual bank account

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of PHYSICAL VIRTUAL

  • bankProvider string

    Bank provider

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of ABANCA ABN_AMRO AGRICULTURAL_BANK_OF_CHINA AIRWALLEX AKTIA_BANK ALANDS_BANKEN ANZ_GROUP ARBEJDERNES_LANDSBANK ARION_BANK BANCA_MARCH BANCA_NAZIONALE_DEL_LAVORO BANCO_BPM BANCO_BRADESCO BANCO_DO_BRASIL BANCO_SABADELL BANCO_SANTANDER BANK_NORWEGIAN BANK_OF_AMERICA BANK_OF_BEIJING BANK_OF_CHINA BANK_OF_COMMUNICATIONS BANK_OF_JIANGSU BANK_OF_MONTREAL BANK_OF_NINGBO BANK_OF_SHANGHAI BANK2 BANKINTER BANQUE_PALATINE BARCLAYS BAYERNLB BBVA BCC_MILANO BN_BANK BNP_PARIBAS BNY_MELLON BOURSORAMA CAIXA_ECONOMICA_FEDERAL CAIXABANK CANADIAN_IMPERIAL_BANK_OF_COMMERCE CAPITAL_ONE CHARLES_SCHWAB CHINA_CITIC_BANK CHINA_CONSTRUCTION_BANK CHINA_EVERBRIGHT_BANK CHINA_GUANGFA_BANK CHINA_MERCHANTS_BANK CHINA_MINSHENG_BANK CHINA_ZHESHANG_BANK CITIGROUP COMMERZBANK COMMONWEALTH_BANK CREDIT_AGRICOLE CREDIT_DU_NORD CREDIT_MUTUEL CULTURA_SPAREBANK DANSKE_BANK DBS_GROUP DEUTSCHE_BANK DNB DNB_BANK DZ_BANK ERSTE_GROUP FELLOW_BANK GOLDMAN_SACHS GRASSHOPPER GROUPE_BPCE HANA_FINANCIAL HANDELSBANKEN HDFC_BANK HELABA HSBC HSBC_FRANCE HUAXIA_BANK HYPO IKANO_BANK INDUSTRIAL_AND_COMMERCIAL_BANK_OF_CHINA INDUSTRIAL_BANK INDUSTRIAL_BANK_OF_KOREA ING_DIBA ING_GROUP ING_SPAIN INSTABANK INTESA_SANPAOLO ISLANDSBANKI ITAU_UNIBANCO JAPAN_POST_BANK JPM_CHASE JYSKE KB_FINANCIAL_GROUP KBC_GROUP KFW_BANK KUTXABANK LA_BANQUE_POSTALE LANDKREDITT_BANK LANDESBANK_BADEN_WURTTEMBERG LANDESBANK_BADEN_WURTTEMBERG_LBBW LANDESBANK_BERLIN LANDSBANKINN LANSFORSAKRINGAR_BANK LLOYDS_BANK LLOYDS_BANKING_GROUP MERCURY MITSUBISHI_UFJ_FINANCIAL_GROUP MIZUHO_FINANCIAL_GROUP MONZO MORGAN_STANLEY NATIONAL_AUSTRALIA_BANK NATIONAL_BANK_OF_CANADA NATIONWIDE_BUILDING_SOCIETY NATWEST NATWEST_GROUP NOMURA_HOLDINGS NONGHYUP_BANK NORDEA NORDLB NORINCHUKIN_BANK NYKREDIT_BANK OCBC OP_BANK OTHER PARETO_BANK PAYPAL PING_AN_BANK PNC_FINANCIAL_SERVICES POP_PANKKI POSTAL_SAVINGS_BANK_OF_CHINA QATAR_NATIONAL_BANK RABOBANK RAIFFEISEN_GROUP RESONA_HOLDINGS REVOLUT RINGKJOBING_LANDBOBANK ROYAL_BANK_OF_CANADA S_PANKKI SANTANDER SANTANDER_UK SAXO_BANK SBANKEN SBERBANK_RUSSIA SCOTIABANK SEB SHANGHAI_PUDONG_DEVELOPMENT_BANK SHINHAN_FINANCIAL SMBC_GROUP SOCIETE_GENERALE SPAR_NORD_BANK STANDARD_CHARTERED STARLING_BANK STATE_BANK_OF_INDIA STOREBRAND_BANK STRIPE SUMITOMO_MITSUI_TRUST SVB SVENSKA_HANDELSBANKEN SWEDBANK SYDBANK TORONTO_DOMINION_BANK TRUIST_FINANCIAL TSB_BANK UBS UNICAJA_BANCO UNICREDIT UNICREDIT_BANK_HYPOVEREINSBANK UNITED_OVERSEAS_BANK US_BANCORP VEKSELBANKEN VIRGIN_MONEY WELLS_FARGO WESTPAC WISE WINTRUST_BANK WOORI_FINANCIAL YA_BANK ZKB

  • paymentSchedulingEligibility string

    Payment scheduling eligibility for this bank account

    • INTERNAL - Eligible for payment scheduling via Light internal capabilities
    • BANK_PROVIDER - Eligible for payment scheduling via the bank provider
    • INELIGIBLE - Not eligible for payment scheduling

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    Derived from the provider: INTERNAL for banks Light can pay through, otherwise INELIGIBLE. Accounts created here never come back as BANK_PROVIDER.

    One of INTERNAL BANK_PROVIDER INELIGIBLE

  • iban string

    IBAN

  • bic string

    BIC / SWIFT code

  • domesticBankAccountNumber string

    Domestic bank account number

  • domesticBankCode string

    Domestic bank code / routing code

  • currency string

  • bankCountry string

    Bank country (ISO 3166-1 alpha-2)

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of UNDEFINED AC AD AE AF AG AI AL AM AN AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BU BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CP CR CS CU CV CW CX CY CZ DE DG DJ DK DM DO DZ EA EC EE EG EH ER ES ET EU EZ FI FJ FK FM FO FR FX GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU IC ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NT NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SF SG SH SI SJ SK SL SM SN SO SR SS ST SU SV SX SY SZ TA TC TD TF TG TH TJ TK TL TM TN TO TP TR TT TV TW TZ UA UG UK UM US UY UZ VA VC VE VG VI VN VU WF WS XI XU XK YE YT YU ZA ZM ZR ZW

  • bankCity string

    Bank city

  • bankAddress string

    Bank address

  • bankZipcode string

    Bank ZIP / postal code

  • bankName string

    Bank name

  • bankState string

    Bank state / region

  • ledgerAccountCode integer · int32

    Ledger account code linked to this bank account

  • createdAt string · date-time

    Timestamp when the bank account was created