Skip to content

Rich phone number

Preview

This feature is not subject to our service terms. Pre-GA features are available as is and might have limited support.

The intelligence and syntax components of a phone number. For some job types, your application is required to provide a phone number, or it is recommended to add one or more phone numbers because it may increase accuracy and coverage. There are also job types where Modigie may append phone numbers or you request the verification of a mobile phone number.

Schema

The job's payload.phoneNumbers property is an array of type RichPhoneV2.

A RichPhoneV2 object has properties as described below:

phoneNumber: ItuPhoneV2

The syntax components of a phone number. See ItuPhoneV2 for more details. The userFormat property is required, and all other properties are read-only.

See Phone number.

compliance: Compliance read-only

Contains compliance information related to the phone number. Requires a subscription with the corresponding features.

See Compliance below.

phoneType: string read-only

Indicates whether a phone number is wireless, landline, or VoIP.

  • "mobile" A mobile phone number.
  • "landline" A landline phone number.
  • "voip" A Voice over IP number.
  • "unknown" Inconclusive signals about the phone type.
smsEmailAddresses: List of RichEmailAddressV2 read-only

List of SMS email addresses that may be used to send an email as an SMS to this phone number. This information is provided on a best effort basis.

See SMS email address

callWindows: CallWindowV2 read-only

List of best time slots to call this phone number.

See Call windows

rels: List of string optional

Presumable relationship of this phone number.

  • "business" Phone number of a person in relation to a business.
  • "personal" Private phone number of a person.
  • "other" Phone number with any other or unknown relation to the person.
source: JobV2Source optional
The source of this RichPhoneV2 object. See Source of an attribute for more details.

Examples

Application provides a business phone number

Tip

U.S. numbers may also be provided as (XXX) YYY-ZZZZ without the ITU country code as prefix and no separate ituCountryCode property and none of the ISO country property. If the country is omitted, the Modigie Job Engine attempts to infer the country from the convention used in the number format (defaulting to the U.S.). For numbers of other countries, the increased ambiguity may reduce coverage and accuracy significantly.

Later on this page are examples of unambigious requests.

job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "(202) 555-0100"
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

Modigie performs syntax validation on every phone number provided by your application.

In many use cases, your application would test that isPossible=true and isValid=true.

The latter indicates whether the phone number is valid and can be used.

