This endpoint retrieves an employee's bank accounts. The response object is region-aware. Fields not applicable to the employee's payroll region will not be returned.
https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accountsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of bank account records. Each entry in the array is a separate bank account object. If there is no more bank accounts, the resulting array will be empty.
How the employee's pay is split between their bank accounts.
Unique identifier for the bank account.
The currency code for the bank account (e.g., "SGD").
The name of the bank account.
The type of bank account.
The account number of the bank account.
The BSB (Bank State Branch) number for Australian bank accounts.
The amount associated with the bank account.
Indicates whether this is the primary bank account. The primary account receives the remainder of the bank split.
The lock level for the bank account (e.g., employee).
External identifier for the bank account.
Text that appears on bank statements.
The roll number for the bank account.
The bank branch information.
The name of the bank.
The bank code.
The SWIFT/BIC code for the bank.
The address of the bank.
The name of the bank branch.
The branch code.
The institute number for the bank.
The payment method associated with the account.
The transit number for the bank account.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "bank_split_type": "percentage", "items": [ { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "currency": "AUD", "account_name": "account_name", "account_type": "account_type", "account_number": "account_number", "bsb": "cbs", "amount": "100", "primary_account": true, "lock_level": "employee", "external_id": "external_id", "statement_text": "statement text", "roll_number": "roll_number", "bank_branch": "bank_branch", "bank_name": "bank_name", "bank_code": "bank_code", "bank_swift_bic": "bank_swift_bic", "bank_address": "bank_address", "branch_name": "branch_name", "branch_code": "branch_code", "institute_number": "institute_number", "payment_method": "payment_method", "transit_number": "transit_number" } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a list of all bank accounts for a specific employee.
https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/bank_accountsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of bank account records. Each entry in the array is a separate bank account object. If there is no more bank accounts, the resulting array will be empty.
Unique identifier for the object.
The account name of a bank account.
The account number of a bank account.
The bsb number of a bank account.
The amount of a bank account.
The boolean flag to determine whether this bank account is primary or not.
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/bank_accounts" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "account_name": "Daniel Nguyen", "account_number": "111111111", "bsb": "111111", "amount": 100, "primary_account": true } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint adds a bank account to an employee. The fields that can be set depend on the employee's country and account type.
Supported regions
Singapore and Malaysia are not supported yet. Calling this endpoint for an
employee in Singapore or Malaysia returns a 422 error.
https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accountsPath Parameters
The ID of the organisation.
The ID of the employee to add the bank account to.
Request Body
The amount is set by the server and cannot be sent: it is 0, except for the first account of a percentage split, which is 100. The first account is the primary account. Use Update Bank Split to change amounts.
Send only the fields that apply to the employee's country and account type. A field that does not apply, or a lock_level you are not allowed to set, returns 422.
The account type, in snake case. Defaults to electronic.
- AU:
electronic. KeyPay organisations can also usebpay, and KeyPay organisations with AIO can also usecash_or_cheque. - UK:
electronic, orcash_or_chequefor AIO organisations.
Responses return the stored value in PascalCase (for example CashOrCheque).
The payment method. Defaults to direct_deposit. A cheque account takes only account_name. An other account takes no account details.
The name of the account.
- AU, NZ, VN: Required.
- UK: Required, except for
cash_or_chequeaccounts of AIO organisations. - CA: Required for
direct_depositandchequeaccounts.
The account number. Required, except for cash_or_cheque accounts and Canadian cheque and other accounts. Spaces and hyphens are removed before validation. Must not duplicate another account of the same employee.
- AU: Digits only, up to 10 for
electronicaccounts. Forbpayaccounts, the customer reference number: 6 to 20 digits. - UK: Digits only, up to 8.
- NZ: Digits only, up to 16.
- CA: 7 to 12 digits.
- PH (Global Teams): Exactly 12 digits.
- VN: No format restriction.
The bank identifier. Required, except for cash_or_cheque accounts.
- AU: The BSB for
electronicaccounts, in the formatxxx-xxx,xxx xxxorxxxxxx. Forbpayaccounts, the biller code: 4 to 6 digits. - UK: The sort code: exactly 6 digits, with no spaces or hyphens.
The text that appears on bank statements. AU only. Required for Xero organisations, which allow letters, numbers and spaces only. For organisations not on Xero, the value is discarded.
The roll number of the account. UK only.
The 3-digit institution number. Required for Canadian direct_deposit accounts.
The 5-digit transit number. Required for Canadian direct_deposit accounts.
Who can edit the account. Defaults to employee on create; omitting it on update keeps the current value. Employees can set employee. Owners and admins can set employee or organisation. system requires permission to change the bank account type. Australian employees not on KeyPay can only be set to employee. Re-sending the current value is always accepted.
The ISO 4217 currency code of the account, for example PHP. Required for PH Global Teams employees, who are the only ones who can send it.
The name of the bank. VN and PH Global Teams employees only.
- VN: Required.
- PH (Global Teams): Required.
The SWIFT/BIC code of the bank, 8 to 11 characters. Required for PH Global Teams employees, who are the only ones who can send it.
The address of the bank. Required for PH Global Teams employees, who are the only ones who can send it.
The name of the bank branch. VN and PH Global Teams employees only.
- VN: Required.
- PH (Global Teams): Required.
Response Body
Returns the created bank account on 201 Created, including its id for use with the other bank account endpoints.
Unique identifier for the bank account.
The currency code for the bank account (e.g., "SGD").
The name of the bank account.
The type of bank account.
The account number of the bank account.
The BSB (Bank State Branch) number for Australian bank accounts.
The amount associated with the bank account.
Indicates whether this is the primary bank account. The primary account receives the remainder of the bank split.
The lock level for the bank account (e.g., employee).
External identifier for the bank account.
Text that appears on bank statements.
The roll number for the bank account.
The bank branch information.
The name of the bank.
The bank code.
The SWIFT/BIC code for the bank.
The address of the bank.
The name of the bank branch.
The branch code.
The institute number for the bank.
The payment method associated with the account.
The transit number for the bank account.
Example
curl -X POST \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "account_type": "electronic", "account_name": "Jane Citizen", "bsb": "062-000", "account_number": "12345678", "lock_level": "employee" }'Response
{ "data": { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "currency": "AUD", "account_name": "account_name", "account_type": "account_type", "account_number": "account_number", "bsb": "cbs", "amount": "100", "primary_account": true, "lock_level": "employee", "external_id": "external_id", "statement_text": "statement text", "roll_number": "roll_number", "bank_branch": "bank_branch", "bank_name": "bank_name", "bank_code": "bank_code", "bank_swift_bic": "bank_swift_bic", "bank_address": "bank_address", "branch_name": "branch_name", "branch_code": "branch_code", "institute_number": "institute_number", "payment_method": "payment_method", "transit_number": "transit_number" }}This endpoint updates the details of an employee's bank account. To change how pay is split between accounts, use Update Bank Split.
Supported regions
Singapore and Malaysia are not supported yet. Calling this endpoint for an
employee in Singapore or Malaysia returns a 422 error.
https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts/:bank_account_idPath Parameters
The ID of the organisation.
The ID of the employee.
The ID of the bank account to update.
Request Body
Updates only the fields you send. Fields you leave out are unchanged.
The amount and primary status of an account cannot be changed here. Use Update Bank Split instead.
The same country and account type rules as Create Bank Account apply.
The account type, in snake case. Defaults to electronic.
- AU:
electronic. KeyPay organisations can also usebpay, and KeyPay organisations with AIO can also usecash_or_cheque. - UK:
electronic, orcash_or_chequefor AIO organisations.
Responses return the stored value in PascalCase (for example CashOrCheque).
The payment method. Defaults to direct_deposit. A cheque account takes only account_name. An other account takes no account details.
The name of the account.
- AU, NZ, VN: Required.
- UK: Required, except for
cash_or_chequeaccounts of AIO organisations. - CA: Required for
direct_depositandchequeaccounts.
The account number. Required, except for cash_or_cheque accounts and Canadian cheque and other accounts. Spaces and hyphens are removed before validation. Must not duplicate another account of the same employee.
- AU: Digits only, up to 10 for
electronicaccounts. Forbpayaccounts, the customer reference number: 6 to 20 digits. - UK: Digits only, up to 8.
- NZ: Digits only, up to 16.
- CA: 7 to 12 digits.
- PH (Global Teams): Exactly 12 digits.
- VN: No format restriction.
The bank identifier. Required, except for cash_or_cheque accounts.
- AU: The BSB for
electronicaccounts, in the formatxxx-xxx,xxx xxxorxxxxxx. Forbpayaccounts, the biller code: 4 to 6 digits. - UK: The sort code: exactly 6 digits, with no spaces or hyphens.
The text that appears on bank statements. AU only. Required for Xero organisations, which allow letters, numbers and spaces only. For organisations not on Xero, the value is discarded.
The roll number of the account. UK only.
The 3-digit institution number. Required for Canadian direct_deposit accounts.
The 5-digit transit number. Required for Canadian direct_deposit accounts.
Who can edit the account. Defaults to employee on create; omitting it on update keeps the current value. Employees can set employee. Owners and admins can set employee or organisation. system requires permission to change the bank account type. Australian employees not on KeyPay can only be set to employee. Re-sending the current value is always accepted.
The ISO 4217 currency code of the account, for example PHP. Required for PH Global Teams employees, who are the only ones who can send it.
The name of the bank. VN and PH Global Teams employees only.
- VN: Required.
- PH (Global Teams): Required.
The SWIFT/BIC code of the bank, 8 to 11 characters. Required for PH Global Teams employees, who are the only ones who can send it.
The address of the bank. Required for PH Global Teams employees, who are the only ones who can send it.
The name of the bank branch. VN and PH Global Teams employees only.
- VN: Required.
- PH (Global Teams): Required.
Response Body
Returns the updated bank account on 200 OK.
Unique identifier for the bank account.
The currency code for the bank account (e.g., "SGD").
The name of the bank account.
The type of bank account.
The account number of the bank account.
The BSB (Bank State Branch) number for Australian bank accounts.
The amount associated with the bank account.
Indicates whether this is the primary bank account. The primary account receives the remainder of the bank split.
The lock level for the bank account (e.g., employee).
External identifier for the bank account.
Text that appears on bank statements.
The roll number for the bank account.
The bank branch information.
The name of the bank.
The bank code.
The SWIFT/BIC code for the bank.
The address of the bank.
The name of the bank branch.
The branch code.
The institute number for the bank.
The payment method associated with the account.
The transit number for the bank account.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts/:bank_account_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "account_name": "Jane Citizen", "account_number": "87654321", "lock_level": "organisation" }'Response
{ "data": { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "currency": "AUD", "account_name": "account_name", "account_type": "account_type", "account_number": "account_number", "bsb": "cbs", "amount": "100", "primary_account": true, "lock_level": "employee", "external_id": "external_id", "statement_text": "statement text", "roll_number": "roll_number", "bank_branch": "bank_branch", "bank_name": "bank_name", "bank_code": "bank_code", "bank_swift_bic": "bank_swift_bic", "bank_address": "bank_address", "branch_name": "branch_name", "branch_code": "branch_code", "institute_number": "institute_number", "payment_method": "payment_method", "transit_number": "transit_number" }}This endpoint removes a bank account from an employee.
Supported regions
Singapore and Malaysia are not supported yet. Calling this endpoint for an
employee in Singapore or Malaysia returns a 422 error.
https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts/:bank_account_idPath Parameters
The ID of the organisation.
The ID of the employee.
The ID of the bank account to delete.
Request Body
Only a non-primary bank account with an amount of 0 can be deleted. To move an amount off an account first, use Update Bank Split.
Response Body
Returns 204 No Content when the bank account has been deleted.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts/:bank_account_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
This endpoint sets how an employee's pay is split between their bank accounts. The primary account receives whatever remains after the other accounts are allocated.
Supported regions
Singapore and Malaysia are not supported yet. Calling this endpoint for an
employee in Singapore or Malaysia returns a 422 error.
https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts/bank_splitPath Parameters
The ID of the organisation.
The ID of the employee.
Request Body
Sets the split type and the amount of every non-primary account. The primary account receives the remainder. In percentage mode it receives 100 minus the total of the other percentages. In fixed_amount mode its amount is 0.
Amounts must not be negative. Fixed amounts can have decimals, but percentages must be whole numbers and their total must not exceed 100. Xero NZ employees cannot use percentage.
The split type. percentage gives each account a share of the pay. fixed_amount gives each account a fixed amount.
The amount for every non-primary bank account. List each non-primary account exactly once, and do not include the primary account.
Response Body
Returns 200 OK with the employee's bank accounts in data.items and the split type now in effect in data.bank_split_type.
The employee's bank accounts after the split.
Unique identifier for the bank account.
The currency code for the bank account (e.g., "SGD").
The name of the bank account.
The type of bank account.
The account number of the bank account.
The BSB (Bank State Branch) number for Australian bank accounts.
The amount associated with the bank account.
Indicates whether this is the primary bank account. The primary account receives the remainder of the bank split.
The lock level for the bank account (e.g., employee).
External identifier for the bank account.
Text that appears on bank statements.
The roll number for the bank account.
The bank branch information.
The name of the bank.
The bank code.
The SWIFT/BIC code for the bank.
The address of the bank.
The name of the bank branch.
The branch code.
The institute number for the bank.
The payment method associated with the account.
The transit number for the bank account.
The split type now in effect: percentage or fixed_amount.
Example
curl -X PUT \ "https://api.employmenthero.com/api/v2/organisations/:organisation_id/employees/:employee_id/bank_accounts/bank_split" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "bank_split_type": "percentage", "bank_accounts": [ { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "amount": 30 }, { "id": "0b8f7e2a-3c1d-4f5e-9a6b-7c8d9e0f1a2b", "amount": 20 } ] }'Response
{ "data": { "items": [ { "id": "6ddbfb24-8153-42a9-9248-c41c9b6c755e", "currency": "AUD", "account_name": "account_name", "account_type": "account_type", "account_number": "account_number", "bsb": "cbs", "amount": "100", "primary_account": true, "lock_level": "employee", "external_id": "external_id", "statement_text": "statement text", "roll_number": "roll_number", "bank_branch": "bank_branch", "bank_name": "bank_name", "bank_code": "bank_code", "bank_swift_bic": "bank_swift_bic", "bank_address": "bank_address", "branch_name": "branch_name", "branch_code": "branch_code", "institute_number": "institute_number", "payment_method": "payment_method", "transit_number": "transit_number" } ], "bank_split_type": "percentage" }}