Phone Status Service

Phone Status Service API Documentation

POST /phone-service/phoneStatus

Phone Status Check

cURL

curl --request POST \
  --url https://api-umbrella.io/api/services/phone-service/phoneStatus \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "[phone]"
}
'

200

{
  "referenceId": "ABC123XYZ789",
  "subResource": "live",
  "status": {
    "code": 300,
    "description": "Transaction successfully completed",
    "updatedOn": "2025-08-01T14:32:10Z"
  },
  "errors": [],
  "phoneType": {
    "code": "2",
    "description": "MOBILE"
  },
  "blocklisting": {
    "blocked": false,
    "blockCode": 0,
    "blockDescription": "Not blocked"
  },
  "numbering": {
    "cleansing": {
      "call": {
        "countryCode": "49",
        "phoneNumber": "15123456789",
        "cleansedCode": 100,
        "minLength": 7,
        "maxLength": 13
      },
      "sms": {
        "countryCode": "49",
        "phoneNumber": "15123456789",
        "cleansedCode": 100,
        "minLength": 7,
        "maxLength": 13
      }
    },
    "original": {
      "completePhoneNumber": "[phone]",
      "countryCode": "49",
      "phoneNumber": "15123456789"
    }
  },
  "location": {
    "city": "Berlin",
    "state": "Berlin",
    "zip": "10115",
    "metroCode": null,
    "county": "Berlin County",
    "country": {
      "name": "Germany",
      "iso2": "DE",
      "iso3": "DEU"
    },
    "coordinates": {
      "latitude": "52.5200",
      "longitude": "13.4050"
    },
    "timeZone": {
      "name": "Europe/Berlin",
      "utcOffsetMax": "+2",
      "utcOffsetMin": "+1"
    }
  },
  "carrier": {
    "name": "Generic Mobile GmbH"
  },
  "live": {
    "subscriberStatus": "ACTIVE",
    "deviceStatus": "REACHABLE",
    "roaming": "UNAVAILABLE",
    "roamingCountry": null,
    "roamingCountryIso2": null
  }
}

For a usage description of the Phone Status Service, please refer to the Phone Status page.

Endpoint

POST /phone-service/phoneStatus

Swagger

⬇️ Download OpenAPI YAML

Authorizations

Authorization · string · header · required

Bearer token obtained from POST /auth. Valid for 60 minutes.

Body

application/json

phoneNumber · string · required

The phone number to check, including country code (E.164).

Example:

"[phone]"

Response

200

application/json

Successfully retrieved phone status.

referenceId · string

Unique reference ID for the transaction.

Example:

"ABC123XYZ789"

subResource · string

Sub-resource type (e.g., 'live').

Example:

"live"

status · object

Show child attributes

errors · string[]

List of errors, if any.

phoneType · object

Show child attributes

blocklisting · object

Show child attributes

numbering · object

Show child attributes

location · object

Show child attributes

carrier · object

Show child attributes

live · object

Show child attributes