Guides
System Status
Start typing to search…

Bank account notification payloads

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. See /v3/funding-accounts/banks in the API reference for more information about the request and response fields.

Sample bank-account.created payload

In this sample unescaped JSON payload, the details of a bank account are available. All the fields are included in each bank-account.created payload.

Field

Description

id

BILL-generated ID of the bank account. The value begins with bac.

archived

Set as true if the bank account is archived

accountNumber

Bank account number

nameOnAccount

Full name on bank account

routingNumber

Bank routing number

bankName

Bank name

status

Bank account status (NOT_VERIFIED, VERIFIED, PENDING, BLOCKED, EXPIRED, INVALID, or UNDEFINED)

createdBy

BILL-generated ID of the user that created the bank account. This value begins with 006.

type

Bank account type (CHECKING or SAVINGS)

ownerType

Bank account owner type (BUSINESS or PERSONAL)

createdTime

Created date and time

updatedTime

Updated date and time

default

Bank account default values for BILL AP and AR operations.

  • payables: Set as true if the bank account is set as default for AP operations
  • receivables: Set as true if the bank account is set as default for AR operations
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.created",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": true,
        "accountNumber": "*****2333",
        "nameOnAccount": "Noodle Soupsmith",
        "routingNumber": "074000010",
        "bankName": "Chase",
        "status": "PENDING",
        "createdBy": "{user_id}",
        "type": "CHECKING",
        "ownerType": "BUSINESS",
        "createdTime": "2025-12-16T23:15:23.127+00:00",
        "updatedTime": "2025-12-16T23:15:23.127+00:00",
        "default": {
            "payables": false,
            "receivables": false
        }
    }
}

Sample bank-account.updated payloads

BILL sends bank-account.updated notifications for a set of operations.

Fields that trigger bank-account.updated notifications

When changes are made to a set of fields in a bank account, the bank-account.updated notification is triggered.

FieldDescription
archivedSet as true if the bank account is archived
statusBank account status
default.payablesSet as true if the bank account is set as default for AP operations
default.receivablesSet as true if the bank account is set as default for AR operations

Bank account status values

In this sample unescaped JSON payload, the details of an updated bank account are available.

When the status changes from PENDING to VERIFIED, the archived value is set as false.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": false,
        "accountNumber": "*****2333",
        "nameOnAccount": "Noodle Soupsmith",
        "routingNumber": "074000010",
        "bankName": "Chase",
        "status": "VERIFIED",
        "createdBy": "{user_id}",
        "type": "CHECKING",
        "ownerType": "BUSINESS",
        "createdTime": "2025-12-16T23:15:23.127+00:00",
        "updatedTime": "2025-12-19T23:15:23.127+00:00",
        "default": {
            "payables": false,
            "receivables": false
        }
    }
}

When the status changes from VERIFIED to NOT_VERIFIED, the archived value is set as true.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": true,
        "accountNumber": "*****2333",
        "nameOnAccount": "Noodle Soupsmith",
        "routingNumber": "074000010",
        "bankName": "Chase",
        "status": "NOT_VERIFIED",
        "createdBy": "{user_id}",
        "type": "CHECKING",
        "ownerType": "BUSINESS",
        "createdTime": "2025-12-16T23:15:23.127+00:00",
        "updatedTime": "2025-12-20T23:15:23.127+00:00",
        "default": {
            "payables": false,
            "receivables": false
        }
    }
}

When the bank account status is PENDING, EXPIRED, or BLOCKED, the archived value is set as true.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": true,
        "accountNumber": "*****2333",
        "nameOnAccount": "Noodle Soupsmith",
        "routingNumber": "074000010",
        "bankName": "Chase",
        "status": "{PENDING, EXPIRED, or BLOCKED}",
        "createdBy": "{user_id}",
        "type": "CHECKING",
        "ownerType": "BUSINESS",
        "createdTime": "2025-12-16T23:15:23.127+00:00",
        "updatedTime": "2025-12-19T23:15:23.127+00:00",
        "default": {
            "payables": false,
            "receivables": false
        }
    }
}

default values for AP and AR operations

In this sample unescaped JSON payload, the details of an updated bank account are available.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": false,
        "accountNumber": "*****2333",
        "nameOnAccount": "Noodle Soupsmith",
        "routingNumber": "074000010",
        "bankName": "Chase",
        "status": "VERIFIED",
        "createdBy": "{user_id}",
        "type": "CHECKING",
        "ownerType": "BUSINESS",
        "createdTime": "2025-12-16T23:15:23.127+00:00",
        "updatedTime": "2025-12-20T23:15:23.127+00:00",
        "default": {
            "payables": true,
            "receivables": true
        }
    }
}

Updated 3 days ago