Number verification API

Starting 2-Step Verification Session

Starting Verification - API endpoints

Main API endpoint https://api2.messente.com/verify/start/
Backup API endpoint https://api3.messente.com/verify/start/

Request parameters

Key Value
username API account user name from the Messente's web page
password API account security key (API key) from the Messente's web page
to Receiver's phone number with the country code
template Optional template of the message, including PIN code. Placeholder for PIN code is <PIN>.
When not set, default template is used: "Your Verification PIN code is <PIN>"
pin_length Length of the PIN code. Minumum 4 digits, maximum 16. Defaults to 4.
from Optional parameter that sets the Sender name.
When not set, the default Sender name "Verify" is used. This sender ID also needs to be added to your account beforehand.
max_tries Optional. Maximum number of times the PIN code is sent in total.
Defaults to "2" - initial PIN code and one retry.
It is discouraged to set this value to "1" as only the initial PIN code is sent and retry is disabled.
retry_delay Optional. For how long (in seconds) to wait for next retry, if the correct PIN code has not been entered yet? Defaults to 30 seconds.
validity Optional. For how long (in seconds) is the PIN code valid. Defaults to 5 minutes (300 seconds). Maximum 30 minutes (1800 seconds).
ip Optional. IP address of the client making verification request
browser Optional. User Agent of the browser. For example "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36"
cookie Optional. Unique cookie assigned to this session. If a user tries logging in with the same cookie present, user is automatically logged in and no PIN code verification is needed.

Response from verification session request

Basic syntax for the successful response:

OK [VerificationID]

When the request was unsuccessful or verification is not needed, the HTTP response includes one of the response codes instead:

Response codes

Code Meaning
VERIFIED User is logging in from already verified computer, no PIN code verification is required.
ERROR 101 Access is restricted, wrong credentials. Check the username and password values.
ERROR 102 Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103 Invalid IP address. The IP address you made the request from, is not in the API settings whitelist.
ERROR 111 Sender parameter "from" is invalid. You have not activated this sender name from Messente.com
ERROR 109 PIN code field is missing in the template value.
FAILED 209 Server failure, try again after a few seconds or try the api3.messente.com backup server.

Examples

from messente.api.sms import Messente


api = messente.Messente(
    username="api_user",
    password="api_password"
)

response = api.number_verification.send_pin(dict(
    to=to,
    max_tries=1,
    retry_delay=30,  # seconds
    validity=(5 * 60),  # seconds
    template="Example: your pin code is: "
))

if response.is_ok():
    print("Verification ID:", response.get_verification_id())
else:
    print(response.get_full_error_msg())

Verifying PIN code

Verifying PIN code - API endpoints

Main API endpoint https://api2.messente.com/verify/pin/
Backup API endpoint https://api3.messente.com/verify/pin/

Request parameters

Key Value
username API account user name from the Messente's web page
password API account security key (API key) from the Messente's web page
verification_id Verification ID returned by the successful verification request
pin PIN code entered by the user.
ip Optional. IP address of the client making verification request. If the IP address is from another country, PIN is required even if the cookies match.
browser Optional. User Agent of the browser. For example "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36"
cookie Optional. Unique cookie assigned to this session. If a user tries logging in with the same cookie present, user is automatically logged in and no PIN code verification is needed.

Response from PIN code verification request

Response of successful response (PIN code was correct):

VERIFIED

Failed request response codes

Code Meaning
INVALID The PIN code does not match the PIN code sent.
EXPIRED The PIN code has expired. Please request for new PIN code.
THROTTLED Too many verification calls made for this Verification Session. User is possibly trying to guess the password.
ERROR 101 Access is restricted, wrong credentials. Check the username and password values.
ERROR 102 Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103 Invalid IP address. The IP address you made the request from, is not in the API settings whitelist.
ERROR 110 Verification Session with following ID was not found.
FAILED 209 Server failure, try again after a few seconds or try the api3.messente.com backup server.

Examples

from messente.api.sms import Messente


api = messente.Messente(
    username="api_user",
    password="api_password"
)

verification_id = "xxxxxxxxxxx"
pin = "xxxx"

response = api.number_verification.verify_pin(dict(
    pin=pin,
    verification_id=verification_id
)
if response.is_ok() and response.is_verified():
    print("PIN code verified")
else:
    # you can use specific helper methods
    print("EXPIRED?", response.is_expired())
    print("THROTTLED?", response.is_throttled())
    print("INVALID?", response.is_invalid())