Phone Status Check - Detailed Documentation

Use this action to get insights about a phone number such as whether it is active or disconnected, whether its associated device is reachable or unreachable, and its associated device’s roaming status.

API Playground:

You can try the phoneid endpoint here.

Endpoints Overview

Phone Status Check: Retrieve the status and details of a phone number.

Authentication

To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.

Tokens are valid for 60 minutes and must be refreshed after expiration.
Refer to the Authentication for detailed steps on obtaining a token.
Include the token in the Authorization header as follows:

Authorization: Bearer YOUR_ACCESS_TOKEN

API Base URL

https://api-umbrella.io/api/services

1. Phone Status Check

Endpoint

POST /phoneid

Description

Use this action to get insights about a phone number, such as its activity status, device reachability, and roaming status.

Required Headers

Header	Value
Content-Type	`application/json`
Authorization	`Bearer yourAccessToken`

Request Body Parameters

Field	Type	Required	Description
`phone`	string	Yes	The phone number to check, including country code.

Response Structure

Field	Type	Description
`referenceId`	string	Unique reference ID for the transaction.
`subResource`	string	Sub-resource type (e.g., `live`).
`status`	object	Transaction status details.
`status.code`	number	Status code (e.g., `300` for success).
`status.description`	string	Status description (e.g., “Transaction successfully completed”).
`status.updatedOn`	string	Timestamp of the last update (ISO 8601 format).
`errors`	array	List of errors, if any.
`phoneType`	object	Type of phone number.
`phoneType.code`	string	Phone type code (e.g., `2` for mobile).
`phoneType.description`	string	Phone type description (e.g., “MOBILE”).
`blocklisting`	object	Blocklisting status of the phone number.
`blocklisting.blocked`	boolean	Whether the number is blocked.
`blocklisting.blockCode`	number	Block code (e.g., `0` for not blocked).
`blocklisting.blockDescription`	string	Block description (e.g., “Not blocked”).
`numbering`	object	Phone number details.
`numbering.cleansing`	object	Cleansed phone number details.
`numbering.cleansing.call`	object	Call-specific cleansing details.
`numbering.cleansing.call.countryCode`	string	Country code.
`numbering.cleansing.call.phoneNumber`	string	Phone number.
`numbering.cleansing.call.cleansedCode`	number	Cleansing status code.
`numbering.cleansing.call.minLength`	number	Minimum allowed length.
`numbering.cleansing.call.maxLength`	number	Maximum allowed length.
`numbering.cleansing.sms`	object	SMS-specific cleansing details.
`numbering.cleansing.sms.countryCode`	string	Country code.
`numbering.cleansing.sms.phoneNumber`	string	Phone number.
`numbering.cleansing.sms.cleansedCode`	number	Cleansing status code.
`numbering.cleansing.sms.minLength`	number	Minimum allowed length.
`numbering.cleansing.sms.maxLength`	number	Maximum allowed length.
`numbering.original`	object	Original phone number details.
`numbering.original.completePhoneNumber`	string	Complete phone number with country code.
`numbering.original.countryCode`	string	Country code.
`numbering.original.phoneNumber`	string	Phone number.
`location`	object	Location details of the phone number.
`location.city`	string	City associated with the phone number.
`location.state`	string	State associated with the phone number.
`location.zip`	string	ZIP code associated with the phone number.
`location.metroCode`	string	Metro code associated with the phone number.
`location.county`	string	County associated with the phone number.
`location.country`	object	Country details.
`location.country.name`	string	Country name.
`location.country.iso2`	string	ISO 2-letter country code.
`location.country.iso3`	string	ISO 3-letter country code.
`location.coordinates`	object	Geographic coordinates.
`location.coordinates.latitude`	string	Latitude.
`location.coordinates.longitude`	string	Longitude.
`location.timeZone`	object	Time zone details.
`location.timeZone.name`	string	Time zone name.
`location.timeZone.utcOffsetMax`	string	Maximum UTC offset.
`location.timeZone.utcOffsetMin`	string	Minimum UTC offset.
`carrier`	object	Carrier details.
`carrier.name`	string	Name of the carrier.
`live`	object	Live status details.
`live.subscriberStatus`	string	Subscriber status (e.g., `ACTIVE`).
`live.deviceStatus`	string	Device status (e.g., `REACHABLE`).
`live.roaming`	string	Roaming status (e.g., `UNAVAILABLE`).
`live.roamingCountry`	string	Roaming country name.
`live.roamingCountryIso2`	string	ISO 2-letter roaming country code.

Example Request

{
"phone": "+436504142107"
}

Example Response

{
    "reference_id": "36475B3EB1DC0C2492E2889F4EACF2CC",
    "sub_resource": "live",
    "status": {
        "code": 300,
        "description": "Transaction successfully completed",
        "updatedOn": "2024/09/09T12:43:42.701105Z"
    },
    "errors": [],
    "phoneType": {
        "code": "2",
        "description": "MOBILE"
    },
    "blocklisting": {
        "blocked": false,
        "blockCode": 0,
        "blockDescription": "Not blocked"
    },
    "numbering": {
        "cleansing": {
            "call": {
                "countryCode": "43",
                "phoneNumber": "6504142107",
                "cleansedCode": 100,
                "minLength": 7,
                "maxLength": 13
            },
            "sms": {
                "countryCode": "43",
                "phoneNumber": "6504142107",
                "cleansedCode": 100,
                "minLength": 7,
                "maxLength": 13
            }
        },
        "original": {
            "completePhoneNumber": "+436504142107",
            "countryCode": "43",
            "phoneNumber": "6504142107"
        }
    },
    "location": {
        "city": "Countrywide",
        "state": null,
        "zip": null,
        "metroCode": null,
        "county": null,
        "country": {
            "name": "Austria",
            "iso2": "AT",
            "iso3": "AUT"
        },
        "coordinates": {
            "latitude": null,
            "longitude": null
        },
        "timeZone": {
            "name": null,
            "utcOffsetMax": "+1",
            "utcOffsetMin": "+1"
        }
    },
    "carrier": {
        "name": "Mass Response Service GmbH"
    },
    "live": {
        "subscriberStatus": "ACTIVE",
        "deviceStatus": "REACHABLE",
        "roaming": "UNAVAILABLE",
        "roamingCountry": null,
        "roamingCountryIso2": null
    }
}

Getting Started

Essentials

Phone Status Check

Phone Status Check - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

1. Phone Status Check

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response

Getting Started

Essentials

​Phone Status Check - Detailed Documentation

​API Playground:

​Endpoints Overview

​Authentication

​API Base URL

​1. Phone Status Check

​Endpoint

​Description

​Required Headers

​Request Body Parameters

​Response Structure

​Example Request

​Example Response

Phone Status Check - Detailed Documentation

API Playground:

Endpoints Overview

Authentication

API Base URL

1. Phone Status Check

Endpoint

Description

Required Headers

Request Body Parameters

Response Structure

Example Request

Example Response