Phone Profiling Service authentication API guide

Use this guide to configure the SecureAuth Authentication API to block specified phone sources, block or allowed lists for phone carriers / countries, and identify phone numbers that recently changed carriers in order to prevent bad actors from using specified phone classes / numbers.

When the end-user attempts to use a phone number as a second authentication factor, an SMS OTP / Voice OTP is dispatched only if the phone number is allowed based on information retrieved from the phone number profiling service.

Prerequisites

Complete the steps in the Authentication API guide
Complete Phone Profiling Service configuration steps in the SecureAuth IdP Web Admin
For more information, see Phone number profiling service configuration

Identity Platform Web Admin configuration

Before you can configure the Endpoints, configure the Phone Profiling Service in the Identity Platform Advanced Settings (formerly Classic Experience).

Phone Profiling Service configuration

To use the Block Phone Numbers that Recently Changed Carriers feature, it requires you to complete these steps.

Go to the Data tab.
Map the Aux ID 2 profile Property to a directory field that meets these requirements:
For example, if it is not used, you can use accountNameHistory.
- Directory String with syntax: 2.5.5.12
- Upper Range of at least 4096
- Multi-valued set to true
Select the Writable check box for Aux ID 2.
Save your changes.
Go to the Multi-Factor Methods tab.

In the Registration Configuration section, make the following configurations for Phone Number Blocking.

Note

The phone number blocking configuration only applies to this realm.

Block phone numbers from the following sources

Select the phone source(s) to be blocked from receiving Voice OTPs or SMS / Text OTPs:

Cellular Telephones – Mobile / wireless phone numbers
Landlines – Phone numbers of home / office wired lines
IP Phones – Virtual phone numbers, also known as DID or access numbers, without a directly associated phone line
Toll-free Numbers – Phone numbers with the following area codes: 800, 888, 877, 866, 855 or 844
Premium Rate Numbers – Phone numbers or phone calls in which certain services are provided and part of the charges are paid to the service provider
Pagers – Phone numbers of call devices that can only receive messages
Unknown – Phone number of an anonymous classification

Block phone numbers that recently changed carriers

Enable this feature to prevent newly ported phone numbers from receiving Voice OTPs or SMS / Text OTPs.

Optional. If you enable this feature, then selecting the Allow users to approve or delete a phone number that has recently changed carriers check box lets end-users accept or remove a newly ported phone number from the multi-factor methods page during authentication.

Set the property in which to Store carrier information in. For example, Aux ID 2.

Note

Select the property mapped to the data store, defined in Step 2.

If using the Authentication API, this is the property that stores the originalCarrier information.

Block or allow phone numbers by carrier or country

Select Enable block / allow list to deny / permit Voice OTPs or SMS / Text OTPs to be received by phone numbers from carriers / countries specified on the activated block and allowed lists.

To configure block and allowed lists, click the Define list of blocked / allowed numbers and carriers link.

Block or Allow Countries / Carriers

Select whether to Block or Allow numbers of specified countries or carriers.
To add or remove countries and carriers, click the Add country/carrier button.
Start typing in the find and select search box to display a filtered list.
Names are organized by country name, and the carrier name within the country.
Select or clear the check boxes in the results list.
After you make your selections, click Close.
Each new country or carrier is displayed as a blue entry.
Tip
To remove a listed country (and all carriers): Click the X to the right of the country name.
To remove a listed carrier: Click the X at the end of the carrier name.

Save your changes.
Results of Block or Allow Countries / Carriers after Save
Once saved, the name of each added carrier selection appears "gray" for the given country.
Note
Countries / carriers can be removed from the list as restrictions and geopolitical conditions require. The list should then be re-saved.

Endpoints

Endpoints for /numberprofile are used on demand to view an end-user's phone number profile and update the record if information such as carrier, network, and / or country has changed.

The POST method retrieves the phone profile record from the data provider which includes the original carrier information.

The PUT method is used to update the directory to reflect the phone carrier information.

After the information is added, a subsequent POST call retrieves the stored carrier information from the directory and the current carrier information from the data provider.

If a discrepancy exists between the original carrier information and current carrier information, a PUT call is made to update the phone profile record

POST

HTTP Method	URI	Example
POST	`/api/v1/numberprofile`	https://secureauth.company.com/secureauth2/api/v1/numberprofile

