The 2FA API is available exclusively for Flex Pro users.
How Wavix 2FA works
In order to use the Wavix 2FA API, you must create a Wavix 2FA Service. Each 2FA Service has the following parameters:- The length of one-time passwords
- Active delivery channels: voice, SMS, or both
- Automatic failover which can be enabled or disabled
- End user’s phone number validation can be enabled or disabled
When sending the OTP via voice, Wavix initiates an automated phone call to the end user’s number. The end user must pick up the call to receive the OTP. Once the call is answered, the Wavix robot reads a message with the OTP in English.
- An end user registers at or accesses your website or application and enters his or her phone number.
- Your backend system initiates a call to the Wavix 2FA API to create a new 2FA Verification. You must specify the phone number to which the verification code will be sent and whether the code needs to be sent via a voice call or an SMS.
- Once the 2FA Verification is created, the Wavix platform performs the following actions:
- Generates a unique one-time password and sends it to the end user’s phone number via the specified channel.
- Generates a unique 2FA Verification ID and sends it back in the response.
- The end user enters the received code on your website or app.
- To verify it, your backend system triggers another call to the Wavix 2FA API and passes the code along with the 2FA Verification ID.
- The Wavix platform checks whether the code matches the latest OTP sent to the end user’s phone number and sends back the verification results (success or failure).
- In cases when the verification is successful, your backend system authorizes registration or access to the website or application.
- In cases when the verification fails, your backend system should check the active 2FA Verification status using this API:
- If the status is either
expired
orfailed
, any further attempts to validate OTPs will result in an error. You must create a new 2FA Verification to send a new code. See point #2. - Otherwise, request the end user to re-enter the code. You can also give him or her an option to request a new code using the same or a different communication channel.
- If the status is either
Prerequisites
Before creating a Wavix 2FA Service and sending and verifying OTPs, you need to sign up for Wavix.Create a Wavix account
- Sign up for a Wavix account using your business email address.
- Confirm your email address and phone number during the sign-up process.
- Wait for your account to be approved by the Wavix team.
- After approval, choose either the Wavix Flex or Flex Pro account level.
Find your API key
Wavix uses API keys to authenticate requests. To find API keys associated with your account:- Sign in to your Wavix account.
- Go to Administration → API Keys.
- Copy the API key you want to use, or create a new one by clicking Create new.
How to create a 2FA service
Follow the below steps to create a Wavix 2FA Service:- Sign in to your Wavix account.
- Go to Solutions → 2FA.
- Select Create new to create a new 2FA Service:
- Enter the Service name and choose the code length. Minimum code length is 4 digits, maximum is 10. The default value is 6 digits.
- Choose if you’d like to allow automatic phone number validation and channel failover. Wavix recommends allowing both options to improve code deliverability.
- Choose the delivery channels you’re planning to use, by enabling SMS, Voice, or both.
- In order to use SMS as a delivery channel, select a Sender ID provisioned for the countries where you plan to send messages.
- In cases when you plan to use voice calls, you must select a Caller ID.
- Select Next and then Save and close to complete the 2FA configuration.
If you want to fallback to voice calls when SMS delivery fails, you must enable Channel failover and select Voice as a delivery channel.

