The API provides three distinct areas of functionality:

Number Discovery™

The discover product is designed to provide instant checks as a user enters their information or before you attempt to send a message or place a call. Check if a number is correctly formatted, genuine, active, reachable and if it was recently assigned to a new user (Number Recycle).

The discover.device product feature takes an IMEI as an input and provides a range of information related to the device such as device serial number and model, activation status, blacklist status, estimated purchase date, and retail information.

discover.device and protect.hasDeviceInfo are not to be used in the same API request. If the IMEI is known use discover.device, if the IMEI is not known use protect.hasDeviceInfo.

Number Assurance™

The assure product verifies that the number and personal details provided to you can be linked together, and match those held by our data partners and there are no suspicious activity flags. Perform data matches for Know Your Customer (KYC), proof of age, email addresses and prevent identity fraud.

Number Protect™

The protect product is used to identify suspicious behaviour in real time. Use live mobile network data to highlight potential fraud, identity theft, account takeovers, false claims and defend against sophisticated crime, including Authorised Push Payment (APP) fraud and One-Time Password (OTP) interception.

The protect.hasDeviceInfo product feature provides infomation about a device, where the IMEI number is not known and is discoverable via the mobile number.

discover.device and protect.hasDeviceInfo are not to be used in the same API request. If the IMEI is known use discover.device, if the IMEI is not known use protect.hasDeviceInfo.

A combination of API token and secret is required to send a request to the API. Access to some API features requires the pre-approval of a suitable use case with our data partners. To apply for API access and use case permission, please visit our contact page.

Depending on your account plan you will be granted access to one or more of the following API platforms:

The API will only accept and respond to secure communications using HTTPS

All requests to the Network Biometrics API require these headers:

The values required for authentication will have been provided to you during the onboarding process after requesting API access. Authentication errors will result in a 401 Unauthorised response code with a transaction status object in the JSON body giving further feedback on the error.

For the deprecated v2 services in the Number Assurance family, the API_token and API_secret are required in the body of the request rather than the header.

The API only accepts requests with the Content-Type header set to application/json. All responses are made using the same format. An invalid JSON body or unsupported content type will result in a 400: Bad request response. The API consumer may optionally provide a unique string (with a 64-character limit) to aid in matching requests, this must be supplied as the Correlation-Id request header and is echoed back in the response headers as Correlation-Id.

For the deprecated v2 services in the Number Assurance family, the optional correlation_id should be in the body of the request rather than the header.

With our Number Discovery™ feature set, verify that a customer's mobile phone number is correctly formatted, genuine, active, reachable and if it was recently assigned to a new and different subscriber (Number Recycle).

Please note the discover product is required in EVERY request but additional products such as assure or protect can be added to the request object - the ordering is not significant. Please refer to the examples provided.

• Number Recycle

  Check if a customer's mobile number remains active on a network operator, or if it was recently deactivated or recycled (hasNumberBeenRecycled), to prevent false number declarations and providing information or access to an authorised user.

• MVNO Pre-filtering

  Check if a customer's mobile number is allocated to a virtual mobile network (MVNO) or not using hasMVNOInfo, and additionally allow pre-filtering on features where they are likely to fail for MVNO customers, e.g. Assure Age Eligibility.

With our Number Assurance™ feature set, step up the protection and add confidence with Know Your Customer (KYC) data matching to verify the number provided by a customer, as part of their identity, is registered to them and does not carry any suspicious activity flags.

• Address Info

  Use the matchingAddress feature to check that the address information supplied matches that of the subscriber associated with the mobile number.
  The address features vary from country to country, below is a table highlighting the availability:

*streetAddress match in France takes an input of house name/number followed by street name (e.g. 26 Rue du Labrador)

• Age Eligibility

  Use the matchingAge feature to check if the mobile subscriber associated with the number is at least 18 years of age (i.e. 18+) and help control access to age-restricted products and services in accordance with legislation.

  Please note that some datasource restrictions might apply to matchingAge including:

  • the number must be associated with an active subscription on a supported mobile network (MVNOs excluded),
  • the number must belong to the subscription holder and bill-payer,
  • the subscription must be a pay monthly contract (PAYM).

• Device Info

  Use the matchingDeviceInfo feature to check that the identity of the mobile device (i.e. IMEI) you are expecting in transaction is the same and associated with the provided number.

• Account Info

  Use the matchingAccountInfo feature to obtain details on the subscriber account linked to number. This feature allows you to request specific information to check:

  • the contract type of the account,
  • if the subscriber account is active, and/or
  • if the device, or more specifically the SIM card, connected to the account has been reported lost or stolen.

  Additional account information may only be available on some networks when you are making a call to assure.matchingName and you generate a match, and may incur an additional charge on some networks

With our Number Protect™ feature set, identify suspicious behaviour in real time and be certain your customer is not the victim of identity theft, account takeover or sophisticated crime, including Authorised Push Payment (APP) fraud and One-Time Password (OTP) interception. Defend against fraudulent claims.

Identify SIM card hasSimChanged and device hasDeviceChanged swap events and detect suspicious call activity and patterns.

• Tenure

  Use the hasAccountTenure feature to determine if the account linked to the provided MSISDN has been held for a minimum amount of time. To provide flexibility, this can be checked using a measure of days, months, or years, or by providing a fixed date. The service will return true if the account has been held at least as long as the period given.

  In some cases, the maximum period you can check is 90 days. Your account manager will confirm where this applies.

Number Assurance is a deprecated product family and is available only to existing customers. All features and MNO coverage are included and extended within the Network Biometrics™ product family. Please contact us if you would like to migrate to the more feature rich Network Biometrics™ product family.

