> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pinnacle.sh/v-2/api-reference/phone-numbers/get/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server. # Number Intelligence - Get Phone Details POST https://api.pinnacle.sh/phone-numbers/details Content-Type: application/json Retrieve information about any phone number. Reference: https://docs.pinnacle.sh/api-reference/phone-numbers/get ## Authentication - `PINNACLE-API-KEY` header (required) — API Key authentication via header ## Request ### Body (application/json) This endpoint expects a phoneDetailsSchema. - `phone` (string, required) — Phone number you want to analyze in E.164 format. - `level` (enum, 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. - Allowed values: `basic`, `advanced` - `options` (RetrievePhoneNumberDetailsOptions, optional) — Customize your lookup with additional options. ## Response ### 200 Returns detailed information for the requested phone number based on the selected lookup. - `phone numbers_get_Response_200` ## Errors ### 400 Bad Request Error Validation failed. The payload has missing required fields and/or invalid types. See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information. - `description` (string, required) — Human-readable summary of validation failures. - `errors` (ZodErrorErrors, required) — Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array ### 401 Unauthorized Error The request lacks valid authentication credentials or the provided credentials are invalid. Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 402 Payment Required Error Insufficient credits to complete this request. 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. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 403 Forbidden Error Your subscription does not include access to this feature. This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 404 Not Found Error The requested resource could not be found. This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 500 Internal Server Error An unexpected error occurred on Pinnacle's servers while processing your request. If this error persists, please contact support with the request details. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ## Types ### RetrievePhoneNumberDetailsOptions Customize your lookup with additional options. - `force` (boolean, optional) — Allows you to force a fresh lookup from primary sources instead of cached data. Fresh lookups will take longer to complete than cached lookups. - `risk` (boolean, optional) — Include a fraud risk and security analysis. - `enhanced_contact_info` (EnhancedContactInfo, optional) — Additional information to tailor lookup. ### 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` (enum, required) — Classification of the phone number. - Allowed values: `LANDLINE`, `MOBILE`, `SATELLITE`, `PREMIUM`, `PAGING`, `SPECIAL`, `TOLL_FREE`, `UNKNOWN` - `formats` (NumberFormat, required) — Different standardized ways the phone number can be formatted for display. - `location` (BasicPhoneInformationLocation, required) — Geographic and political details where the phone number is registered. - `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. ### 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. - `formats` (NumberFormat, required) — Different standardized ways the phone number can be formatted for display or dialing. - `location` (AdvancedPhoneInformationLocation, required) — Comprehensive geographic and administrative location data with precise coordinates and timezone information for accurate localization. - `carrier` (AdvancedPhoneInformationCarrier, required) — Detailed carrier information. - `contact` (AdvancedPhoneInformationContact, required, nullable) — Enhanced contact information associated with the phone number. ### ZodErrorErrors Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array ### EnhancedContactInfo Additional information to tailor lookup. - `context` (string, optional) — Business context. ### NumberFormat 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. 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. ### BasicPhoneInformationLocation Geographic and political details where the phone number is registered. - `country` (BasicPhoneInformationLocationCountry, required) — Information about the country of registration. - `place` (string, required) — Location description including region, state/province, and city. ### BasicPhoneInformationContact Contact information linked to the phone number registration, if available. - `name` (string, required) — Registered name associated with the phone number. ### AdvancedPhoneInformationType Detailed classification including fraud risk and security recommendations. - `value` (enum, required) — Technical classification derived from carrier intelligence systems. - Allowed values: `FIXED_LINE`, `INVALID`, `MOBILE`, `OTHER`, `PAGER`, `PAYPHONE`, `PERSONAL`, `PREPAID`, `RESTRICTED_PREMIUM`, `TOLL_FREE`, `VOICEMAIL`, `VOIP` - `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` (enum, 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. - Allowed values: `ALLOW`, `BLOCK`, `FLAG` ### AdvancedPhoneInformationLocation Comprehensive geographic and administrative location data with precise coordinates and timezone information for accurate localization. - `country` (AdvancedPhoneInformationLocationCountry, required) — Complete country identification and metadata. - `city` (string, required, nullable) — Primary city or municipality associated with the phone number. - `state` (string, required, nullable) — State, province, or primary administrative division code. Uses standard 2-letter abbreviations where applicable. - `zip` (string, required, nullable) — Postal or ZIP code for the phone number's registered location. - `metroCode` (string, required, nullable) — Primary Metropolitan Statistical Area (PMSA) code for US numbers. Used for demographic and market analysis purposes. - `county` (string, required, nullable) — County or secondary administrative division name. - `coordinates` (AdvancedPhoneInformationLocationCoordinates, required) — Coordinates provide the precise latitude and longitude values for the phone number’s registered location. - `timeZone` (string, required, nullable) — IANA timezone identifier for the number’s location. ### AdvancedPhoneInformationCarrier 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. ### AdvancedPhoneInformationContact Enhanced contact information associated with the phone number. - `firstName` (string, optional) — Given name of the primary contact. - `lastName` (string, optional) — Family name of the primary contact. - `emailAddress` (string, optional) — Primary email associated with the number’s registration. - `street` (string, optional) — Street address including number and street name. - `unit` (string, optional) — Secondary address info like suite or apartment number. - `place` (string, optional) — Combined city, state, and postal info in a human-readable format. - `zip` (string, optional) — Postal or ZIP code of the contact’s address. - `state` (string, optional) — Full state or province name of the contact’s address. - `country` (string, optional) — Full country name of the contact’s registered address. - `profiles` (list of EnhancedContactItems, optional) — Collection of online profiles and social media accounts associated with the contact. These are potential candidates and may be inaccurate. Always double check. ### BasicPhoneInformationLocationCountry 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. ### AdvancedPhoneInformationLocationCountry 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. ### AdvancedPhoneInformationLocationCoordinates Coordinates provide the precise latitude and longitude values for the phone number’s registered location. - `latitude` (double, required, nullable) — Decimal degrees latitude coordinate. - `longitude` (double, required, nullable) — Decimal degrees longitude coordinate. ### EnhancedContactItems - `description` (string, required) — Professional or personal description of the contact. May include job title, company affiliation, or biographical information. - `email` (string, required) — Primary email address associated with this contact profile. - `links` (list of string, required) — Additional web links associated with this contact profile. May include personal websites, social media profiles, or professional portfolios. - `linkedin` (string, required, nullable) — 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. ## Examples ### Successful Basic Phone Number Details **Request** ```json { "phone": "+11234567890", "level": "advanced", "options": { "risk": true, "enhanced_contact_info": { "context": "This is my friend from JZ. He has done a lot in the crypto space." } } } ``` **Response** ```json { "isValid": true, "type": "MOBILE", "formats": { "international": "+11234567890", "national": "(123) 456-7890", "raw": "12345678901" }, "location": { "country": { "code": "US", "name": "United States", "prefix": "+1" }, "place": "Springfield, Illinois" }, "carrier": "Example Telecom", "contact": { "name": "DOE, JOHN" } } ``` **SDK Code** ```python Successful Basic Phone Number Details import requests url = "https://api.pinnacle.sh/phone-numbers/details" payload = { "phone": "+11234567890", "level": "advanced", "options": { "risk": True, "enhanced_contact_info": { "context": "This is my friend from JZ. He has done a lot in the crypto space." } } } headers = { "PINNACLE-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Successful Basic Phone Number Details const url = 'https://api.pinnacle.sh/phone-numbers/details'; const options = { method: 'POST', headers: {'PINNACLE-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"phone":"+11234567890","level":"advanced","options":{"risk":true,"enhanced_contact_info":{"context":"This is my friend from JZ. He has done a lot in the crypto space."}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Successful Basic Phone Number Details package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/phone-numbers/details" payload := strings.NewReader("{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("PINNACLE-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Successful Basic Phone Number Details require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/phone-numbers/details") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["PINNACLE-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java Successful Basic Phone Number Details import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.pinnacle.sh/phone-numbers/details") .header("PINNACLE-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}") .asString(); ``` ```php Successful Basic Phone Number Details request('POST', 'https://api.pinnacle.sh/phone-numbers/details', [ 'body' => '{ "phone": "+11234567890", "level": "advanced", "options": { "risk": true, "enhanced_contact_info": { "context": "This is my friend from JZ. He has done a lot in the crypto space." } } }', 'headers' => [ 'Content-Type' => 'application/json', 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Successful Basic Phone Number Details using RestSharp; var client = new RestClient("https://api.pinnacle.sh/phone-numbers/details"); var request = new RestRequest(Method.POST); request.AddHeader("PINNACLE-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Successful Basic Phone Number Details import Foundation let headers = [ "PINNACLE-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "phone": "+11234567890", "level": "advanced", "options": [ "risk": true, "enhanced_contact_info": ["context": "This is my friend from JZ. He has done a lot in the crypto space."] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/phone-numbers/details")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Successful Advanced Phone Number Details **Request** ```json { "phone": "+11234567890", "level": "advanced", "options": { "risk": true, "enhanced_contact_info": { "context": "This is my friend from JZ. He has done a lot in the crypto space." } } } ``` **Response** ```json { "isValid": true, "type": { "value": "MOBILE", "description": "\"Mobile telephones are provided by companies such as Verizon or Sprint that require contracts, making these telephone numbers traceable and generally low-risk. However, some prepaid mobile phones will be identified as Mobile. Internationally, phones identified as mobile can also include TETRA mobile phones, cordless access systems, proprietary fixed radio access, and fixed cellular systems.\"\n", "details": "", "recommendation": "ALLOW" }, "formats": { "international": "+11234567890", "national": "(123) 456-7890", "raw": "1234567890" }, "location": { "country": { "name": "United States", "code": "US", "code3": "USA" }, "city": "Springfield", "state": "IL", "zip": "62704", "metroCode": "1234", "county": "Example County", "coordinates": { "latitude": 39.7817, "longitude": -89.6501 }, "timeZone": "America/Chicago" }, "carrier": { "name": "Example Telecom Inc.", "normalizedCarrier": "Example Telecom", "mcc": "", "mnc": "12345" }, "contact": { "firstName": "John", "lastName": "Doe", "emailAddress": "johndoe@example.com", "street": "123 Main St", "unit": "", "place": "", "zip": "62704", "state": "IL", "country": "US", "profiles": [ { "description": "", "email": "johndoe@example.com", "links": [ "https://example.com/profile/johndoe", "https://linkedin.com/in/johndoe" ], "linkedin": "https://linkedin.com/in/johndoe", "name": "John Doe" } ] } } ``` **SDK Code** ```python Successful Advanced Phone Number Details import requests url = "https://api.pinnacle.sh/phone-numbers/details" payload = { "phone": "+11234567890", "level": "advanced", "options": { "risk": True, "enhanced_contact_info": { "context": "This is my friend from JZ. He has done a lot in the crypto space." } } } headers = { "PINNACLE-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Successful Advanced Phone Number Details const url = 'https://api.pinnacle.sh/phone-numbers/details'; const options = { method: 'POST', headers: {'PINNACLE-API-KEY': '', 'Content-Type': 'application/json'}, body: '{"phone":"+11234567890","level":"advanced","options":{"risk":true,"enhanced_contact_info":{"context":"This is my friend from JZ. He has done a lot in the crypto space."}}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Successful Advanced Phone Number Details package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/phone-numbers/details" payload := strings.NewReader("{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("PINNACLE-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Successful Advanced Phone Number Details require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/phone-numbers/details") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["PINNACLE-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java Successful Advanced Phone Number Details import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.pinnacle.sh/phone-numbers/details") .header("PINNACLE-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}") .asString(); ``` ```php Successful Advanced Phone Number Details request('POST', 'https://api.pinnacle.sh/phone-numbers/details', [ 'body' => '{ "phone": "+11234567890", "level": "advanced", "options": { "risk": true, "enhanced_contact_info": { "context": "This is my friend from JZ. He has done a lot in the crypto space." } } }', 'headers' => [ 'Content-Type' => 'application/json', 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Successful Advanced Phone Number Details using RestSharp; var client = new RestClient("https://api.pinnacle.sh/phone-numbers/details"); var request = new RestRequest(Method.POST); request.AddHeader("PINNACLE-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"phone\": \"+11234567890\",\n \"level\": \"advanced\",\n \"options\": {\n \"risk\": true,\n \"enhanced_contact_info\": {\n \"context\": \"This is my friend from JZ. He has done a lot in the crypto space.\"\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Successful Advanced Phone Number Details import Foundation let headers = [ "PINNACLE-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "phone": "+11234567890", "level": "advanced", "options": [ "risk": true, "enhanced_contact_info": ["context": "This is my friend from JZ. He has done a lot in the crypto space."] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/phone-numbers/details")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` > One API for RCS, iMessage, MMS, and SMS. Build, test, and scale every channel — send your first message in minutes, not weeks.