v1

latestOpenAPI 3.0.12026-07-24310590875.6 KB
mfa

Add phone for MFA setup

Add a valid phone number for setting up MFA in the current organization.

In the response, a setupId is generated and a six-digit token is sent to the phone number. After you add a phone number (with POST /v3/mfa/setup), complete the MFA setup by validating the entered phone number (with POST /v3/mfa/validate). At this point, the phone number is registered for the MFA sign in operation.

There are two stages in the BILL MFA process.

  1. MFA setup: Add a valid phone number for setting up MFA in the organization (with POST /v3/mfa/setup), and then complete the setup by validating the entered phone number (with POST /v3/mfa/validate). At this point, the phone number is registered for the MFA sign in operation.
  2. MFA sign in: Generate an MFA challenge (with POST /v3/mfa/challenge), and then complete MFA sign in by validating the MFA challenge (with POST /v3/mfa/challenge/validate). At this point, your API session is MFA trusted.

Note: In the production environment, BILL requires an MFA-trusted API session for a set of API operations.

  • Enable vendor autoPay
  • Enable recurring bill autoPayment
  • Create a payment or bulk payment
  • Create a bank account in a BILL organization
  • Reset MFA (Complete MFA setup and MFA sign-in again)
post/v3/mfa/setup

Headers

sessionIdstring nullable

API session ID generated with /v3/login

Example:{{session_id}}
devKeystring nullable

Developer key generated with your BILL developer account

Example:{{developer_key}}

Request body

phonestring required

Phone number for MFA setup. The validation token is sent to this number.

type'VOICE' | 'TEXT' required

Phone type for MFA setup.

  • TEXT: You receive the validation token as an SMS test message.
  • VOICE: You receive the validation token by an automated phone call
primaryboolean

Set as true to mark the phone number as the primary mobile device. The default value is true.

Example request

{
  "phone": "{{user_phone_no}}",
  "type": "TEXT",
  "primary": true
}

Response

Add phone for MFA setup response

setupIdstring required

MFA setup ID. This value is required for completing your MFA setup validation with POST /v3/mfa/setup/validate.