With our Assured Registration and Assured Age feature sets, step up the protection and add confidence with Know Your Customer (KYC) data matching to verify the number provided by a customer is registered to them, as part of their identity. Assured Age adds basic age verification by confirming date of birth. > Please note that some datasource restrictions might apply, including: > - the number must be associated with an active subscription on a supported mobile network (MVNOs excluded) > - the number must belong to the subscription holder and bill-payer > - the subscription must be a pay monthly contract (PAYM)

Call Network Biometrics™ services as specified in the request body.

The API call will respond with appropriate HTTP status codes set in the header and additional detail within the JSON body.

There are 3 types of responses that can be returned from each feature requested:

1. a successful call to the feature (i.e., data is held about the number in question and has been returned within the matching response object).
2. a successful call to the feature, however the requested data is unavailable, which is indicated by the isDataAvailable flag set to false (where applicable).
3. a failed call, which could be for a number of reasons - in this case the feature response will contain a status object indicating the error.

All successful assure features will return isDataAvailable & isMatched

• isDataAvailable indicates if the subscriber data is available.
• isMatched indicates if the data provided in the request matches the data held about the subscriber.

The isMatched flag is directly linked with matchConfidence as further explained below. Similarly, the deprecated v2 services in the Number Assurance family, will respond with *_match and *_data_available for the requested data points, e.g. first_name_match and first_name_data_available

As part of the assure features matchingName, matchingAddress, and matchingBirthDate we will return a matchConfidence property as an integer between 0-100 (representing a percentage score of how much the requested data matches with data held about the subscriber).

Match thresholds : for email and date of birth matching, a 100% match is required to trigger the isMatched flag as true. All other fields are considered to be isMatched true at or above 90%.

Please note that for some user data we may only be able to respond with a matchConfidence of 100 for isMatched true or 0 for isMatched false, and no intermediate scores will be provided.

For more information see the 200: OK example for UK and France assure responses.

Some features of our product allow you to specify a time period to verify if the relevant event happened during that time (i.e. hasNumberBeenRecycled, hasSimChanged, hasDeviceChanged, wasReportedLostOrStolen, hasAccountTenure, wasBlacklisted)

Those features all at a minimum return a flag indicating if the event happened within the requested period, e.g. changedInTimePeriod, and the date of the last registered event, e.g. lastChange, however that field will only return a date/time value if the event took place during the same time period

Scenario: we want to check that a SIM change event happened during the last 15 minutes (900 seconds)

{
  "discover": {
    "number": "447700900501"
  },
  "protect": {
    "hasSimChanged": {
      "inSeconds": 900
    }
  }
} 

If the event has occurred during the last 15 minutes the Network Biometrics™ API will return:

{
  "discover": {
    "number": {
      "is": "447700900501",
      "isCorrectFormat": true,
      "isValid": true,
      "country": {
        "name": "United Kingdom of Great Britain and Northern Ireland",
        "code": "GB",
        "dialCode": "44"
            },
            "onNetwork": {
                "MCC": "001",
                "MNC": "04",
                "networkName": "Phronesis (H3G UK)"
            },
            "isPorted": false
        }
    },
    "protect": {
        "hasSimChanged": {
            "changedInTimePeriod": true,
            "lastChange": "2023-05-26T12:19:11+00:00"
        }
    },
  "transaction": {
    "status": {
      "value": 0,
      "message": "transaction successful"
    },
    "reference": "https://developer.api.v3.phronesis.tech/",
    "id": "dad42be1-fdcd-49ee-bd4c-c153befbff35"
  }
}

However, if the event did not occur during the specified time the field lastChange will be null:

{
  "discover": {
    "number": {
      "is": "447700900501",
      "isCorrectFormat": true,
      "isValid": true,
      "country": {
        "name": "United Kingdom of Great Britain and Northern Ireland",
        "code": "GB",
        "dialCode": "44"
            },
            "onNetwork": {
                "MCC": "001",
                "MNC": "04",
                "networkName": "Phronesis (H3G UK)"
            },
            "isPorted": false
        }
    },
    "protect": {
        "hasSimChanged": {
            "changedInTimePeriod": false,
            "lastChange": null
        }
    },
    "transaction": {
        "status": {
            "value": 0,
            "message": "transaction successful"
        },
        "reference": "https://developer.api.v3.phronesis.tech/",
        "id": "bd843246-1eed-4519-9869-a7fdc72a260e"
    }
}

The following numbers with associated personas are provided for testing purposes and will generate scenarios as described without making costly calls to the mobile network operators (MNO). Each number can be tested on any of our platforms to which you have been granted access during your onboarding.

EE UK

O2 UK

H3G UK

Phronesis (H3G UK)

Phronesis (WindTre IT)

Phronesis (Vodafone UK)

Phronesis (Vodafone NL)

Phronesis (Vodafone DE)

Phronesis (EE UK)

Phronesis (O2 UK)

Phronesis (invalid or unknown)

Phronesis (Telefonica DE)

Phronesis (SFR)

Phronesis (Bouygues)

Phronesis (Orange)

Phronesis (Free Mobile)

Phronesis (KPN)

Phronesis (Odido)

Virgin Mobile Telecoms Limited

Vodafone UK

Vodafone Enabler Espana SL

Vodafone

Vodafone D2

Vodafone Libertel

Orange France

Bouygues France

Free Mobile

T-Mobile US-SVR-10X/2

Cingular Wireless-NSR/2

Vodafone (former Omnitel Pronto Italia)

Noverca - full mvno TIM

KPN B.V.

T-Mobile Netherlands B.V.

Telefónica Móviles España, SAU

Telefonica Germany GmbH & Co. oHG