We have improved navigation between the Guides and API Reference sections. When you are reviewing the API Reference documentation for an endpoint, you now find links to the relevant Guides sections for more information, sample requests, and responses.
We have updated the webhooks events catalog to include event types for bank accounts and BILL risk verification. You can now set up subscriptions to receive notifications for these new events.
| New events | Related documentation |
|---|---|
bank-account.createdbank-account.updated | Bank account notification payloads |
risk-verification.updated | Risk verification notification payloads |
See Get events catalog in the API reference for more information.
When you create a new webhook subscription with POST /v3/subscriptions, you now get a one-time securityKey as one of the generated values in the response. All event notifications sent to your notificationUrl are signed with the security key using the HMAC-SHA256 algorithm. The key is sent as the x-bill-sha-signature header value in the notification.
You can use the security key to verify all notifications sent to you. It is good practice to keep the security key for your subscription updated in a timely manner. Use POST /v3/subscriptions/{subscriptionId}/security_key to generate a new security key based on your desired frequency.
See Create a security key in the API reference for more information.
You can now create multiple bills with a single POST /v3/bills/bulk API call. Bulk bill creation at BILL follows a set of rules.
See Bills for more information.
We have introduced PENDING as a new BILL risk verification decision status for your organization.
As a BILL partner, when you create an organization and then create a user for that organization, it is important that you initiate risk verification with POST /v3/risk-verifications. In the API response, the BILL risk verification decision status can now have one of five values.
| Value | Description |
|---|---|
REVIEW | Risk verification is in progress |
PENDING | Risk verification is in progress. BILL waiting for more information about vendors in the organization. BILL requests the vendor in question for more information. |
HOLD | Risk verification is complete. BILL has set the approval on hold. BILL requests the organization owner for more information. |
APPROVE | Risk verification is complete. BILL has approved the organization for BILL AP and AR operations. |
DECLINE | Risk verification is complete. BILL has declined the organization. |
See Users for BILL partners for more information.
For verified national vendors like Comcast or PG&E, you can now filter your BILL network search by your billing statement accountNumber. See GET /v3/network in the API reference for more information.
When updating a bill (PATCH /v3/bills/{billId}) or replacing a bill (PUT /v3/bills/{billId}), we learned that there was an error response if the bill had a duplicate invoice number. We have now fixed this issue.
You can now filter payments by the transactionNumber field. See Search operations with lists for more information about the complete list of fields you can filter and sort with.
You can now get a list of users with GET /v3/users. In the response, you get the list of users that belong to the organization you are signed in to. See GET /v3/users in the API reference for more information.
As a BILL partner, you now have the additional capability of getting a list of users that belong to any of your created organizations. See GET /v3/partner/users in the API reference for more information.
You can now set the transactionNumber field when you create a payment (POST /v3/payments) or bulk payment (POST /v3/payments/bulk).
You can set transactionNumber as a unique alphanumeric value for your system to track a payment transaction. The value must be 50 characters or fewer. If you do not set transactionNumber, BILL sets this field as a unique alphanumeric payment identification value.
See /v3/payments in the API reference for more information.