---
updatedAt: 2026-04-24T14:41:53.000Z
agentTools:
projectIndex: https://docs.talkdesk.com/llms.txt
---
# Get a phone number validation data
Returns reputation and quality information for a phone number, such as fraud and risk signals.
Use this endpoint to inspect a phone number before deciding how to handle the corresponding contact, for example to flag suspicious callers or to route low-risk numbers through a faster path.
The phone number must be provided in E.164-style format.
Each validation is billable for accounts with an active Identity license.
For aggregate usage information, use the stats variant of this endpoint instead.
## Scope
`identity-phone-validation:read`
# OpenAPI definition
```json
{
"openapi": "3.0.2",
"info": {
"title": "Public API",
"version": "5.12.71",
"description": "Documents public API endpoints. Scopes are given to external software, that we don't control",
"contact": {
"name": "Talkdesk",
"url": "https://talkdesk.com"
}
},
"servers": [
{
"url": "https://api.talkdeskapp.com",
"description": "United States (td-us-1)"
},
{
"url": "https://api.talkdeskapp.eu",
"description": "Europe (td-eu-1)"
},
{
"url": "https://api.talkdeskappca.com",
"description": "Canada (td-ca-1)"
},
{
"url": "https://api.talkdeskapp.co.uk",
"description": "United Kingdom (td-uk-1)"
}
],
"tags": [
{
"name": "Identity API",
"description": "Identity API"
}
],
"paths": {
"/identity/phonevalidations/{phone_number}": {
"get": {
"description": "Returns reputation and quality information for a phone number, such as fraud and risk signals.\nUse this endpoint to inspect a phone number before deciding how to handle the corresponding contact, for example to flag suspicious callers or to route low-risk numbers through a faster path.
\nThe phone number must be provided in E.164-style format.\nEach validation is billable for accounts with an active Identity license.\nFor aggregate usage information, use the stats variant of this endpoint instead.",
"operationId": "getPhoneValidation",
"parameters": [
{
"name": "phone_number",
"in": "path",
"description": "Phone number",
"required": true,
"schema": {
"type": "string",
"minimum": 1,
"maximum": 24
},
"example": "+351999999999"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"description": "Phone validation parameters page",
"properties": {
"_embedded": {
"description": "Phone validation parameters.",
"properties": {
"active": {
"description": "Is this phone number a live usable phone number that is currently active?",
"type": "string"
},
"carrier": {
"description": "The carrier (service provider) this phone number has been assigned to or \"N/A\" if unknown.",
"type": "string"
},
"country": {
"description": "The two character country code for this phone number.",
"type": "string"
},
"name": {
"description": "The name of the owner associated with the phone number, such as the first or last name or business name assigned to the phone number. Might return multiple names in comma-separated format. Value is \"N/A\" if unknown.",
"type": "string"
},
"city": {
"description": "City of the phone number if available or \"N/A\" if unknown.",
"type": "string"
},
"region": {
"description": "Region (state) of the phone number if available or \"N/A\" if unknown.",
"type": "string"
},
"zip_code": {
"description": "Zip or Postal code of the phone number if available or \"N/A\" if unknown.",
"type": "string"
},
"timezone": {
"description": "Time zone of the phone number if available or \"N/A\" if unknown.",
"type": "string"
},
"do_not_call": {
"description": "Indicates if the phone number is listed on any Do Not Call (DNC) lists. This parameter is only supported in the USA and Canada.",
"type": "string"
},
"fraud_score": {
"description": "The phone risk score which estimating how likely the phone number is to be fraudulent. Scores 85+ are high risk.",
"format": "int32",
"type": "integer"
},
"id": {
"description": "Phone number",
"type": "string"
},
"leaked": {
"description": "Has this phone number recently been exposed in an online database breach or act of compromise, if available, or \"N/A\" if unknown.",
"type": "string"
},
"line_type": {
"description": "The type of line this phone number is associated with (Toll Free, Mobile, Landline, Satellite, VOIP, Premium Rate, Pager, etc...) or \"N/A\" if unknown.",
"type": "string"
},
"prepaid": {
"description": "Is this phone number associated with a prepaid service plan?",
"type": "string"
},
"recent_abuse": {
"description": "Has this phone number been associated with recent or ongoing fraud?",
"type": "string"
},
"risky": {
"description": "Is this phone number associated with fraudulent activity, scams, robo calls, fake accounts, or other unfriendly behavior?",
"type": "string"
},
"spammer": {
"description": "Indicates if the phone number has recently been reported for spam or harassing calls/texts, if available, or \"N/A\" if unknown.",
"type": "string"
},
"tcpa_blacklist": {
"description": "Indicates if the phone number is known to be or associated with repeated TCPA plaintiffs (individuals who frequently file TCPA lawsuits).",
"type": "string"
},
"status": {
"description": "Is the number considered safe, suspicious, or high risk?",
"enum": [
"HIGH_RISK",
"SAFE",
"SUSPICIOUS",
"ERROR"
],
"type": "string"
},
"valid": {
"description": "Is the phone number properly formatted and considered valid based on assigned phone numbers available to carriers in that country?",
"type": "boolean"
},
"voip": {
"description": "Is this phone number a Voice Over Internet Protocol (VOIP) or digital phone number?",
"type": "string"
}
},
"type": "object"
},
"_links": {
"properties": {
"self": {
"description": "Show self link.",
"required": [
"href"
],
"properties": {
"href": {
"description": "The hypertext reference describing this link.",
"example": "https://api.talkdeskstg.com/identity?page=1&per_page=10",
"type": "string"
}
},
"type": "object"
}
},
"type": "object",
"description": "This page reference links"
}
},
"type": "object"
},
"example": {
"_embedded": {
"id": "+17025551234",
"status": "SAFE",
"valid": true,
"active": "true",
"fraud_score": 10,
"recent_abuse": "true",
"voip": "true",
"prepaid": "true",
"risky": "true",
"carrier": "Verizon",
"line_type": "Wireless",
"country": "US",
"name": "Joseph Pinetrees",
"city": "Las Vegas",
"region": "Nevada",
"zip_code": "89132",
"timezone": "America/Los_Angeles",
"do_not_call": "false",
"tcpa_blacklist": "false",
"success": true
},
"_links": {
"self": {
"href": "https://api-docs.talkdesk.org/identity/phonevalidations/%2B17025551234"
}
}
}
}
},
"description": "Phone validation data"
},
"400": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1910003",
"message": "A constraint violation error has occurred."
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1910010",
"message": "Unauthorized"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1910009",
"message": "Forbidden"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"description": {
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"example": {
"code": "1910001",
"message": "Phone quality service not available."
}
}
},
"description": "Not Found"
}
},
"security": [
{
"GA": [
"identity-phone-validation:read"
]
}
],
"summary": "Get a phone number validation data",
"tags": [
"Identity API"
]
}
}
},
"components": {
"securitySchemes": {
"GA": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://{account_name}.talkdeskid.com/oauth/authorize",
"tokenUrl": "https://{account_name}.talkdeskid.com/oauth/token",
"scopes": {
"account:read": "Show account details",
"apps:read": "Get details about app installations for an account",
"apps:write": "Update an app installation state programatically",
"attributes:read": "List attributes or attribute categories for an account and get details for a specific attribute",
"attributes:write": "Create, update and remove attributes or attributes categories for an account",
"bulk-imports:read": "Get list of imports and export errors into CSV file",
"bulk-imports:write": "Create and update import data",
"messages:write": "Ability to send messages from the API",
"callback:write": "Request a new direct callback",
"contacts-integrations:read": "Get details for contacts' integrations",
"contacts:read": "Get details for contact(s)",
"contacts:write": "Create, update or delete contacts",
"contact-gdpr:write": "GDPR Contacts",
"continuity-settings:read": "Read business continuity settings",
"continuity-settings:write": "Change business continuity settings",
"continuity-settings-activation:read": "Read information on activation of the continuity settings",
"continuity-settings-activation:write": "Edit information on activation of the continuity settings",
"data-reports:read": "Download previously generated data reports",
"data-reports:write": "Create new data reports",
"data-tables:read": "Fetch and list data tables",
"data-tables:write": "Create and update data tables",
"data-tables-exports:read": "List and download data table exports",
"data-tables-exports:write": "Create and cancel data table exports",
"events:read": "Get details from received events",
"express-provisioning:read": "Express-provisioning validate if account exists",
"express-provisioning:write": "Provisioning of an account",
"express-accounts-usage:read": "Read usage information for an account",
"express-accounts:read": "Read account information",
"express-accounts-contracts:read": "Get contract info for express accounts",
"express-accounts-contracts-actions:write": "Create contract actions for express accounts",
"express-accounts-contracts-actions:read": "Read contract actions of express accounts",
"express-products:read": "Read product information",
"express-accounts-subscriptions:read": "Read subscription information for an account",
"express-accounts-invoices:read": "Read invoice information for an account",
"erc-ecommerce-shopify-webhooks-handler-credentials:write": "Create or update Shopify webhook handler credentials",
"erc-ecommerce-shopify-webhooks-handler-credentials:read": "Read Shopify webhook handler credentials",
"flows-interactions:start": "Starts an interaction associated with a flow",
"flows-platform:submit": "Trigger an automation flow associated with an account",
"fsi-accounts:read": "List of accounts associated with a contact",
"fsi-contacts:write": "Update contact information",
"fsi-contacts:read": "List and get contact details",
"fsi-cards:read": "List of cards from a account",
"fsi-cards:write": "Update the status for a card",
"fsi-payments:read": "List of payments from a specific account",
"fsi-transactions:read": "List of transactions for a specific account",
"fsi-payoff:read": "Get the payoff for an FSI account",
"fsi-transfers:write": "Create an FSI Transfer",
"fsi-stop-payment:write": "Cancel a payment before it’s been processed",
"fsi-travel-notification:write": "Create a new endpoint for Travel Notifications",
"fsi-checks:read": "Search for a check",
"fsi-set-ach-transfer:write": "FSI Set ACH Transfer",
"fsi-unlock-account:write": "Unlock account for a banking customer",
"fsi-decrypt:read": "The decryption based on AES algorithm",
"fsi-write-back:write": "FSI Write Data Back",
"fsi-spend-limit:read": "Daily limit for reading debit cards",
"fsi-spend-limit:write": "Modify the daily limit of debit cards",
"guardian-call-quality:read": "Read Guardian call quality data.",
"guardian-sessions:read": "Read Sessions Guardian data.",
"guardian-users:read": "Read Users Guardian data.",
"guardian-cases:read": "Read Cases Guardian data.",
"identity-activity:read": "Identity activity read access",
"identity-email-validation:read": "Identity Email Validation read access",
"identity-ip-validation:read": "Identity IP Validation read access",
"identity-phone-validation:read": "Identity Phone Validation read access",
"openid": "User info endpoint",
"recordings:read": "Get recording files",
"recordings:delete": "Delete recording files",
"refresh_token": "Token refresh flow",
"reports:read": "List previously generated reports and download them",
"reports:write": "Create new reports or delete existing ones",
"queues:read": "List CCAAS queues",
"queues:write": "Create/update CCAAS queues details",
"queues-users:read": "List users assigned to a CCAAS queue",
"users:read": "List users for an account and get details for a specific user",
"users:write": "Create, Update and Delete users",
"interactions:control-recordings": "Control the recording status of an interaction",
"fsi-workspace-contact-synchronization:write": "Synchronize Talkdesk contact with fsi member information",
"voicebiometrics-enroll:write": "Update and delete Voice Biometrics enroll data",
"voicebiometrics-consent:read": "VoiceBiometrics consent read access",
"voicebiometrics-consent:write": "VoiceBiometrics consent write access",
"live-queries:read": "Read and list queries from Live API",
"live-subscriptions:read": "Read subscriptions from Live API",
"live-subscriptions:write": "Create a new subscription for Live API",
"wfm-aion-public:write": "Create, Update and Delete WFM Aion related data by an external client.",
"wfm-request-management-public:write": "Create, Update and Delete WFM Request Management related data by an external client.",
"wfm-request-management-public:read": "Read WFM Request Management related data by an external client.",
"account-wallets:read": "Get information about account wallets",
"bucket-configurations:read": "Get all bucket configurations",
"cases-public:write": "Create,update and delete case data",
"cases-public:read": "Read case",
"case-notes-public:read": "Read case note data",
"case-notes-public:write": "Create, edit, and delete case note data",
"case-fields-public:read": "Read case field",
"do-not-call-lists:manage": "Update a DNCL by adding or deleting a entry on a do not call list",
"do-not-call-lists:read": "Read entries in a do not call list",
"record-lists:manage": "Ability to view, add and update records of a Record List",
"record-lists:write": "Create and update record lists for an account",
"role-permissions:skip": "Skip role permissions validation",
"campaigns:write": "Create, update and delete campaigns",
"campaigns:read": "List and view available campaigns",
"schedule-callbacks:read": "List schedule callbacks",
"schedule-callbacks:write": "schedule a callbacks or reschedule a callbacks",
"po-record-list-automations:write": "Custom record list automations for proactive outbound clients",
"prompts:read": "Read prompts",
"prompts:write": "Create a prompt",
"prompts:delete": "Delete a prompt",
"prompts:download": "Get prompt download link",
"webhooks-trigger:write": "Create, update and delete a webhook trigger",
"cfm-public:write": "Collect feedback data",
"digital-connect:read": "List and Get digital-connect Resources",
"digital-connect:write": "Create, Update and Delete digital-connect Resources",
"entitymapper-contact-interactions:write": "Update interaction's contact mappings",
"locations-directory:read": "Read locations information",
"locations-directory:write": "Write/update locations information and custom fields",
"locations-directory:support": "Create/Update/Delete locations-directory support features",
"staffs-directory:read": "Read staffs information",
"staffs-directory:write": "Write/update staffs information",
"automated-notifications-management:read": "Read Automated Notifications related account information",
"automated-notifications-management:write": "Write Automated Notifications related account information",
"automated-notifications:read": "Read Automated Notifications event information",
"automated-notifications:write": "Write Automated Notifications event information",
"automated-notifications-bridge:write": "Write permissions for automated-notifications-bridge webhooks",
"automated-notifications-subscriptions:read": "Read Automated Notifications subscriptions related to a topic/channel",
"automated-notifications-subscriptions:write": "Write (subscribe/unsubscribe) Automated Notifications subscriptions related to a topic/channel",
"entitymapper-map:write": "Write mappings with external entities",
"entitymapper-contacts:read": "Search Talkdesk contact",
"entitymapper-contacts:write": "Write Talkdesk contact",
"appointment-scheduling-va:read": "Read appointment scheduling va entries",
"hls-coverage:read": "Read healthcare & life sciences coverage information",
"hls-balance:read": "Read healthcare & life sciences balance information",
"hls-patient:read": "Read healthcare & life sciences patient information",
"hls-providers:call-answered": "Write healthcare & life sciences call answered information",
"hls-appointment:read": "Read healthcare & life sciences patient appointments",
"hls-medication-order:read": "Read healthcare & life sciences patient medication orders",
"hls-appointment:write": "Write healthcare & life sciences patient appointments",
"hls-contact:write": "Write healthcare & life sciences data into talkdesk contact",
"hls-provider:read": "Read healthcare & life sciences provider appointments",
"hls-phone-action:write": "Write healthcare & life sciences phone action",
"hls-click-to-call:write": "Write healthcare & life sciences click-to-call action",
"hls-epic-outgoing-sms:write": "Trigger outgoing SMS from Epic",
"hls-epic-agent-status-sync:write": "Trigger agent status sync from Epic",
"hls-inbasket-message:write": "Send in-basket message to Epic",
"hls-popup-intent:write": "Save intent of a patient",
"hls-prescription:read": "Read healthcare & life sciences prescription information",
"hls-prescription:write": "Write healthcare & life sciences prescription information",
"hls-encounter:read": "Read healthcare & life sciences patient encounters",
"hls-service-request:read": "Read healthcare & life sciences patient service requests",
"hls-procedure:read": "Read healthcare & life sciences patient procedures",
"hls-payers-connections:read": "Read healthcare & life sciences payers information",
"hls-payers-connections:write": "Write healthcare & life sciences payers information",
"hls-symptom-checker:write": "Symptom checker for patient",
"hls-patient:write": "Write healthcare & life sciences patient information",
"hls-epic:call-answered": "Write healthcare & life sciences call answered information",
"hls-sycurio:integrate": "Integrate with Sycurio platform",
"hls-patient-case:write": "Write healthcare & life sciences patient case information",
"hls-outstanding-order:read": "Read healthcare & life sciences outstanding orders",
"hls-medication-order:write": "Write healthcare & life sciences medication order(request)",
"hls-medication-statement:write": "Write healthcare & life sciences medication statement",
"hls-medication-statement:read": "Read healthcare & life sciences medication statement",
"hls-hl7-events:write": "Write healthcare providers HL7 events",
"erc-ecommerce-connections-orders:write": "Update e-commerce connections orders info",
"erc-ecommerce-connections-customers:read": "Read e-commerce connections customers info",
"erc-ecommerce-connections-customers:write": "Write e-commerce connections customers info",
"erc-ecommerce-connections-orders:read": "Read e-commerce connections orders info",
"erc-ecommerce-connections-products:read": "Read e-commerce connections products info",
"erc-ecommerce-customers:read": "Read e-commerce customers info",
"erc-ecommerce-customers:write": "Write e-commerce customers info",
"erc-ecommerce-return-reasons:read": "Read e-commerce return reasons",
"erc-ecommerce-return:read": "Read e-commerce return info",
"erc-ecommerce-return:write": "Write e-commerce return info",
"erc-ecommerce-cart:write": "Sync e-commerce cart items",
"erc-ecommerce-products:read": "Search e-commerce catalog products",
"erc-ecommerce-orders:read": "Show e-commerce integrations orders info",
"erc-ecommerce-orders:write": "Update e-commerce integrations orders info",
"erc-ecommerce-recall:write": "Write e-commerce recall contacts",
"industries-settings-public:write": "Write industries settings",
"industries-contexts:write": "Create, update, and delete context values",
"fsi-insurance-connections-automated-notifications:write": "Write Automated Notifications event information",
"fsi-insurance-connections-contacts:write": "Sync Talkdesk contacts",
"fsi-insurance-connections-claims:read": "Read claims by id from FSI Insurance",
"fsi-insurance-integrations-policies:read": "Read policies from FSI Insurance",
"fsi-insurance-integrations-accounts:read": "Read accounts from FSI Insurance",
"fsi-insurance-integrations-claims:write": "Write claims from FSI Insurance",
"fsi-insurance-integrations-billing:read": "Read billing info from FSI Insurance",
"fsi-insurance-integrations-claims:read": "Read claims from FSI Insurance",
"fsi-insurance-integrations-contacts:write": "Update contact details from FSI Insurance",
"fsi-insurance-integrations-send-docs:read": "Send document deliveries from FSI Insurance",
"fsi-insurance-integrations-data-back:write": "Write contact event data back to FSI Insurance",
"automated-notifications-interactions:read": "Read Automated Notifications related with interactions",
"industries-scheduler-teams:read": "Read teams from industries-scheduler",
"industries-scheduler-availabilities:read": "Get users availabilities by email",
"industries-scheduler-appointment:write": "Create cancel event on specialist's calendar",
"industries-scheduler-appointment:read": "Read appointments from industries-scheduler",
"industries-messaging-service:write": "Write messages in industries-messaging-service",
"interaction-custom-fields:write": "Allows to populate interaction custom fields",
"user-session-public:end": "Terminate a user session",
"industries-settings-public:read": "Read industries settings",
"industries-contexts:read": "Read context values",
"dialer-integrations-records:read": "Read dialer integrations campaign records",
"scim": "Access SCIM-related routes",
"hls-epic-my-chart-reset-password:write": "Trigger Epic MyChart password reset (Deprecated - use hls-patient-password-reset:write)",
"hls-patient-password-reset:write": "Trigger patient password reset for healthcare portal",
"locations-directory-bulk-operation:write": "Write locations directory data",
"locations-directory-batch-operation:write": "Apply a batch of locations directory create/update/delete operations",
"hls-patient-location:read": "Read loction patient data",
"hls-patient-practice:read": "Read healthcare & life sciences patient practices",
"hls-guarantor:read": "Read guarantor identifiers from providers",
"hls-guarantor-billing:read": "Read guarantor billing summary from providers",
"hls-guarantor-password-reset:write": "Trigger guarantor password reset for healthcare portal",
"hls-patient-billing:read": "Read patient billing details from providers",
"hls-interaction-overrides:write": "Write healthcare & life sciences interaction-specific configuration overrides",
"industries-workflows:read": "Read industries workflow schedules and workflows",
"industries-workflows:write": "Create, update, start, and delete industries workflow schedules and workflows",
"digital-messaging-adapter:write": "Write or update Digital Messaging Adapter data"
}
}
}
}
}
},
"externalDocs": {
"description": "External Documentation",
"url": "https://api-docs.talkdeskapp.com/external_docs"
}
}
```