Skip to main content
POST
/
phone-service
/
phoneid
Phone ID
curl --request POST \
  --url https://api-umbrella.io/api/services/phone-service/phoneid \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "11234567890",
  "accountLifecycleEvent": "create",
  "externalId": "CustomExternalID7349",
  "originatingIp": "203.0.113.45",
  "addons": {
    "ageVerify": {
      "ageThreshold": 21
    },
    "contact": {
      "email": "test@example.com"
    },
    "contactMatch": {
      "firstName": "string",
      "lastName": "string",
      "address": "string",
      "city": "string",
      "postalCode": "string",
      "state": "string",
      "country": "string",
      "inputUsed": "email"
    },
    "contactPlus": {
      "billingPostalCode": "95110"
    },
    "numberDeactivation": {
      "carrierName": "Verizon",
      "lastDeactivated": "2016-04-05T00:00:00Z",
      "trackingSince": "2014-10-06T00:00:00Z",
      "status": {
        "code": 2800,
        "description": "Request successfully completed"
      },
      "recycledSinceLastVerification": "notRecycled"
    },
    "portingHistory": {
      "pastXDays": 10
    },
    "breachedData": {},
    "callForwardDetection": {},
    "subscriberStatus": {},
    "portingStatus": {},
    "simSwap": {}
  },
  "consent": {
    "method": 1,
    "timestamp": "2018-05-05T00:00:00Z"
  }
}
'
{
  "status": true,
  "data": {
    "referenceId": "0123456789ABCDEF0123456789ABCDEF",
    "externalId": null,
    "status": {
      "code": 300,
      "description": "Transaction successfully completed",
      "updatedOn": "2025-01-01T00:00:00Z"
    },
    "location": {
      "city": "Countrywide",
      "state": null,
      "zip": null,
      "metroCode": null,
      "county": null,
      "country": {
        "name": "Exampleland",
        "iso2": "EX",
        "iso3": "EXL"
      },
      "coordinates": {
        "latitude": null,
        "longitude": null
      },
      "timeZone": {
        "name": null,
        "utcOffsetMax": "+0",
        "utcOffsetMin": "+0"
      }
    },
    "blocklisting": {
      "blocked": false,
      "blockCode": 0,
      "blockDescription": "Not blocked"
    },
    "numbering": {
      "cleansing": {
        "call": {
          "countryCode": "99",
          "phoneNumber": "5550123456",
          "cleansedCode": 100,
          "minLength": 7,
          "maxLength": 13
        },
        "sms": {
          "countryCode": "99",
          "phoneNumber": "5550123456",
          "cleansedCode": 100,
          "minLength": 7,
          "maxLength": 13
        }
      },
      "original": {
        "completePhoneNumber": "+995550123456",
        "countryCode": "99",
        "phoneNumber": "5550123456"
      }
    },
    "phoneType": {
      "code": "2",
      "description": "MOBILE"
    },
    "carrier": {
      "name": "Example Mobile Ltd"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Endpoint

POST /phone-service/phoneid

​
Swagger

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
phoneNumber
string
required

Phone number to query, including country code (no spaces or symbols).

Example:

"11234567890"

​
accountLifecycleEvent
enum<string>

Stage of the user journey.

Available options:
create,
sign-in,
transact,
update,
delete
Example:

"create"

​
externalId
string

Customer-defined ID echoed in the response.

Example:

"CustomExternalID7349"

​
originatingIp
string

End user's IP address (IPv4 or IPv6).

Example:

"203.0.113.45"

​
addons
object

Add-on services to enrich the phone lookup.

​
consent
object

Consent record for querying the number — required for certain add-ons.

Response

Successfully retrieved phone ID information.

​
status
boolean
required

Indicates if the API request itself was successful.

​
data
object
required