Location phone numbers validation rules for format, types, and contact information requirements

Change Detection

CountOfPhoneNumberTypesIncreased

Definition	Severity	API	Sample	Mode
Validate that the count of types in latest submittal is less than or matches the count in the stored record

SuspiciousRemovalOfPhoneNumbers

Definition	Severity	API	Sample	Mode
Validate that phoneNumbers is present when previously submitted

UnexpectedPrimaryPhoneNumberChange

Definition	Severity	API	Sample	Mode
Validate that the primary phoneNumber is unchanged between last version and latest submittal

UnexpectedPhoneNumberTypeChange

Definition	Severity	API	Sample	Mode
Validate that a phoneNumber, unchanged between last version and latest submittal, has the same type

UnexpectedPrimaryPhoneNumberTypeChange

Definition	Severity	API	Sample	Mode
Validate that the Primary Phone Number type is unchanged between last version and latest submittal

Cross-feature

PhoneNumbers_ExpectedRegionSubtagForCountryNotPresent

Preconditions
structuredAddress is present

Definition	Severity	API	Sample	Mode
Validate that at least one (1) Region Subtag is present that corresponds with countryCode in structuredAddress

PhoneNumbers_ExpectedRegionSubtagForDerivedCountryNotPresent

Preconditions
displayPoint is present
mainAddress is not present

Definition	Severity	API	Sample	Mode
Validate that at least one (1) Region Subtag is present that corresponds with a country derived from displayPoint

UnexpectedPhoneNumberFormatForCountryCode

Preconditions
structuredAddress is present

Definition	Severity	API	Sample	Mode
Validate that phoneNumber has expected format for the corresponding Country derived from the countryCode

UnexpectedPhoneNumberFormatForDerivedCountry

Preconditions
displayPoint is present

Definition	Severity	API	Sample	Mode
Validate that phoneNumber has expected format for the corresponding Country derived from the displayPoint

Phone Numbers

CountOfValuesInPhoneNumbersListExceedsThreshold

Definition	Severity	API	Sample	Mode
Validate that the count of phoneNumbers values in a list does not exceed ten (10)

CountryDialingCodeNotAllowedForOrgType

Preconditions
orgId resolves to organization that is location owner

Definition	Severity	API	Sample	Mode
Validate that dialing code does not resolve to China

Example Validation Report

{
  "code": "VALIDATION__CountryDialingCodeNotAllowedForOrgType",
  "severity": "VIOLATION",
  "message": "Country support for your organization type is not available"
}

CountryDialingCodeNotSupported

Definition	Severity	API	Sample	Mode
Validate that a dialing code is associated with a supported country			Link

Example Validation Report

{
  "code": "VALIDATION__CountryDialingCodeNotSupported",
  "severity": "VIOLATION",
  "message": "Support for 'phoneNumber' value '{{value}}' not available",
  "context": {
    "value": "+74959375911"
  },
  "details": {
    "createdDate": "2026-09-01T21:00:59.865Z",
    "submitted": [
      {
        "field": "$.locationDetails.phoneNumbers[0].phoneNumber",
        "value": "+74959375911"
      }
    ],
    "compared": [],
    "expected": []
  }
}

PhoneNumbersListMustNotIncludeNulls

Definition	Severity	API	Sample	Mode
Validate that a list does not include null

PhoneNumbersMustNotBeEmptyArray

Definition	Severity	API	Sample	Mode
Validate that phoneNumbers is not an empty array

Example Validation Report

{
  "code": "VALIDATION__PhoneNumbersMustNotBeEmptyArray",
  "message": "'{{field}}' must be omitted or contain at least one element; empty arrays are not allowed.",
  "severity": "VIOLATION",
  "context": {
    "field": "phoneNumbers"
  },
  "details": {
    "compared": [],
    "expected": [],
    "submitted": [
      {
        "field": "$.locationDetails.phoneNumbers",
        "value": "[]"
      }
    ],
    "createdDate": "2026-03-03T13:58:43.946Z"
  }
}