user_id: User ID provided
phone_number: User phone number provided
status: State of the user ID or phone number provided (not_found, invalid, valid)
message: Additional information regarding the status of the user ID or phone number; will always be in response
providerRequestId: Unique reference identification number for the request, generated by the data provider
portedStatus: User phone status for the option to block phone numbers that recently changed carriers (not_ported, ported)
originalCarrier: The first time a POST call is made, user phone profile information from the data provider information appears here – on subsequent POST calls, user phone profile information stored in the directory appears here
currentCarrier: Following a PUT call and a subsequent POST call, user phone profile information from the data provider appears here
carrierCode: 6-digit number or a concatenation of the country code and phone type
carrier: Name of the carrier or a concatenation of the country code and phone type
countryCode: 2-character country code
networkType: Phone connection source (landline, tollfree, mobile, virtual, unknown, landline_tollfree)
carrierStatus:
- status: State of the carrier (blocked, allowed) based on the configuration defined in the Web Admin
- reason: Explanation for the state of the carrier (network_type, ported, country, carrier) based on the configuration defined in the Web Admin

Note

Before using a POST request to display the phone number profile for a designated realm, make sure the blocking option is enabled; otherwise, a NULL value is returned for all carrier values in that realm along with a status of VALID (similar to the 'invalid phone number' error response shown in the example below).

To resolve this problem, make sure the Allow option is selected in the Block or Allow Countries / Carriers option for the designated API realm (without requiring any blocked countries / carriers) as shown in Step 6 above.

JSON Parameters	Success Response (Phone profile is returned with this response)	Fail / Error Response (Phone profile is not returned with this response)
{ "user_id": "<USERNAME>", "phone_number": "<PHONE NO.>" } Example: { "user_id": "jsmith", "phone_number": "19491234567" }	{ "numberProfileResult": { "providerRequestId": "01eda1b2-d47c-4290-b1ca-6de8b2573836", "internationalFormat": "19491234567", "nationalFormat": "(949) 123-4567", "countryPrefix": "1", "countryCode": "US", "countryCodeISO3": "USA", "country": "United States of America", "portedStatus": "not_ported", "validNumber": null, "reachable": null, "roamingInfo": null, "currentCarrier": { "carrierCode": "US-FIXED", "carrier": "United States of America Landline", "countryCode": "US", "networkType": "landline", "carrierStatus": { "status": "blocked", "reason": [ "networkType" ] } }, "originalCarrier": { "carrierCode": "US-FIXED", "carrier": "T-mobile USA, Inc.", "countryCode": "US", "networkType": "mobile", "carrierStatus": { "status": "allowed", "reason": null } }, "ipInfo": null, "ipWarning": null }, "status": "valid", "message": "" }	{ "status": "not_found", "message": "User Id was not found." } HTTP Status 200 (OK - Non-existing user) { "status": "not_found", "message": "The requested resource cannot be found." } HTTP Status 404 (Not Found - Non-existing endpoint) { "status": "invalid", "message": "Request validation failed with: PhoneNumber was not present." } HTTP Status 400 (Bad Request - Missing phone number) { "status": "valid", "message": "" } HTTP Status 200 (OK - Invalid phone number) { "status": "not_found", "message": "The requested resource cannot be found." } HTTP Status 404 (Not Found - Non-existing endpoint)

JSON Parameters

Success Response

(Phone profile is returned with this response)

Fail / Error Response

(Phone profile is not returned with this response)

{
  "user_id": "<USERNAME>",
  "phone_number": "<PHONE NO.>"
}

Example:

{
  "user_id": "jsmith",
  "phone_number": "19491234567"
}

{
 "numberProfileResult": {
   "providerRequestId": "01eda1b2-d47c-4290-b1ca-6de8b2573836",
   "internationalFormat": "19491234567",
   "nationalFormat": "(949) 123-4567",
   "countryPrefix": "1",
   "countryCode": "US",
   "countryCodeISO3": "USA",
   "country": "United States of America",
   "portedStatus": "not_ported",
   "validNumber": null,
   "reachable": null,
   "roamingInfo": null,
   "currentCarrier": {
     "carrierCode": "US-FIXED",
     "carrier": "United States of America Landline",
     "countryCode": "US",
     "networkType": "landline",
     "carrierStatus": {
       "status": "blocked",
       "reason": [
         "networkType"
       ]
     }
   },
   "originalCarrier": {
     "carrierCode": "US-FIXED",
     "carrier": "T-mobile USA, Inc.",
     "countryCode": "US",
     "networkType": "mobile",
     "carrierStatus": {
       "status": "allowed",
       "reason": null
     }
   },
   "ipInfo": null,
   "ipWarning": null
 },
 "status": "valid",
 "message": ""
}

