{ "components": { "securitySchemes": { "accountSid_authToken": { "scheme": "basic", "type": "http" } }, "schemas": { "lookups.v1.phone_number": { "type": "object", "properties": { "caller_name": { "nullable": true, "description": "The name of the phone number's owner. If `null`, that information was not available.", "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } } }, "country_code": { "type": "string", "nullable": true, "description": "The [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) for the phone number.", "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } } }, "phone_number": { "type": "string", "format": "phone-number", "nullable": true, "description": "The phone number in [E.164](https://www.twilio.com/docs/glossary/what-e164) format, which consists of a + followed by the country code and subscriber number.", "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } } }, "national_format": { "type": "string", "nullable": true, "description": "The phone number, in national format.", "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } } }, "carrier": { "nullable": true, "description": "The telecom company that provides the phone number." }, "add_ons": { "nullable": true, "description": "A JSON string with the results of the Add-ons you specified in the `add_ons` parameters. For the format of the object, see [Using Add-ons](https://www.twilio.com/docs/add-ons).", "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } } }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "The absolute URL of the resource." } } }, "phone_number_enum_type": { "type": "string", "enum": [ "landline", "mobile", "voip" ] } } }, "info": { "title": "Twilio - Lookups", "description": "This is the public Twilio REST API.", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio Support", "url": "https://support.twilio.com", "email": "support@twilio.com" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.0", "x-twilio": { "apiStandards": "v0.1" } }, "openapi": "3.0.1", "paths": { "/v1/PhoneNumbers/{PhoneNumber}": { "servers": [ { "url": "https://lookups.twilio.com" } ], "description": "Detailed information on phone numbers", "x-twilio": { "defaultOutputProperties": [ "caller_name", "country_code", "carrier", "url" ], "pathType": "instance" }, "get": { "description": "", "summary": "", "tags": [ "LookupsV1PhoneNumber" ], "parameters": [ { "name": "PhoneNumber", "in": "path", "description": "The phone number to lookup in [E.164](https://www.twilio.com/docs/glossary/what-e164) format, which consists of a + followed by the country code and subscriber number.", "schema": { "type": "string" }, "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } }, "required": true }, { "name": "CountryCode", "in": "query", "description": "The [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the phone number to fetch. This is used to specify the country when the phone number is provided in a national format.", "schema": { "type": "string" }, "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } }, "examples": { "fetchCarrier": { "value": "country_code" }, "fetchCarrierInternational": { "value": "country_code" }, "fetchCallerName": { "value": "country_code" }, "fetchCarrierAndCallerName": { "value": "country_code" }, "fetchAddonsWhitepagesPro": { "value": "country_code" }, "fetchAddonsPayfone": { "value": "country_code" } } }, { "name": "Type", "in": "query", "description": "The type of information to return. Can be: `carrier` or `caller-name`. The default is null. To retrieve both types of information, specify this parameter twice; once with `carrier` and once with `caller-name` as the value.", "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "fetch": { "value": [] }, "fetchCarrier": { "value": [ "carrier" ] }, "fetchCarrierInternational": { "value": [ "carrier" ] }, "fetchCallerName": { "value": [ "caller-name" ] }, "fetchCarrierAndCallerName": { "value": [ "carrier", "caller-name" ] }, "fetchAddonsWhitepagesPro": { "value": [ "caller-name" ] }, "fetchAddonsNomorobo": { "value": [ "carrier" ] }, "fetchAddonsPayfone": { "value": [ "carrier" ] } } }, { "name": "AddOns", "in": "query", "description": "The `unique_name` of an Add-on you would like to invoke. Can be the `unique_name` of an Add-on that is installed on your account. You can specify multiple instances of this parameter to invoke multiple Add-ons. For more information about Add-ons, see the [Add-ons documentation](https://www.twilio.com/docs/add-ons).", "schema": { "type": "array", "items": { "type": "string" } }, "x-twilio": { "pii": { "handling": "standard", "deleteSla": 30 } }, "examples": { "fetchAddonsWhitepagesPro": { "value": [ "whitepages_pro_caller_id" ] }, "fetchAddonsNomorobo": { "value": [ "nomorobo_spamscore" ] }, "fetchAddonsPayfone": { "value": [ "payfone_tcpa_compliance" ] } } }, { "name": "AddOnsData", "in": "query", "description": "Data specific to the add-on you would like to invoke. The content and format of this value depends on the add-on.", "schema": { "type": "object", "format": "prefixed-collapsible-map-AddOns" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/lookups.v1.phone_number" }, "examples": { "fetch": { "value": { "caller_name": null, "carrier": null, "add_ons": null, "country_code": "US", "national_format": "(510) 867-5310", "phone_number": "+15108675310", "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310" } }, "fetchCarrier": { "value": { "caller_name": null, "carrier": { "error_code": null, "mobile_country_code": "310", "mobile_network_code": "456", "name": "verizon", "type": "mobile" }, "country_code": "US", "national_format": "(510) 867-5310", "phone_number": "+15108675310", "add_ons": null, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310" } }, "fetchCarrierInternational": { "value": { "caller_name": null, "carrier": { "error_code": null, "mobile_country_code": null, "mobile_network_code": null, "name": "Vodafone Business Solutions", "type": "landline" }, "country_code": "GB", "national_format": "020 7765 1182", "phone_number": "+4402077651182", "add_ons": null, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+4402077651182" } }, "fetchCallerName": { "value": { "caller_name": { "caller_name": "Delicious Cheese Cake", "caller_type": "CONSUMER", "error_code": null }, "carrier": null, "country_code": "US", "national_format": "(510) 867-5310", "phone_number": "+15108675310", "add_ons": null, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310" } }, "fetchCarrierAndCallerName": { "value": { "caller_name": { "caller_name": "Delicious Cheese Cake", "caller_type": "CONSUMER", "error_code": null }, "carrier": { "error_code": null, "mobile_country_code": "310", "mobile_network_code": "456", "name": "verizon", "type": "mobile" }, "country_code": "US", "national_format": "(510) 867-5310", "phone_number": "+15108675310", "add_ons": { "status": "successful", "message": null, "code": null, "results": {} }, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310" } }, "fetchAddonsWhitepagesPro": { "value": { "caller_name": { "caller_name": "EMPIRE STATE BUILDING", "caller_type": "BUSINESS", "error_code": null }, "country_code": "US", "phone_number": "+12127363100", "national_format": "(212) 736-3100", "carrier": null, "add_ons": { "status": "successful", "message": null, "code": null, "results": { "whitepages_pro_caller_id": { "status": "successful", "request_sid": "XR28b8f152ae12345605b0b3cc34123456", "message": null, "code": null, "result": { "phone_number": "2127363100", "warnings": [], "historical_addresses": [], "alternate_phones": [], "error": null, "is_commercial": true, "associated_people": [], "country_calling_code": "1", "belongs_to": [], "is_valid": true, "line_type": "NonFixedVOIP", "carrier": "Level 3 Communications", "current_addresses": [ { "city": "New York", "lat_long": { "latitude": 40.748731, "longitude": -73.986413, "accuracy": "RoofTop" }, "is_active": null, "location_type": "Address", "street_line_2": null, "link_to_person_start_date": "2018-08-28", "street_line_1": "350 5th Ave", "postal_code": "10118", "delivery_point": "MultiUnit", "country_code": "US", "state_code": "NY", "id": "Location.4e81b857-1234-5678-31d29a3301e1", "zip4": "0110" } ], "id": "Phone.f8396fef-1234-5678-bc7128b6fd99", "is_prepaid": false } } } }, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+12127363100" } }, "fetchAddonsNomorobo": { "value": { "caller_name": null, "country_code": "US", "phone_number": "+19892008374", "national_format": "(989) 200-8374", "carrier": { "mobile_country_code": "310", "mobile_network_code": null, "name": "Ytel/Blitz", "type": "mobile", "error_code": null }, "add_ons": { "status": "successful", "message": null, "code": null, "results": { "nomorobo_spamscore": { "status": "successful", "request_sid": "XR763c8acc4c56d5e3e18d2f0f12345bc1", "message": null, "code": null, "result": { "status": "success", "message": "success", "score": 1 } } } }, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+19892008374" } }, "fetchAddonsPayfone": { "value": { "caller_name": null, "country_code": "US", "phone_number": "+16502530000", "national_format": "(650) 253-0000", "carrier": { "mobile_country_code": null, "mobile_network_code": null, "name": "Level 3 Communications, LLC", "type": "landline", "error_code": null }, "add_ons": { "status": "successful", "message": null, "code": null, "results": { "payfone_tcpa_compliance": { "status": "successful", "request_sid": "XRd3a2991c9108bde3ca9589ed84d31463", "message": null, "code": null, "result": { "Status": 0, "Response": { "MSISDNType": "NonFixedVoIP", "NumberMatch": "I", "VerifyNumberTransactionId": "2019459819" }, "RequestId": "XRd3a2991c9108bde3ca9589ed84d31463", "Description": "Success." } } } }, "url": "https://lookups.twilio.com/v1/PhoneNumbers/+16502530000" } } } } }, "headers": { "Access-Control-Allow-Origin": { "description": "Specify the origin(s) allowed to access the resource", "schema": { "type": "string" }, "example": "*" }, "Access-Control-Allow-Methods": { "description": "Specify the HTTP methods allowed when accessing the resource", "schema": { "type": "string" }, "example": "POST, OPTIONS" }, "Access-Control-Allow-Headers": { "description": "Specify the headers allowed when accessing the resource", "schema": { "type": "string" }, "example": "Content-Type, Authorization" }, "Access-Control-Allow-Credentials": { "description": "Indicates whether the browser should include credentials", "schema": { "type": "boolean" } }, "Access-Control-Expose-Headers": { "description": "Headers exposed to the client", "schema": { "type": "string", "example": "X-Custom-Header1, X-Custom-Header2" } } }, "description": "OK" } }, "security": [ { "accountSid_authToken": [] } ], "operationId": "FetchPhoneNumber" } } }, "servers": [ { "url": "https://lookups.twilio.com" } ], "tags": [ { "name": "LookupsV1Index" }, { "name": "LookupsV1PhoneNumber" }, { "name": "LookupsV1Version" } ], "security": [ { "accountSid_authToken": [] } ] }