{"extension": string,// Union field kind can be only one of the following:"e164Number": string,"shortCode": {object (ShortCode)}// End of list of possible types for union field kind.}
Fields
extension
string
The phone number's extension. The extension is not standardized in ITU recommendations, except for being defined as a series of numbers with a maximum length of 40 digits. Other than digits, some other dialing characters such as ',' (indicating a wait) or '#' may be stored here.
Note that no regions currently use extensions with short codes, so this field is normally only set in conjunction with an E.164 number. It is held separately from the E.164 number to allow for short code extensions in the future.
Union field kind. Required. Either a regular number, or a short code. New fields may be added to the oneof below in the future, so clients should ignore phone numbers for which none of the fields they coded against are set. kind can be only one of the following:
e164Number
string
The phone number, represented as a leading plus sign ('+'), followed by a phone number that uses a relaxed ITU E.164 format consisting of the country calling code (1 to 3 digits) and the subscriber number, with no additional spaces or formatting. For example:
correct: "+15552220123"
incorrect: "+1 (555) 222-01234 x123"
The ITU E.164 format limits the latter to 12 digits, but in practice not all countries respect that, so we relax that restriction here. National-only numbers are not allowed.
An object representing a short code, which is a phone number that is typically much shorter than regular phone numbers and can be used to address messages in MMS and SMS systems, as well as for abbreviated dialing (For example "Text 611 to see how many minutes you have remaining on your plan.").
Short codes are restricted to a region and are not internationally dialable, which means the same short code can exist in different regions, with different usage and pricing, even if those regions share the same country calling code (For example: US and CA).
JSON representation
{"regionCode": string,"number": string}
Fields
regionCode
string
Required. The BCP-47 region code of the location where calls to this short code can be made, such as "US" and "BB".
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-07-31 UTC."],[],[],null,["# PhoneNumber\n\n- [JSON representation](#SCHEMA_REPRESENTATION)\n- [ShortCode](#ShortCode)\n - [JSON representation](#ShortCode.SCHEMA_REPRESENTATION)\n\nAn object representing a phone number, suitable as an API wire format.\n\nThis representation:\n\n- should not be used for locale-specific formatting of a phone number, such as \"+1 (650) 253-0000 ext. 123\"\n\n- is not designed for efficient storage\n\n- may not be suitable for dialing - specialized libraries (see references) should be used to parse the number for that purpose\n\nTo do something meaningful with this number, such as format it for various use-cases, convert it to an `i18n.phonenumbers.PhoneNumber` object first.\n\nFor instance, in Java this would be: \n\n com.google.type.PhoneNumber wireProto =\n com.google.type.PhoneNumber.newBuilder().build();\n com.google.i18n.phonenumbers.Phonenumber.PhoneNumber phoneNumber =\n PhoneNumberUtil.getInstance().parse(wireProto.getE164Number(), \"ZZ\");\n if (!wireProto.getExtension().isEmpty()) {\n phoneNumber.setExtension(wireProto.getExtension());\n }\n\nReference(s): - \u003chttps://github.com/google/libphonenumber\u003e\n\n| JSON representation |\n|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"extension\": string, // Union field `kind` can be only one of the following: \"e164Number\": string, \"shortCode\": { object (/merchant/api/reference/rest/Shared.Types/PhoneNumber#ShortCode) } // End of list of possible types for union field `kind`. } ``` |\n\n| Fields ||\n|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `extension` | `string` The phone number's extension. The extension is not standardized in ITU recommendations, except for being defined as a series of numbers with a maximum length of 40 digits. Other than digits, some other dialing characters such as ',' (indicating a wait) or '#' may be stored here. Note that no regions currently use extensions with short codes, so this field is normally only set in conjunction with an E.164 number. It is held separately from the E.164 number to allow for short code extensions in the future. |\n| Union field `kind`. Required. Either a regular number, or a short code. New fields may be added to the oneof below in the future, so clients should ignore phone numbers for which none of the fields they coded against are set. `kind` can be only one of the following: ||\n| `e164Number` | `string` The phone number, represented as a leading plus sign ('+'), followed by a phone number that uses a relaxed ITU E.164 format consisting of the country calling code (1 to 3 digits) and the subscriber number, with no additional spaces or formatting. For example: - correct: \"+15552220123\" - incorrect: \"+1 (555) 222-01234 x123\" The ITU E.164 format limits the latter to 12 digits, but in practice not all countries respect that, so we relax that restriction here. National-only numbers are not allowed. References: - \u003chttps://www.itu.int/rec/T-REC-E.164-201011-I\u003e - \u003chttps://en.wikipedia.org/wiki/E.164\u003e. - \u003chttps://en.wikipedia.org/wiki/List_of_country_calling_codes\u003e |\n| `shortCode` | `object (`[ShortCode](/merchant/api/reference/rest/Shared.Types/PhoneNumber#ShortCode)`)` A short code. Reference(s): - \u003chttps://wikipedia.org/wiki/Short_code\u003e |\n\nShortCode\n---------\n\nAn object representing a short code, which is a phone number that is typically much shorter than regular phone numbers and can be used to address messages in MMS and SMS systems, as well as for abbreviated dialing (For example \"Text 611 to see how many minutes you have remaining on your plan.\").\n\nShort codes are restricted to a region and are not internationally dialable, which means the same short code can exist in different regions, with different usage and pricing, even if those regions share the same country calling code (For example: US and CA).\n\n| JSON representation |\n|----------------------------------------------------|\n| ``` { \"regionCode\": string, \"number\": string } ``` |\n\n| Fields ||\n|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `regionCode` | `string` Required. The BCP-47 region code of the location where calls to this short code can be made, such as \"US\" and \"BB\". Reference(s): - \u003chttp://www.unicode.org/reports/tr35/#unicode_region_subtag\u003e |\n| `number` | `string` Required. The short code digits, without a leading plus ('+') or country calling code. For example \"611\". |"]]