---
title: "Number Intelligence - Get Phone Details"
method: POST
path: "/phone-numbers/details"
tags: ["phoneNumbers"]
---

# Number Intelligence - Get Phone Details

`POST /phone-numbers/details`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/phone-numbers/details`
- Auth: API key in header `PINNACLE-API-KEY`

Retrieve information about any phone number.

## Request body

- PhoneDetailsSchema: Provide a phone number and select the level of detail you want for its analysis. <br> Choose additional options to customize the lookup and get the most relevant insights.
  - `phone` string, required: Phone number you want to analyze in E.164 format.
  - `level` 'basic' | 'advanced', required: Choose how much detail you want in your results: - `basic`: Receive essential info like carrier, location, and format. - `advanced`: Receive a deeper analysis including fraud risk, detailed location, and enhanced contact info.
  - `options` RetrievePhoneNumberDetailsOptions: Customize your lookup with additional options.
    - `force` boolean: Allows you to force a fresh lookup from primary sources instead of cached data. <br> Fresh lookups will take longer to complete than cached lookups.
    - `risk` boolean: Include a fraud risk and security analysis.
    - `enhanced_contact_info` EnhancedContactInfo: Additional information to tailor lookup.
      - `context` string: Business context.

## Response `200`

Returns detailed information for the requested phone number based on the selected lookup.

- union
  - BasicPhoneInformation: Key details about a phone number, including its validity, type, location, carrier, and contact information. Provides the essential data required for verification, display, and basic analysis.
    - `isValid` boolean, required: Indicates whether the phone number is valid and capable of receiving communications.
    - `type` 'LANDLINE' | 'MOBILE' | 'SATELLITE' | 'PREMIUM' | 'PAGING' | 'SPECIAL' | 'TOLL_FREE' | 'UNKNOWN', required: The classification of the phone number based on its service type. <br> Determines the billing, usage, and routing characteristics.
    - `formats` NumberFormat, required: Multiple formatting representations of the same phone number for different use cases. Provides flexibility for display, storage, and integration requirements.
      - `international` string, required: Phone number in E.164 format with country code prefix.
      - `national` string, required: Phone number formatted according to national conventions. <br> Includes parentheses, spaces, and dashes as commonly used in the country.
      - `raw` string, required: Phone number with only digits, no formatting or country code prefix.
    - `location` BasicPhoneInformationLocation, required: Geographic and political details where the phone number is registered.
      - `country` BasicPhoneInformationLocationCountry, required: Information about the country of registration.
        - `code` string, required: Two-letter country code where the number is registered.
        - `name` string, required: Full name of the country.
        - `prefix` string, required: International dialing prefix for the country.
      - `place` string, required: Location description including region, state/province, and city.
    - `carrier` string, required: The telecommunications carrier or service provider for the number.
    - `contact` BasicPhoneInformationContact, required: Contact information linked to the phone number registration, if available.
      - `name` string, required: Registered name associated with the phone number.
  - AdvancedPhoneInformation: Detailed phone number analysis including validation status, classification with fraud risk, precise geographic data, carrier intelligence, and enhanced contact information. Provides comprehensive insights for risk assessment, compliance, and advanced usage scenarios.
    - `isValid` boolean, required: Indicates whether the phone number is valid and capable of receiving communications.
    - `type` AdvancedPhoneInformationType, required: Detailed classification including fraud risk and security recommendations.
      - `value` 'FIXED_LINE' | 'INVALID' | 'MOBILE' | 'OTHER' | 'PAGER' | 'PAYPHONE' | 'PERSONAL' | 'PREPAID' | 'RESTRICTED_PREMIUM' | 'TOLL_FREE' | 'VOICEMAIL' | 'VOIP', required: Classification of the phone number type based on Telesign’s taxonomy. Indicates the phone’s service category, such as mobile, fixed line, toll-free, or VOIP, along with special types like prepaid, pager, or restricted premium. The "INVALID" type denotes an unrecognized or improperly formatted number.
      - `description` string, required: Explanation of the phone number type and service
      - `details` string, required: Additional technical details about the service type, billing model, and typical usage patterns for this number classification.
      - `recommendation` 'ALLOW' | 'BLOCK' | 'FLAG', required: Security recommendation based on fraud risk analysis: - `ALLOW`: Low risk, safe for normal use. - `BLOCK`: High risk, block or require additional verification. - `FLAG`: Medium risk, recommend further scrutiny or monitoring.
    - `formats` NumberFormat, required: Multiple formatting representations of the same phone number for different use cases. Provides flexibility for display, storage, and integration requirements.
      - `international` string, required: Phone number in E.164 format with country code prefix.
      - `national` string, required: Phone number formatted according to national conventions. <br> Includes parentheses, spaces, and dashes as commonly used in the country.
      - `raw` string, required: Phone number with only digits, no formatting or country code prefix.
    - `location` AdvancedPhoneInformationLocation, required: Comprehensive geographic and administrative location data with precise coordinates and timezone information for accurate localization.
      - `country` AdvancedPhoneInformationLocationCountry, required: Complete country identification and metadata.
        - `name` string, required: Name of the country.
        - `code` string, required: Two-letter country code where the number is registered.
        - `code3` string, required: Three-letter country code where the number is registered.
      - `city` string, nullable, required: Primary city or municipality associated with the phone number.
      - `state` string, nullable, required: State, province, or primary administrative division code. Uses standard 2-letter abbreviations where applicable.
      - `zip` string, nullable, required: Postal or ZIP code for the phone number's registered location.
      - `metroCode` string, nullable, required: Primary Metropolitan Statistical Area (PMSA) code for US numbers. Used for demographic and market analysis purposes.
      - `county` string, nullable, required: County or secondary administrative division name.
      - `coordinates` AdvancedPhoneInformationLocationCoordinates, required: Coordinates provide the precise latitude and longitude values for the phone number’s registered location.
        - `latitude` number, double, nullable, required: Decimal degrees latitude coordinate.
        - `longitude` number, double, nullable, required: Decimal degrees longitude coordinate.
      - `timeZone` string, nullable, required: IANA timezone identifier for the number’s location.
    - `carrier` AdvancedPhoneInformationCarrier, required: Detailed carrier information.
      - `name` string, required: Carrier or service provider name as registered with telecom authorities.
      - `normalizedCarrier` string, required: Standardized carrier name used across data sources.
      - `mcc` string, required: Mobile Country Code - 3-digit identifier assigned by ITU-T for the country. Used in GSM, UMTS, and LTE networks for international roaming and identification.
      - `mnc` string, required: Mobile Network Code - 2 or 3-digit identifier for the specific carrier within the country. Combined with MCC provides unique global identification of the mobile network.
    - `contact` AdvancedPhoneInformationContact, required: Enhanced contact information associated with the phone number.
      - `firstName` string: Given name of the primary contact.
      - `lastName` string: Family name of the primary contact.
      - `emailAddress` string: Primary email associated with the number’s registration.
      - `street` string: Street address including number and street name.
      - `unit` string: Secondary address info like suite or apartment number.
      - `place` string: Combined city, state, and postal info in a human-readable format.
      - `zip` string: Postal or ZIP code of the contact’s address.
      - `state` string: Full state or province name of the contact’s address.
      - `country` string: Full country name of the contact’s registered address.
      - `profiles` EnhancedContactItems[]: Collection of contact profiles associated with a phone number. May include multiple profiles if the number is associated with different online identities.
        - `description` string, required: Professional or personal description of the contact. May include job title, company affiliation, or biographical information.
        - `email` string, email, required: Primary email address associated with this contact profile.
        - `links` string[], required: Additional web links associated with this contact profile. May include personal websites, social media profiles, or professional portfolios.
        - `linkedin` string, nullable, required: LinkedIn profile URL if available and publicly accessible. Null if no LinkedIn profile is found or accessible.
        - `name` string, required: Full name of the contact person associated with this profile.

## Other responses

- `400`: Validation failed. The payload has missing required fields and/or invalid types. <br> See https://zod.dev/error-formatting for more information.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `402`: Insufficient credits to complete this request. <br> This occurs when your account balance is below the required amount for processing the operation. Please add credits to your account to continue using the service.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)