In the vendors API response, we have introduced a new transferMethod field. This field provides the default payment delivery method for international payments. This field is set when payBySubType is set as MULTIPLE.
LOCAL: Funds transferred with the vendor country's domestic payment network
WIRE: Funds transferred with bank-operated networks (For example, SWIFT)
In the Get list of vendors (GET /v3/vendors) and Get vendor details (GET /v3/vendors/{vendorId}) API response, you now get the new transferMethod field.
See GET /v3/vendors in the API reference for more information.
In the documents API response, we have introduced two new fields - scanStatus and numOfPages. In all the documents API responses, you can now get detailed information about an uploaded document. This information includes the document scan status and the number of pages in a CLEAN document.
Field
Description
scanStatus
Document scan status (NOT_SCANNED, CLEAN, INFECTED, IN_QUEUE, REJECTED, or UNDEFINED)
On the vendor's bank location screen, we have added the ability to lock bill currency selection. You can now control whether the user will be able to select bill currency preferences. This change helps with preventing any accidental changes and with ensuring currency consistency.
Bug fixes
Onboarding and Adding funding widget
We learned that the Add a payment method form was not working as expected after a user re-entered their account number. We have fixed this issue.
We learned that the account number mismatch error was appearing before a user completed re-entering their account number. We have fixed this issue. The account number mismatch error now appears only when the re-entered account number entry is complete and if the number is a mismatch.
March 30, 2026 onwards, BILL will remove the ability to add or use a secondary phone number for MFA operations. After this change, MFA operations will be available only with the primary phone number.
Use primary MFA phone number
When you add a phone number for MFA setup with the POST /v3/mfa/setup API endpoint, you currently have the ability to set primary as false in your API request for adding a secondary or backup phone number. Any added phone number can be used for generating an MFA challenge with POST /v3/mfa/challenge or POST /v2/MFAChallenge.json.
March 30, 2026 onwards, BILL will remove the ability to add or use a secondary phone number for MFA operations. This change will be in both the sandbox and production environments.
After this change, generating an MFA challenge will be available only with the primary phone number.
Upcoming V3 API changes
March 30, 2026 onwards, you will no longer be able to set primary as false in your POST /v3/mfa/setup API request. In addition, the primary field will no longer be required in this API request. When you set primary as false in your API request, you will get an HTTP 400 response and an error message.
March 30, 2026 onwards, you will no longer be able to set useBackup as true in your POST /v3/mfa/challenge API request. In addition, the useBackup field will no longer be required in this API request. When you set useBackup as true in your API request, you will get an HTTP 400 response and an error message.
Upcoming V2 API changes
March 30, 2026 onwards, you will no longer be able to set useBackup as true in your POST /v2/MFAChallenge.json API request. When you set the useBackup field as true in your API request, you will get an error message.
Developer actions
If you rely on a secondary phone number for MFA operations in your integration with the BILL API, update your integration to use only the primary MFA phone number before March 30, 2026.
If you use the POST /v3/mfa/setup endpoint, set primary as true or remove the primary field in the body of your API request. Setting the primary field will be optional.
If you use the POST /v3/mfa/challenge endpoint, set useBackup as false or remove the useBackup field in the body of your API request. Setting the useBackup field will be optional.
If you use the POST /v2/MFAChallenge.json endpoint, set useBackup as false or remove the useBackup field in the body of your API request. Setting the useBackup field will be optional.
If you have an MFA phone number set, replacing your phone number is available only with the BILL web app (Settings > Security > Change Primary 2-Step Verification).
In the Spend & Expense transactions API, we have added updatedTime and authorizedTime to the list of transaction filters. In the Get list of transactions (GET /v3/spend/transactions) request, you can now filter transactions with the updatedTime (transaction updated date and time) and authorizedTime (transaction authorized date and time) fields.
New fields you can filter with
Available operators
updatedTime
lte (Less than or equal) gte (Greater than or equal)
authorizedTime
lte (Less than or equal) gte (Greater than or equal)
In addition, we have introduced the parentBudgetUuid field in the transactions API response. In all the transactions API responses, you can now get the BILL-generated UUID of the parent budget linked with each transaction.
We have introduced a new API endpoint for getting a list of login organizations.
You can now get a list of organizations that are accessible with your current API session. In the response, you get a list of organizations and console organizations. When a console organization is available in the response, this indicates that the console organization is a parent of the listed organization.
In the payments API, we have introduced a new exchangeRateBatchId field. BILL maintains all exchangeRate values in a batch. When a batch expires, a new batch ID is generated and all exchangeRate values are updated in the new batch.
In the Create a payment (POST /v3/payments) and Create a bulk payment (POST /v3/payments/bulk) API request, you can now set this required field for paying international vendors.
Get the current BILL exchange rate and exchange rate batch ID with GET /v3/payments/exchange-rate or POST /v3/payments/exchange-rate (for multiple international vendors).
We have introduced a new API endpoint for getting BILL exchange rates for multiple vendors.
You can now get the current BILL exchange rate and exchange rate batch ID for multiple international vendors with one API request. The exchange rate batch ID is required for creating a bulk payment with POST /v3/payments/bulk.
The BILL exchange rate changes periodically. Use this endpoint to get the current exchange rate based on the payment amount and vendor bill currency.
We have added a new developer tutorial video - BILL v3 API webhooks explained - in the BILL API Platform for developers YouTube playlist. In this video, we learn how to use the BILL v3 Webhooks API to build faster, smarter, and more efficient integrations. See the BILL API Platform for developers playlist for the complete set of developer tutorial videos.
BILL v3 API webhooks explained
In this tutorial, we learn how to use the BILL v3 Webhooks API to build faster, smarter, and more efficient integrations.