job-response.json
{
  "payload": {
    "phoneNumbers": [
      {
        "callWindows": [],
        "rating": {
          "score": 89,
          "scoreMax": 100,
          "numberActivity": {
            "code": "high",
            "score": 89
          },
          "numberNameMatch": {
            "code": "high",
            "score": 89
          }
        },
        "phoneType": "mobile",
        "compliance": null,
        "smsEmailAddresses": [],
        "phoneNumber": {
          "userFormat": "(202) 555-0100",
          "isPossible": true,
          "isValid": true,
          "intlFormat": "+1 202-555-0100",
          "natlFormat": "(202) 555-0100",
          "country": {
            "officialName": "United States of America",
            "num3": "840",
            "alpha3": "USA",
            "title": "United States",
            "alpha2": "US"
          },
          "e164Format": "+12025550100",
          "ituCountryCode": 1
        },
        "rels": [
          "business",
          "private"
        ],
        "source": {
          "objectSystem": null,
          "objectType": null,
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

Application provides an invalid phone number

job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "+1 800 11"
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

Because the phone number is not valid, Modigie removed the business relationship and reject the job request if a valid phone number is required.

If a phone number is invalid, no intelligence is available.

job-response.json
{
  "callWindows": [],
  "compliance": null,
  "phoneNumber": {
    "country": null,
    "e164Format": null,
    "intlFormat": null,
    "isPossible": false,
    "isValid": false,
    "ituCountryCode": null,
    "natlFormat": null,
    "userFormat": "+1 800 11"
  },
  "phoneType": null,
  "rating": null,
  "rels": [],
  "smsEmailAddresses": [],
  "source": {
    ...
  }
}

Phone number

Syntax components of a phone number in different formats, compatible to the standard ITU-T E.164.

Schema of ItuPhoneV2

A RichPhoneV2's phoneNumber property is of type ItuPhoneV2.

userFormat: string

Phone number in arbitrary format as provided by user.

Example: "(234) 567-8901"

Note

Please be aware that this format may vary between phone numbers. If you need a format for programmatic purposes, please consider using the field e164Format.

e164Format: string read-only

Phone number in ITU.T E.164 standard format.

This format has only digits, and the plus ("+") prefix. This is the only number format that a caller in any country can dial, no matter which country the number belongs to. Most suitable for machines and programmatic processing, often used in context by automated dialers, mobile phones etc.

Example: "+18091234560"

intlFormat: string read-only

Phone number in international format following conventions that are used in the country the number belongs to, e.g. "+49 30 1234560" (Germany), or "+1 809-123-4560" (United States).

Note

Please be aware that this format may vary between phone numbers. If you need a format for programmatic purposes, please consider using the field e164Format.

natlFormat: string read-only

Phone number in national format following conventions that are used in the country the number belongs to, e.g. "(030) 1234560" (Germany), or "+1 809-123-4560" (United States).

Note

Please be aware that this format may vary between phone numbers. If you need a format for programmatic purposes, please consider using the field e164Format.

country: CountryV2 read-only

The country this phone number belongs to.

Represents a country in context of Modigie APIs which is based on the ISO 3166-1 standard.

In requests, it is required to provide alpha2, alpha3, or title. code will produce the best experience.

See CountryV2

ituCountryCode: integer read-only
International prefix of the country this number belongs to, e.g. 1 for US (or any member of NANP), 49 for Germany.
isPossible: boolean read-only

Is true if phone number is possible (e.g. it has the right number of digits), but not necessearily valid (e.g. it's in an assigned exchange).

"+120012301" is not possible, because too few digits for numbers of the North American Number Plan (NANP).

isValid: boolean read-only

Is true if the phone number is possible (e.g. it has the right number of digits) and valid (e.g. it's in an assigned exchange).

"+120012301" is not valid, because numbering plan area 200 does not exist in the North American Numbering Plan (NANP).

Examples of ItuPhoneV2

Provide phone numbers without ambiguity

Tip

Eliminate any ambiguity and provide your numbers either in E.164 format, or attach one of the ISO 3166-1 country codes to the number. A phone number in the format (XXX) YYY-ZZZZ will be typically interpreted as a U.S. number if the country was omitted.

All of the following request examples with an ambiguous input are interpreted as phone numbers in the North American Numbering Plan (NANP) as far as they are possible and valid in the NANP.

phoneNumber.userFormat = "(720) 767-1234"
A number of 10 digits, formatted in NANP convention, will be interpreted as NANP number: +17207671234
phoneNumber.userFormat = "17207671234"
A number of 11 digits, without non-digit characters, starting with 1, will be interpreted as NANP number: +17207671234
phoneNumber.userFormat = "1 (720) 767-1234"
A number of 11 digits, formatted in NANP convention, prefixed with 1, will be interpreted as NANP number: +17207671234
phoneNumber.userFormat = "7207671234"
A number of 10 digits, without non-digit characters, will be interpreted as NANP number: +17207671234

In some situations, this opinionatedness may lead to wrong interpretations if you provide a phone number without any country indication and it matches one of the previous patterns and is a valid number in the NANP.

phoneNumber.userFormat = "2073238000"
This number is actually of the British Museum in London, Great Britain, (20) 7323 8000, but presented without any non-digit characters and no country indicators. As (207) 323-8000 would also be a possible and valid number in the NANP, it is incorrectly interpreted as a NANP number instead of a GB number: 2073238000.

Danger

For every phone number, your application should choose only one of the following options to provide the country part of a phone number. Your application MUST NOT combine these options or the syntax validation may fail!

Include country prefix in the userFormat

If you don't provide a separate ituCountryCode or one of the country codes, you may provide the userFormat with the ITU prefix + and ITU country code to eliminate ambiguity like in the following examples:

phoneNumber.userFormat = "+1 (720) 767-1234"
Because of the +1 prefix the number will be read as a number in the NANP.
phoneNumber.userFormat = "+44 (20) 7323 8000"
Because of the +44 prefix the number will be read as a number in Great Britain.
phoneNumber.userFormat = "+17207671234"
Provide the E.164 format as the userFormat will also eliminate any ambiguity.
job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "+1 (202) 555-0100"
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

You can provide the ITU country code without the + symbol if it's a U.S. number.

Warning

This approach is only applicable to phone numbers of the North American Numbering Plan (NANP), i.e. all phone numbers of the ITU country code 1 such as United States or Canada.

job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "1 (202) 555-0100"
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

Provide the country with ituCountryCode

job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "(202) 555-0100",
          "ituCountryCode": 1
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

Provide the country with country

Danger

Your application should provide only one of the country properties and never combine with ituCountryCode or also prefix the userFormat value with the ITU country code!

job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "(202) 555-0100",
          "country": {
            "alpha2": "US"
          }
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}
job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "(202) 555-0100",
          "country": {
            "alpha3": "USA"
          }
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}
job-request.json
{
  "payload": {
    "phoneNumbers": [
      {
        "phoneNumber": {
          "userFormat": "(202) 555-0100",
          "country": {
            "num3": "840"
          }
        },
        "rels": [
          "business"
        ],
        "source": {
          "objectId": "personA",
          "propertyName": "phone__c"
        }
      }
    ],
    ...
  },
  ...
}

Schema: RichPhoneV2

Compliance

Contains compliance information related to the phone number. Requires a subscription with the corresponding features.

While regulatoryStatus is cumulative over all supported regulations, some clients may need to differentiate between specific regulations, e.g. processing them differently.

Schema of Compliance

A RichPhoneV2.compliance property has properties as described below:

regulatoryStatus: RichPhoneV2_compliance_regulatoryStatus

An aggregated indicator as umbrella over all compliance related information currently supported and covered by the subscription.

This cumulative data point is useful, if a client doesn't want to handle the specific regulations differently, typically to keep the application logic simple.

restricted: string

Indicates there may be any compliance regulation to consider for the phone number.

  • "no" If there is no restriction for any of the supported compliance regulations covered by the subscription. Modigie Engage service does not know of any restriction applicable to the phone number with regards to the covered regulations. Outside the scope of this feature, other regulations may still apply.
  • "yes" If there is a restriction for any of the supported compliance regulations covered by the subscription. With regards to the phone number the client MUST processes it defensively, that is as if the use would be restricted by all supported regulations.
  • "unknown" If any supported regulation shows "unknown", but none of them show "yes". With regards to the phone number the client SHOULD processes it defensively, that is as if the use would be restricted by all supported regulations.
lastCheckTime: string (date-time)
The timestamp when Modigie Engage service looked up the compliance information. It shows the oldest timestamp of all supported regulations.
regulations: RichPhoneV2_compliance_regulations

If the repository of your application is not subscribed to a feature, the corresponding regulation is nullified (null).

doNotCallOrTcpa

National Do Not Call Registry of the United States, managed by the Federal Trade Commission (FTC) or TCPA litigator removal.

This regulation applies to the United States only.

us

National Do Not Call Registry of the United States, managed by the Federal Trade Commission (FTC) or TCPA litigator removal.

      This regulation applies to the United States only.
restricted: string

Indicates if there may be restrictions for the phone number with regards to this regulation.

  • "no" Modigie Engage service does not know of any restriction applicable to the phone number with regards to this regulations. Outside the scope of this feature, other regulations may still apply.
  • "yes" With regards to this phone number the client MUST processes it compliant to this regulation.
  • "unknown" Modigie Engage service was not able to lookup the compliance information for the phone number with regards to this regulation. With regards to this phone number the client SHOULD processes it defensively, that is as if the use would be restricted by this regulation.
lastCheckTime: string (date-time)

The timestamp when Modigie Engage service looked up the compliance information for this regulation.

The timestamp will also be present if the lookup failed or for other reasons shows "unknown".

If a lookup is repeated later it will show a greater timestamp value here.

Examples of Compliance

Your application can parse the property regulatoryStatus.restricted to learn if there may be any regulatory restriction.

Inside the regulations object there may be more detailed compliance information.

job-response.json
{
  "payload": {
    "phoneNumbers": [
      {
        "compliance": {
          "regulations": {
            "doNotCallOrTcpa": {
              "us": {
                "lastCheckTime": "2025-04-18T19:25:37.290329Z",
                "restricted": "yes"
              }
            }
          },
          "regulatoryStatus": {
            "lastCheckTime": "2025-04-18T19:25:37.290329Z",
            "restricted": "yes"
          }
        },
        ...
      }
    ],
    ...
  },
  ...
}

For this phone number no individual regulatory restriction has been found.

job-response.json
{
  "payload": {
    "phoneNumbers": [
      {
        "compliance": {
          "regulations": {
            "doNotCallOrTcpa": {
              "us": {
                "lastCheckTime": "2025-04-18T19:25:37.290329Z",
                "restricted": "no"
              }
            }
          },
          "regulatoryStatus": {
            "lastCheckTime": "2025-04-18T19:25:37.290329Z",
            "restricted": "no"
          }
        },
        ...
      }
    ],
    ...
  },
  ...
}

For this phone number the compliance lookups could not be completed.

Your application SHOULD processes it defensively, that is as if the use would be restricted by this regulation.

job-response.json
{
  "payload": {
    "phoneNumbers": [
      {
        "compliance": {
          "regulations": {
            "doNotCallOrTcpa": {
              "us": {
                "lastCheckTime": "2025-04-18T19:25:37.290329Z",
                "restricted": "unknown"
              }
            }
          },
          "regulatoryStatus": {
            "lastCheckTime": "2025-04-18T19:25:37.290329Z",
            "restricted": "unknown"
          }
        },
        ...
      }
    ],
    ...
  },
  ...
}

Rating

Valid and possible mobile phone number may have a rating that indicates how good the number is.

Schema of Rating

A RichPhoneV2.rating property has properties as described below:

score: integer

Indicates confidence in this phone number to be an active number in service and that the given person can be reached under this number.

The value can range from 0 (no confidence) to 100 (very high confidence).

The score will be 0 if this is not a mobile or VoIP number.

A phone number with a score of 70 or greater is considered to be a good mobile phone number. A phone number with a score of 69 or less is considered to be a bad number.

numberActivity:

Indicates if the number is in service and active.

score: integer
The score that represents the number activity with a value between 0 (no activity) and 100 (high activity)
code: string

The code that represents the number activity:

  • "high": Phone number shows high activity.
  • "medium": Phone number shows medium activity.
  • "low": Phone number shows low activity.
  • "inactive": Phone numbers shows no or very low activity. May be discontinued.
  • "unknown": No information available to indicate activity of this mobile or VoIP number.
  • "unqualified": Phone number does not qualify for activity indicator, i.e. it is not a mobile or VoIP number.
numberNameMatch

Indicates if the subscriber of the number is matching the name of the given person.

score: integer
The score that represents the number name match with a value between 0 (no match) and 100 (strong match)
code: string

The code that represents the number name match:

  • "high": Subscriber name of this phone number shows high match the expected name.
  • "medium": Subscriber name of this phone number shows medium match the expected name.
  • "low": Subscriber name of this phone number shows low match the expected name.
  • "mismatch": Subscriber name of this phone number doesn't match the expected name.
  • "unknown": No information available to indicate activity of this mobile or VoIP number.
  • "unqualified": Phone number does not qualify for activity indicator, i.e. it is not a mobile or VoIP number.

Examples of Rating

Your application can parse the property rating.score to learn if the phone number is a good mobile number belonging to the given person.

This example shows a rating.score >= 70 which indicates good mobile number.

job-response.json
{
  "payload": {
    "phoneNumbers": [
      {
        "rating": {
          "score": 89,
          "scoreMax": 100,
          "numberActivity": {
            "code": "high",
            "score": 89
          },
          "numberNameMatch": {
            "code": "high",
            "score": 89
          }
        },
        ...
      }
    ],
    ...
  },
  ...
}

This example shows a rating.score < 70 which indicates bad mobile number.

job-response.json
{
  "payload": {
    "phoneNumbers": [
      {
        "rating": {
          "numberActivity": {
            "code": "inactive",
            "score": 0
          },
          "numberNameMatch": {
            "code": "low",
            "score": 57
          },
          "score": 23,
          "scoreMax": 100
        },
        ...
      }
    ],
    ...
  },
  ...
}

Call windows

The callWindows list indicates the best time slots to call a phone number.

Schema of CallWindowV2

A RichPhoneV2.callWindows is a list of CallWindowV2 objects. A CallWindowV2 has properties as described below:

title: string

The day or average throughout the week.

  • "Overall"
  • "Monday"
  • "Tuesday"
  • "Wednesday"
  • "Thursday"
  • "Friday"
  • "Saturday"
  • "Sunday"
code: string

Programmatic indicator of best time window to call

  • "00...02" The time slot between 12 am and 2 am
  • "02...04" The time slot between 2 am and 4 am
  • "04...06" The time slot between 4 am and 6 am
  • "06...08" The time slot between 6 am and 8 am
  • "08...10" The time slot between 8 am and 10 am
  • "10...12" The time slot between 10 am and 12 pm
  • "12...14" The time slot between 12 pm and 2 pm
  • "14...16" The time slot between 2 pm and 4 pm
  • "16...18" The time slot between 4 pm and 6 pm
  • "18...20" The time slot between 6 pm and 8 pm
  • "20...22" The time slot between 8 pm and 10 pm
  • "22...00" The time slot between 10 pm and 12 am
clock12Format: string
12 hours AM/PM representation of the call window
clock24Format: string
24 hours representation of the call window
timezone: string
Name of timezone in which call windows are shown
offset: string
Offset of the timezone to UTC.

Example of CallWindowV2

This example shows the best time to call this phone for certain weekdays.

job-response.json
{
  "payload": {
    "callWindows": [
      {
        "title": "Overall",
        "code": "22...00",
        "clock12Format": "10pm - 12am",
        "clock24Format": "22:00 - 00:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Monday",
        "code": "22...00",
        "clock12Format": "10pm - 12am",
        "clock24Format": "22:00 - 00:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Tuesday",
        "code": "18...20",
        "clock12Format": "6pm - 8pm",
        "clock24Format": "18:00 - 20:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Wednesday",
        "code": "22...00",
        "clock12Format": "10pm - 12am",
        "clock24Format": "22:00 - 00:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Thursday",
        "code": "18...20",
        "clock12Format": "6pm - 8pm",
        "clock24Format": "18:00 - 20:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Friday",
        "code": "00...02",
        "clock12Format": "12am - 2am",
        "clock24Format": "00:00 - 02:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Saturday",
        "code": "00...02",
        "clock12Format": "12am - 2am",
        "clock24Format": "00:00 - 02:00",
        "timezone": "UTC",
        "offset": "+00:00"
      },
      {
        "title": "Sunday",
        "code": "02...04",
        "clock12Format": "2am - 4am",
        "clock24Format": "02:00 - 04:00",
        "timezone": "UTC",
        "offset": "+00:00"
      }
    ],
    ...
  },
  ...
}

SMS email address

Example of RichEmailAddressV2

An SMS email address that may be used to send an email as an SMS to this phone number. This information is provided on a best effort basis.

job-response.json
{
  "payload": {
      "smsEmailAddresses": [
        {
          "emailAddress": {
            "isDeliverable": true,
            "isSyntaxValid": true,
            "normalFormat": "12025550100@vtext.com",
            "rfc882Format": "12025550100@vtext.com",
            "userFormat": "12025550100@vtext.com"
          },
          "origin": null,
          "rels": [
            "sms"
          ]
        }
      ],
    ...
  },
  ...
}