Guides
System Status

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. The notification includes a set of bank-account fields. All the fields are included in each bank-account.created payload.

FieldDescription
idBILL-generated ID of the bank account. The value begins with bac.
archivedSet as true if the bank account is archived
accountNumberBank account number
nameOnAccountFull name on bank account
routingNumberBank routing number
bankNameBank name
statusBank account status (NOT_VERIFIED, VERIFIED, PENDING, BLOCKED, EXPIRED, INVALID, or UNDEFINED)
createdByBILL-generated ID of the user that created the bank account. This value begins with 006.
typeBank account type (CHECKING or SAVINGS)
ownerTypeBank account owner type (BUSINESS or PERSONAL)
createdTimeCreated date and time
defaultBank account default values for BILL AP and 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",
        "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. In addition, the bank account id and updatedTime is available.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": false,
        "status": "VERIFIED",
        "updatedTime": "2025-12-17T23:15:23.127+00:00"
    }
}

When the status changes from VERIFIED to NOT_VERIFIED, the archived value is set as true. In addition, the bank account id and updatedTime is available.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "archived": true,
        "status": "NOT_VERIFIED",
        "updatedTime": "2025-12-18T23:15:23.127+00:00"
    }
}

When the bank account status is PENDING, EXPIRED, or BLOCKED, the archived value is set as true and is not available in the bank-account.updated payload. In addition, the bank account id and updatedTime is available.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "status": "{PENDING, EXPIRED, or BLOCKED}",
        "updatedTime": "2025-12-18T23:15:23.127+00:00"
    }
}

default values for AP and AR operations

In this sample unescaped JSON payload, the details of an updated bank account are available. The notification includes three bank-account fields.

FieldDescription
idBILL-generated ID of the bank account. The value begins with bac.
defaultBank 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
updatedTimeUpdated date and time
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "bank-account.updated",
        "version": "1"
    },
    "bank-account": {
        "id": "{bankaccount_id}",
        "default": {
          "receivables": false
        },
        "updatedTime": "2025-12-19T23:15:23.127+00:00"
    }
}

Updated 24 days ago