2FA Service ID is required for sending and verifying OTPs via the 2FA API. You can copy Service ID when creating a new 2FA Service or you can find it later in the list of 2FA Services on your account.
Wavix 2FA Service restrictions
The following limitations apply:- Each verification code is valid only for 5 minutes after being sent. Any attempt to validate the code after this 5-minute window will fail.
- After sending a verification code, you have a maximum of 5 attempts to validate it. In cases when you exceed this limit, 2FA Verification would fail. Additional attempts to validate the code or resend a new one within a failed 2FA Verification would not be permitted.
- Regardless of the communication channel used, you can send a maximum of 5 codes within a single 2FA Verification. Any attempt to send a 6th OTP will result in the ‘failed’ 2FA Verification status.
Step-by-step instructions
How to send a verification code
To send a verification code, you must create a 2FA Verification using the method below. Once the 2FA Verification is created, Wavix automatically generates and sends an OTP to the specified phone number.service_id
- unique identifier of the Wavix 2FA Serviceto
- the end user’s phone number to which the verification code will be sentchannel
- usesms
to send the verification code via SMS orvoice
to trigger a voice call with the code
HTTP 200 OK
. The response contains the created 2FA Verification details.
success
- indicates whether 2FA Verification was successfully createdservice_id
- unique identifier of the Wavix 2FA Servicedestination
- the end user’s phone numbersession_url
- automatically generated 2FA Verification URL. You can use the URL to validate the OTP and, optionally, to resend the verification code.session_id
- unique identifier of the Wavix 2FA Verificationcreated_at
- date and time the 2FA Verification was creatednumber_lookup
- extended information about the destination phone number:number_type
- the destination phone number typecountry
- the destination phone number’s 2-letter ISO country codecurrent_carrier
- the carrier network the phone number currently belongs to
The
number_lookup
details are only returned if the Number validation option is activated for the 2FA Service.uuid
- Wavix 2FA Verification ID
channel
- usesms
to resend the verification code via SMS orvoice
to trigger a voice call with a new code
HTTP 200 OK
. The response indicates whether the code was successfully sent, the date and time the code was sent, and the communication channel used.
success
- indicates whether the OTP successfully sentchannel
- containssms
in cases when the code was sent via an SMS orvoice
when a voice call with the code was placeddestination
- the end user’s phone numbercreated_at
- date and time the code was sent
How to validate an OTP
In order to validate an OTP entered by an end user, use the method belowuuid
- Wavix 2FA Verification ID
code
- the code entered by the end user
HTTP 200 OK
. The response contains the validation results.
is_valid
- indicates whether the verification code was successfully validated
How to cancel a 2FA Verification
You can explicitly cancel the 2FA Verification. Once the verification is canceled, no further codes would be sent and you wouldn’t be able to validate any of the codes sent previously. To send a new code you’d need to create a new Verification. In order to cancel the 2FA Verification use the method belowuuid
- Wavix 2FA Verification ID
How to query 2FA service logs
The Wavix 2FA API allows customers to retrieve a list of active 2FA Verifications and events associated with each 2FA Verification. To get a list of active 2FA Verifications, use the method belowservice_id
- unique identifier of the Wavix 2FA Servicefrom
- start date of the search time range in theyyyy-mm-dd
formatto
- end date of the search time range in theyyyy-mm-dd
format
- created_at - date and time the Wavix 2FA Verification was created
- session_id - unique identifier of the Wavix 2FA Verification
- phone_number - an end user’s phone number
- destination_country - 2-letter ISO code of a country the destination phone number belongs to
- status - 2FA Verification status. Can be one of the below:
verified
- indicates the sent code was successfully verifiedexpired
- indicates the 2FA Verification expiredcanceled
- indicates the 2FA Verification was explicitly canceledfailed
- indicates that all validation attempts were unsuccessful
- charge - total charge for the 2FA Verification, in USD
- service_id - unique identifier of the Wavix 2FA Services the Verification is associated with
- service_name - the Wavix 2FA Service name
session_uuid
- Wavix 2FA Verification ID
HTTP 200 OK
. The response contains a list of events associated with the 2FA Verification
created_at
- date and time of the eventevent
- human readable event description. Can contain one of the below values:Number lookup
- indicates that the Wavix platform checked if the destination phone number was valid. You’d only see the event when the Number validation option was activated for your 2FA ServiceCode sent via SMS
- indicates the OTP was sent using SMS as a communication channelCode sent via voice
- indicates the OTP was sent using voice as a communication channelVerification
- indicates the OTP verification attempt
status
- status of the event. It can be any of the following:delivered
,success
,failed
, orpending
.charge
- the cost of an action associated with the event, in USDerror
- error description, if any