{
   "status": "not_found",
   "message": "User Id was not found."
}
HTTP Status 200 (OK - Non-existing user)

{
   "status": "not_found",
   "message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)

{
   "status": "invalid",
   "message": "Request validation failed with: PhoneNumber was not present."
}
HTTP Status 400 (Bad Request - Missing phone number)

{
   "status": "valid",
   "message": ""
}
HTTP Status 200 (OK - Invalid phone number)

{
   "status": "not_found",
   "message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)

PUT

HTTP Method	URI	Example
PUT	`/api/v1/numberprofile`	https://secureauth.company.com/secureauth2/api/v1/numberprofile

user_id: User ID provided
phone_number: User phone number provided
status: State of the user ID or phone number provided (not_found, invalid, valid)
message: Additional information regarding the status of the user ID or phone number; will always be in response
portedStatus: User phone status for the option to block phone numbers that recently changed carriers (not_ported, ported)
carrierCode: 6-digit number or a concatenation of the country code and phone type
carrier: Name of the carrier or a concatenation of the country code and phone type
countryCode: 2-character country code
networkType: Phone connection source (landline, tollfree, mobile, virtual, unknown, landline_tollfree)

JSON Parameters	Success Response (Phone profile is returned with this response)	Fail / Error Response (Phone profile is not returned with this response)
{ "user_id": "<USERNAME>", "phone_number": "<PHONE NO.>", "portedStatus": "not_ported", "carrierInfo": { "carrierCode": "<6-DIGIT NO. OR COUNTRY CODE + PHONE TYPE>", "carrier": "<CARRIER NAME OR COUNTRY CODE + PHONE TYPE", "countryCode": "<2-CHARACTER COUNTRY CODE>", "networkType": "<TYPE OF NETWORK CONNECTION>" } } Example: { "user_id": "jsmith", "phone_number": "19491234567", "portedStatus":"not_ported", "carrierInfo": { "carrierCode": "US-FIXED", "carrier": "T-mobile USA, Inc.", "countryCode": "US", "networkType": "mobile" } }	{ "status": "valid", "message": "" } HTTP Status 200 (OK - Successful PUT)	{ "status": "not_found", "message": "User Id was not found." } HTTP Status 200 (OK - Non-existing user) { "status": "not_found", "message": "The requested resource cannot be found." } HTTP Status 404 (Not Found - Non-existing endpoint) { "status": "invalid", "message": "Request validation failed with: PhoneNumber was not present." } HTTP Status 400 (Bad Request - Missing phone number) { "status": "valid", "message": "" } HTTP Status 200 (OK - Invalid phone number)

JSON Parameters

Success Response

(Phone profile is returned with this response)

Fail / Error Response

(Phone profile is not returned with this response)

{
  "user_id": "<USERNAME>",
  "phone_number": "<PHONE NO.>",
  "portedStatus": "not_ported",
  "carrierInfo": {
         "carrierCode": "<6-DIGIT NO. OR COUNTRY CODE + PHONE TYPE>",
         "carrier": "<CARRIER NAME OR COUNTRY CODE + PHONE TYPE",
         "countryCode": "<2-CHARACTER COUNTRY CODE>",
         "networkType": "<TYPE OF NETWORK CONNECTION>"
     }
}

Example:

{
  "user_id": "jsmith",
  "phone_number": "19491234567",
  "portedStatus":"not_ported",
     "carrierInfo": {
         "carrierCode": "US-FIXED",
         "carrier": "T-mobile USA, Inc.", 
         "countryCode": "US",
         "networkType": "mobile"
   }
}

{
   "status": "valid",
   "message": ""
}
HTTP Status 200 (OK - Successful PUT)

{
   "status": "not_found",
   "message": "User Id was not found."
}
HTTP Status 200 (OK - Non-existing user)

{
   "status": "not_found",
   "message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)

{
   "status": "invalid",
   "message": "Request validation failed with: PhoneNumber was not present."
}
HTTP Status 400 (Bad Request - Missing phone number)

{
   "status": "valid",
   "message": ""
}
HTTP Status 200 (OK - Invalid phone number)

In this section:

Phone Profiling Service authentication API guide

Prerequisites

Identity Platform Web Admin configuration

Phone Profiling Service configuration

Note

Note

Tip

Note

Endpoints

POST

Note

PUT

Search results