Messente avatar logo

Number verification API

Starting 2-Step Verification Session

Starting Verification - API endpoints
Main API endpointhttps://api2.messente.com/verify/start/
Backup API endpointhttps://api3.messente.com/verify/start/
Request parameters
KeyValue
usernameAPI account user name from the Messente's web page
passwordAPI account security key (API key) from the Messente's web page
toReceiver's phone number with the country code
templateOptional 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_lengthLength of the PIN code. Minumum 4 digits, maximum 16. Defaults to 4.
fromOptional 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_triesOptional. 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_delayOptional. For how long (in seconds) to wait for next retry, if the correct PIN code has not been entered yet? Defaults to 30 seconds.
validityOptional. For how long (in seconds) is the PIN code valid. Defaults to 5 minutes (300 seconds). Maximum 30 minutes (1800 seconds).
ipOptional. IP address of the client making verification request
browserOptional. 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"
cookieOptional. 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
CodeMeaning
VERIFIEDUser is logging in from already verified computer, no PIN code verification is required.
ERROR 101Access is restricted, wrong credentials. Check the username and password values.
ERROR 102Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103Invalid IP address. The IP address you made the request from, is not in the API settings whitelist.
ERROR 111Sender 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 209Server failure, try again after a few seconds or try the api3.messente.com backup server.

Examples

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 endpointhttps://api2.messente.com/verify/pin/
Backup API endpointhttps://api3.messente.com/verify/pin/
Request parameters
KeyValue
usernameAPI account user name from the Messente's web page
passwordAPI account security key (API key) from the Messente's web page
verification_idVerification ID returned by the successful verification request
pinPIN code entered by the user.
ipOptional. IP address of the client making verification request. If the IP address is from another country, PIN is required even if the cookies match.
browserOptional. 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"
cookieOptional. 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
CodeMeaning
INVALIDThe PIN code does not match the PIN code sent.
EXPIREDThe PIN code has expired. Please request for new PIN code.
THROTTLEDToo many verification calls made for this Verification Session. User is possibly trying to guess the password.
ERROR 101Access is restricted, wrong credentials. Check the username and password values.
ERROR 102Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103Invalid IP address. The IP address you made the request from, is not in the API settings whitelist.
ERROR 110Verification Session with following ID was not found.
FAILED 209Server failure, try again after a few seconds or try the api3.messente.com backup server.

Examples

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