Release Notes
System Status
Start typing to search…
Back to All
Removed

UPCOMING API CHANGES | Use primary MFA phone number

February 6th, 2026

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).