def status(self, ref_id, verify_code=None):
"""
Retrieves the verification result. You make this call in your web application after users complete the authentication transaction (using either a call or sms).
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `ref_id`
- The Reference ID returned in the response from the TeleSign server, after you called either **call** or **sms**.
* - `verify_code`
- The verification code received from the user.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
phone_info = verify.sms(phone_number) # Send a text message that contains an auto-generated validation code, to the user.
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/verify/%s" % ref_id
method = "GET"
headers = generate_auth_headers(self._customer_id, self._secret_key,
resource, method)
fields = None
if (verify_code != None):
fields = {"verify_code": verify_code}
req = requests.get(url="{}{}".format(self._url, resource),
params=fields,
headers=headers,
proxies=self._proxy)
return Response(self._validate_response(req), req)
def status(self, ref_id, verify_code=None):
"""
Retrieves the verification result. You make this call in your web application after users complete the authentication transaction (using either a call or sms).
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `ref_id`
- The Reference ID returned in the response from the TeleSign server, after you called either **call** or **sms**.
* - `verify_code`
- The verification code received from the user.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
phone_info = verify.sms(phone_number) # Send a text message that contains an auto-generated validation code, to the user.
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/verify/%s" % ref_id
method = "GET"
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method)
fields = None
if(verify_code != None):
fields = {"verify_code": verify_code}
req = requests.get(url="{}{}".format(self._url, resource), params=fields, headers=headers, proxies=self._proxy)
return Response(self._validate_response(req), req)
def standard(self, phone_number):
"""
Retrieves the standard set of details about the specified phone number. This includes the type of phone (e.g., land line or mobile), and it's approximate geographic location.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
phone_info = phoneid.standard(phone_number)
except AuthorizationError as ex:
# API authorization failed. Check the API response for details.
...
except TelesignError as ex:
# Failed to completely execute the PhoneID service. Check the API response
# for details. Data returned might be incomplete or invalid.
...
"""
resource = "/v1/phoneid/standard/%s" % phone_number
method = "GET"
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method)
req = requests.get(url="{}{}".format(self._url, resource), headers=headers, proxies=self._proxy)
return Response(self._validate_response(req), req)
def contact(self, phone_number, use_case_code):
"""
In addition to the information retrieved by **standard**, this service provides the Name & Address associated with the specified phone number.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `use_case_code`
- A four letter code used to specify a particular usage scenario for the web service.
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
phone_number = "13107409700"
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
phone_info = phoneid.contact(phone_number) # The use-case code is optional.
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to completely execute the PhoneID service, check the API response
# for details; data returned may be incomplete or not be valid
...
"""
resource = "/v1/phoneid/contact/%s" % phone_number
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
"GET")
req = self._pool.request('GET', resource, headers=headers, fields={'ucid':use_case_code})
return Response(self._validate_response(req), req)
def standard(self, phone_number):
"""
Retrieves the standard set of details about the specified phone number. This includes the type of phone (e.g., land line or mobile), and it's approximate geographic location.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
phone_info = phoneid.standard(phone_number)
except AuthorizationError as ex:
# API authorization failed. Check the API response for details.
...
except TelesignError as ex:
# Failed to completely execute the PhoneID service. Check the API response
# for details. Data returned might be incomplete or invalid.
...
"""
resource = "/v1/phoneid/standard/%s" % phone_number
method = "GET"
headers = generate_auth_headers(self._customer_id, self._secret_key,
resource, method)
req = requests.get(url="{}{}".format(self._url, resource),
headers=headers,
proxies=self._proxy)
return Response(self._validate_response(req), req)
def call(self, phone_number, verify_code=None, language="en"):
"""
Calls the specified phone number, and using speech synthesis, speaks the verification code to the user.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `verify_code`
- (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
* - `language`
- (optional) The written language used in the message. The default is English.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
try:
phone_info = verify.call(phone_number)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
if(verify_code == None):
verify_code = random_with_N_digits(5)
resource = "/v1/verify/call"
method = "POST"
fields = {
"phone_number": phone_number,
"language": language,
"verify_code": verify_code}
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
req = requests.post(url="{}{}".format(self._url, resource), data=fields, headers=headers, proxies=self._proxy)
return Response(self._validate_response(req), req, verify_code=verify_code)
def live(self, phone_number, use_case_code):
"""
In addition to the information retrieved by **standard**, this service provides actionable data associated with the specified phone number.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `use_case_code`
- A four letter code used to specify a particular usage scenario for the web service.
.. rubric:: Use-case Codes
The following table list the available use-case codes, and includes a description of each.
======== =====================================
Code Description
======== =====================================
**BACS** Prevent bulk account creation + spam.
**BACF** Prevent bulk account creation + fraud.
**CHBK** Prevent chargebacks.
**ATCK** Prevent account takeover/compromise.
**LEAD** Prevent false lead entry.
**RESV** Prevent fake/missed reservations.
**PWRT** Password reset.
**THEF** Prevent identity theft.
**TELF** Prevent telecom fraud.
**RXPF** Prevent prescription fraud.
**OTHR** Other.
**UNKN** Unknown/prefer not to say.
======== =====================================
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
use_case_code = "RXPF"
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
phone_info = phoneid.live(phone_number, use_case_code)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to completely execute the PhoneID service, check the API response
# for details; data returned may be incomplete or not be valid
...
"""
resource = "/v1/phoneid/live/%s" % phone_number
method = "GET"
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method)
req = requests.get(url="{}{}".format(self._url, resource), params={'ucid': use_case_code}, headers=headers, proxies=self._proxy)
return Response(self._validate_response(req), req)
def call(self, phone_number, verify_code=None, language="en"):
"""
Calls the specified phone number, and using speech synthesis, speaks the verification code to the user.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `verify_code`
- (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
* - `language`
- (optional) The written language used in the message. The default is English.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
try:
phone_info = verify.call(phone_number)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
if(verify_code == None):
verify_code = random_with_N_digits(5)
resource = "/v1/verify/call"
method = "POST"
fields = {
"phone_number": phone_number,
"language": language,
"verify_code": verify_code}
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
req = self._pool.request_encode_body(method, resource, headers=headers, fields=fields, encode_multipart=False)
return Response(self._validate_response(req), req, verify_code=verify_code)
def two_way_sms(self, phone_number, ucid, message="", validity_period=""):
"""
The TeleSign Verify Soft Token web service is a server-side component of the TeleSign AuthID application, and it allows you to authenticate your end users when they use the TeleSign AuthID application on their mobile device to generate a Time-based One-time Password (TOTP) verification code
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `ucid`
- A string specifying one of the Use Case Codes
* - `message`
- (optional) The text to display in the body of the text message. You must include the $$CODE$$ placeholder for the verification code somewhere in your message text. TeleSign automatically replaces it with a randomly-generated verification code
* - `validity_period`
- (optional) This parameter allows you to place a time-limit on the verification. This provides an extra level of security by restricting the amount of time your end user has to respond (after which, TeleSign automatically rejects their response). Values are expressed as a natural number followed by a lower-case letter that represents the unit of measure. You can use 's' for seconds, 'm' for minutes, 'h' for hours, and 'd' for days
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
try:
phone_info = verify.two_way_sms(phone_number, "BACS")
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/verify/two_way_sms"
method = "POST"
fields = {
"phone_number": phone_number,
"ucid": ucid,
"message": message,
"validity_period": validity_period
}
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
req = self._pool_mobile.request_encode_body(method, resource, headers=headers, fields=fields, encode_multipart=False)
return Response(self._validate_response(req), req)
def soft_token(self, phone_number, soft_token_id="", verify_code=None):
"""
The TeleSign Verify Soft Token web service is a server-side component of the TeleSign AuthID application, and it allows you to authenticate your end users when they use the TeleSign AuthID application on their mobile device to generate a Time-based One-time Password (TOTP) verification code
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `soft_token_id`
- (optional) The alphanumeric string that uniquely identifies your TeleSign soft token subscription
* - `verify_code`
- (optional) The verification code received from the end user
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
try:
phone_info = verify.soft_token(phone_number)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
if(verify_code == None):
verify_code = random_with_N_digits(5)
resource = "/v1/verify/soft_token"
method = "POST"
fields = {
"phone_number": phone_number,
"verify_code": verify_code,
"soft_token_id": soft_token_id
}
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
req = self._pool_mobile.request_encode_body(method, resource, headers=headers, fields=fields, encode_multipart=False)
return Response(self._validate_response(req), req)
def push(self, phone_number, notification_type="", notification_value="", template="", message=""):
"""
The TeleSign Verify Push web service is a server-side component of the TeleSign AuthID application, and it allows you to provide on-device transaction authorization for your users. It works by delivering authorization requests to your users via Push Notification, and then by receiving their permission responses via their mobile device's wireless Internet connection. The service provides two levels of security to support two types of transactions.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `notification_type`
- (optional) Indicates the security measure to use for transaction authorization. The following types are currently supported: CODE, SIMPLE
* - `notification_value`
- (optional) Applies when notification_type=CODE. The verification code used for the code challenge. This is a randomly generated numeric value that you display in your web page for your user. After reading this value, the user then types it into the AuthID application on their mobile device
* - `template`
- (optional) Specifies a custom banner and icon for the TeleSign AuthID application to use for this notification. This allows you to brand your notifications with your corporate logo and/or your service-specific branding.
* - `message`
- (optional) The message to display to the end user, in the body of the notification. You normally leave this parameter empty (or set to null), and the default message is displayed.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
try:
phone_info = verify.push(phone_number, "", "", "Outlook-2FA", "Test Message")
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/verify/push"
method = "POST"
fields = {
"phone_number": phone_number,
"notification_type": notification_type,
"notification_value": notification_value,
"template": template,
"message": message
}
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
req = self._pool_mobile.request_encode_body(method, resource, headers=headers, fields=fields, encode_multipart=False)
return Response(self._validate_response(req), req)
def call(self,
phone_number,
verify_code=None,
use_case_code=None,
verify_method="",
language="en",
extension_type="",
redial="",
originating_ip=None,
pressx=None,
extra=None,
timeout=None):
"""
Calls the specified phone number, and using speech synthesis, speaks the verification code to the user.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `verify_code`
- (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
* - `language`
- (optional) The written language used in the message. The default is English.
* - `verify_method`
- (optional)
* - `extension_type`
- (optional)
* - `redial`
- (optional)
* - `use_case_code`
- (optional, recommended) A four letter code (use case code) used to specify a particular usage scenario for the web service.
* - `originating_ip`
- (optional) An IP (v4 or v6) address, possibly detected by the customer's website, that is considered related to the user verification request
* - `timeout`
- (optional) Timeout for the request (see timeout in the requests documentation). Will override any timeout set in the initialization. Note that this is not a timeout for the actual phone call, just for the http request.
* - `extra`
- (optional) Key value mapping of additional parameters.
.. rubric:: Use-case Codes
The following table list the available use-case codes, and includes a description of each.
======== =====================================
Code Description
======== =====================================
**BACS** Prevent bulk account creation + spam.
**BACF** Prevent bulk account creation + fraud.
**CHBK** Prevent chargebacks.
**ATCK** Prevent account takeover/compromise.
**LEAD** Prevent false lead entry.
**RESV** Prevent fake/missed reservations.
**PWRT** Password reset.
**THEF** Prevent identity theft.
**TELF** Prevent telecom fraud.
**RXPF** Prevent prescription fraud.
**OTHR** Other.
**UNKN** Unknown/prefer not to say.
======== =====================================
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
phone_number = "13107409700"
try:
phone_info = verify.call(phone_number, use_case_code="ATCK")
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/verify/call"
method = "POST"
fields = {
"phone_number": phone_number,
"language": language,
"verify_method": verify_method,
"extension_type": extension_type,
"redial": redial,
}
if verify_code:
fields['verify_code'] = verify_code
if pressx:
fields['pressx'] = pressx
if use_case_code:
fields['ucid'] = use_case_code
if originating_ip is not None:
fields['originating_ip'] = originating_ip
if extra is not None:
fields.update(extra)
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
headers['User-Agent'] = self._user_agent
req = requests.post(url="{}{}".format(self._url, resource),
data=fields,
headers=headers,
proxies=self._proxy,
timeout=timeout or self._timeout)
return Response(self._validate_response(req), req, verify_code=verify_code)
def score(self, phone_number, use_case_code):
"""
Retrieves a score for the specified phone number. This ranks the phone number's "risk level" on a scale from 0 to 1000, so you can code your web application to handle particular use cases (e.g., to stop things like chargebacks, identity theft, fraud, and spam).
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `use_case_code`
- A four letter code used to specify a particular usage scenario for the web service.
.. rubric:: Use-case Codes
The following table list the available use-case codes, and includes a description of each.
======== =====================================
Code Description
======== =====================================
**BACS** Prevent bulk account creation + spam.
**BACF** Prevent bulk account creation + fraud.
**CHBK** Prevent chargebacks.
**ATCK** Prevent account takeover/compromise.
**LEAD** Prevent false lead entry.
**RESV** Prevent fake/missed reservations.
**PWRT** Password reset.
**THEF** Prevent identity theft.
**TELF** Prevent telecom fraud.
**RXPF** Prevent prescription fraud.
**OTHR** Other.
**UNKN** Unknown/prefer not to say.
======== =====================================
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
use_case_code = "ATCK"
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
score_info = phoneid.score(phone_number, use_case_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/phoneid/score/%s" % phone_number
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
"GET")
req = self._pool.request('GET', resource, headers=headers, fields={'ucid': use_case_code})
return Response(self._validate_response(req), req)
def sms(self, phone_number, verify_code=None, language="en", template=""):
"""
Sends a text message containing the verification code, to the specified phone number (supported for mobile phones only).
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `verify_code`
- (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
* - `language`
- (optional) The written language used in the message. The default is English.
* - `template`
- (optional) A standard form for the text message. It must contain the token ``$$CODE$$``, which TeleSign auto-populates with the verification code.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
phone_number = "13107409700"
try:
phone_info = verify.sms(phone_number)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
if(verify_code == None):
verify_code = random_with_N_digits(5)
resource = "/v1/verify/sms"
method = "POST"
fields = {
"phone_number":phone_number,
"language":language,
"verify_code":verify_code,
"template":template}
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
req = self._pool.request_encode_body(method, resource, headers=headers, fields=fields, encode_multipart=False)
return Response(self._validate_response(req), req, verify_code=verify_code)
def push(self,
phone_number,
use_case_code,
timeout=None,
extra={}):
"""
The **push** method sends a push notification containing the verification code to the specified phone number (supported for mobile phones only).
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `notification_type`
- The notification type to sent to the user. It could have the following valid values: SIMPLE | CODE | GESTURE | QR
* - `notification_value`
- The notification value is sent to the user. This is a value ranging between 6-8 digits long. Default length 6.
* - `template`
- (optional) A standard form for the text message. It must contain the token ``$$CODE$$``, which TeleSign auto-populates with the verification code.
* - `message`
- (optional) Text message that the application displays when asking for the notification details information.
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
phone_number = "13107409700"
try:
phone_info = verify.sms(phone_number)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v2/verify/push"
method = "POST"
fields = {
"phone_number": phone_number,
"ucid": use_case_code
}
fields.update(extra)
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
headers['User-Agent'] = self._user_agent
req = requests.post(url="{}{}".format(self._url, resource),
headers=headers,
data=fields,
timeout=timeout or self._timeout,
proxies=self._proxy)
return Response(self._validate_response(req), req)
def smart(self,
phone_number,
use_case_code,
verify_code=None,
language="en",
preference=None,
ignore_risk=False,
timeout=None,
extra=None):
"""
Calls the specified phone number, and using speech synthesis, speaks the verification code to the user.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number to receive the text message. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `verify_code`
- (optional) The verification code to send to the user. If omitted, TeleSign will automatically generate a random value for you.
* - `language`
- (optional) The written language used in the message. The default is English.
* - `use_case_code`
- A four letter code (use case code) used to specify a particular usage scenario for the web service.
* - `preference`
- (optional) Customer preference for delivery method. One of 'call', 'sms', 'push'. This may override TeleSign's determination of the method to use when possible (for instance, it is not possible to send an sms to all phones).
* - `ignore_risk`
- (optional) If true, TeleSign will ignore the evaluated risk for the phone and attempt delivery in all cases.
* - `extra`
- (optional) Key value mapping of additional parameters.
.. rubric:: Use-case Codes
The following table list the available use-case codes, and includes a description of each.
======== =====================================
Code Description
======== =====================================
**BACS** Prevent bulk account creation + spam.
**BACF** Prevent bulk account creation + fraud.
**CHBK** Prevent chargebacks.
**ATCK** Prevent account takeover/compromise.
**LEAD** Prevent false lead entry.
**RESV** Prevent fake/missed reservations.
**PWRT** Password reset.
**THEF** Prevent identity theft.
**TELF** Prevent telecom fraud.
**RXPF** Prevent prescription fraud.
**OTHR** Other.
**UNKN** Unknown/prefer not to say.
======== =====================================
**Example**::
from telesign.api import Verify
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
verify = Verify(cust_id, secret_key) # Instantiate a Verify object.
phone_number = "13107409700"
try:
phone_info = verify.call(phone_number, use_case_code="ATCK")
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to execute the Verify service, check the API response for details
...
# When the user inputs the validation code, you can verify that it matches the one that you sent.
if (phone_info != None):
try:
status_info = verify.status(phone_info.data["reference_id"], verify_code=phone_info.verify_code)
except AuthorizationError as ex:
...
except TelesignError as ex:
...
"""
resource = "/v1/verify/smart"
method = "POST"
fields = {
"phone_number": phone_number,
"language": language,
'ucid': use_case_code,
}
if preference:
fields['preference'] = preference
if ignore_risk:
fields['ignore_risk'] = ignore_risk
if extra is not None:
fields.update(extra)
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method,
fields=fields)
headers['User-Agent'] = self._user_agent
req = requests.post(url="{}{}".format(self._url, resource),
data=fields,
headers=headers,
timeout=timeout or self._timeout,
proxies=self._proxy)
return Response(self._validate_response(req), req, verify_code=verify_code)
def live(self, phone_number, use_case_code):
"""
In addition to the information retrieved by **standard**, this service provides actionable data associated with the specified phone number.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `use_case_code`
- A four letter code used to specify a particular usage scenario for the web service.
.. rubric:: Use-case Codes
The following table list the available use-case codes, and includes a description of each.
======== =====================================
Code Description
======== =====================================
**BACS** Prevent bulk account creation + spam.
**BACF** Prevent bulk account creation + fraud.
**CHBK** Prevent chargebacks.
**ATCK** Prevent account takeover/compromise.
**LEAD** Prevent false lead entry.
**RESV** Prevent fake/missed reservations.
**PWRT** Password reset.
**THEF** Prevent identity theft.
**TELF** Prevent telecom fraud.
**RXPF** Prevent prescription fraud.
**OTHR** Other.
**UNKN** Unknown/prefer not to say.
======== =====================================
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
use_case_code = "RXPF"
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
phone_info = phoneid.live(phone_number, use_case_code)
except AuthorizationError as ex:
# API authorization failed, the API response should tell you the reason
...
except TelesignError as ex:
# failed to completely execute the PhoneID service, check the API response
# for details; data returned may be incomplete or not be valid
...
"""
resource = "/v1/phoneid/live/%s" % phone_number
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
"GET")
req = self._pool.request('GET', resource, headers=headers, fields={'ucid': use_case_code})
return Response(self._validate_response(req), req)
def standard(self, phone_number, use_case_code=None, extra=None, timeout=None):
"""
Retrieves the standard set of details about the specified phone number. This includes the type of phone (e.g., land line or mobile), and it's approximate geographic location.
.. list-table::
:widths: 5 30
:header-rows: 1
* - Parameters
-
* - `phone_number`
- The phone number you want details about. You must specify the phone number in its entirety. That is, it must begin with the country code, followed by the area code, and then by the local number. For example, you would specify the phone number (310) 555-1212 as 13105551212.
* - `use_case_code`
- (optional, recommended) A four letter code (use case code) used to specify a particular usage scenario for the web service.
* - `timeout`
- (optional) Timeout for the request (see timeout in the requests documentation). Will override any timeout set in the initialization.
* - `extra`
- (optional) Key value mapping of additional parameters.
.. rubric:: Use-case Codes
The following table list the available use-case codes, and includes a description of each.
======== =====================================
Code Description
======== =====================================
**BACS** Prevent bulk account creation + spam.
**BACF** Prevent bulk account creation + fraud.
**CHBK** Prevent chargebacks.
**ATCK** Prevent account takeover/compromise.
**LEAD** Prevent false lead entry.
**RESV** Prevent fake/missed reservations.
**PWRT** Password reset.
**THEF** Prevent identity theft.
**TELF** Prevent telecom fraud.
**RXPF** Prevent prescription fraud.
**OTHR** Other.
**UNKN** Unknown/prefer not to say.
======== =====================================
**Example**::
from telesign.api import PhoneId
from telesign.exceptions import AuthorizationError, TelesignError
cust_id = "FFFFFFFF-EEEE-DDDD-1234-AB1234567890"
secret_key = "EXAMPLE----TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw=="
phone_number = "13107409700"
phoneid = PhoneId(cust_id, secret_key) # Instantiate a PhoneId object.
try:
phone_info = phoneid.standard(phone_number, use_case_code="ATCK")
except AuthorizationError as ex:
# API authorization failed. Check the API response for details.
...
except TelesignError as ex:
# Failed to completely execute the PhoneID service. Check the API response
# for details. Data returned might be incomplete or invalid.
...
"""
resource = "/v1/phoneid/standard/%s" % phone_number
method = "GET"
fields = {}
if use_case_code:
fields["ucid"] = use_case_code
if extra is not None:
fields.update(extra)
headers = generate_auth_headers(
self._customer_id,
self._secret_key,
resource,
method)
headers['User-Agent'] = self._user_agent
req = requests.get(url="{}{}".format(self._url, resource),
params=fields,
headers=headers,
proxies=self._proxy,
timeout=timeout or self._timeout) # use timeout passed in or session timeout in that order
return Response(self._validate_response(req), req)