PhoneNumbersNotPresent

Definition	Severity	API	Sample	Mode
Validate that phoneNumbers (recommended features) are present			Link

Example Validation Report

{
  "code": "VALIDATION__PhoneNumbersNotPresent",
  "severity": "WARNING",
  "message": "New Location does not include phone numbers (recommended)",
  "details": {
    "createdDate": "2026-09-01T21:00:59.865Z",
    "expected": [
      {
        "field": "$.locationDetails.phoneNumbers"
      }
    ],
    "compared": [],
    "submitted": []
  }
}

PhoneNumbersShouldNotBeExclusivelyFax

Definition	Severity	API	Sample	Mode
Validate that not all listed Phone Numbers are exclusively FAX

PhoneNumbersAreaCodesAreDissimilar

Definition	Severity	API	Sample	Mode
Validate that phoneNumber area code prefixes match

PhoneNumbersMustBeDistinct

Definition	Severity	API	Sample	Mode
Validate that each phoneNumber value is distinct

Phone Extension

PhoneNumbersExtMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that phoneExt is not an empty string

PhoneNumberMustNotMatchPhoneExt

Definition	Severity	API	Sample	Mode
Validate that phoneNumber does not match phoneExt

SuspiciousPhoneExtCharacterLength

Definition	Severity	API	Sample	Mode
Validate that phoneExt length does not exceed a maximum value (5)

Primary

AtLeastOnePrimaryPhoneNumberShouldBePresent

Definition	Severity	API	Sample	Mode
Validate that at least one (1) primary phoneNumber is present			Link

MustOnlyHaveOnePrimaryPhoneNumber

Definition	Severity	API	Sample	Mode
Validate that only one (1) primary phoneNumber is present			Link

PhoneNumbersPrimaryMustBePresent

Definition	Severity	API	Sample	Mode
Validate that primary is present			Link

Phone Number

PhoneNumberMustBePresent

Preconditions
phoneNumbers is present

Definition	Severity	API	Sample	Mode
Validate that phoneNumber is present			Link

PhoneNumberMustHaveValidFormat

Definition	Severity	API	Sample	Mode
Validate that phoneNumber formatting is valid

{{reason}}
invalid country calling code
invalid length for region
number length matches local not region
too long for region
too short for region

Example Validation Report

{
  "code": "VALIDATION__PhoneNumberMustHaveValidFormat",
  "message": "Phone Number rejected for reason: '{{reason}}'",
  "severity": "VIOLATION",
  "context": {
    "reason": "too short for region"
  },
  "details": {
    "createdDate": "2026-09-01T21:00:59.865Z",
    "submitted": [
      {
        "field": "$.locationDetails.phoneNumbers[0].phoneNumber",
        "value": "+4479704802"
      }
    ],
    "compared": [],
    "expected": []
  }
}

PhoneNumberMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that phoneNumber is not an empty string

PhoneNumberShouldNotBeExclusivelyTTY

Definition	Severity	API	Sample	Mode
Validate that not all listed Phone Numbers are exclusively TTY

PhoneNumberTypeMustBePresent

Preconditions
phoneNumbers is present

Definition	Severity	API	Sample	Mode
Validate that type is present			Link

PhoneNumberTypeMustBeDistinct

Definition	Severity	API	Sample	Mode
Validate that each type is distinct			Link

PhoneNumberTypeMustBeValid

Definition	Severity	API	Sample	Mode
Validate that type value is valid			Link

PhoneNumberTypeMustNotBeEmpty

Definition	Severity	API	Sample	Mode
Validate that type is not an empty string

UnexpectedMatchAmongPhoneNumbersAndTypes

Definition	Severity	API	Sample	Mode
Validate that Phone Numbers do not unexpectedly match among types: FAX and TTY