Phone Number Fields

Dev Feature

Phone Number fields store contact numbers with built-in validation and normalization. All values are stored in E.164 format (a + followed by 7–15 digits, for example +15551234567), providing a single consistent representation across forms, APIs, and notifications.

Adding a Phone Number Field

Open the Global Menu (), go to the Control Panel tab, and click Objects.
Click the object definition you want to edit.
Go to the Fields tab and click the Add button ().
Enter a Label and Field Name.
Select Phone Number as the field type.
Enable Mandatory if entries must provide a value.
Click Save.

Note

After saving, click the field in the Fields tab to configure its country source (see Configuring the Country Source below).

Configuring the Country Source

Every Phone Number field requires a country source, which controls how the country calling code is applied to entered values.

In the object definition’s Fields tab, click the Phone Number field to edit it.
Under Country Source, select an option:

Defined by User: Users select their country when entering a phone number. The field accepts numbers from any country.

Fixed: A Country dropdown appears. Select a country. Users enter their number without a country code, and the configured calling code is automatically prepended before storage.
Click Save.

You can update the country source after the object definition is published.

Validation and Storage

Before storing a phone number value, Objects removes all non-digit characters except a leading + and validates the result against E.164 format. Values that don’t match + followed by 7–15 digits are rejected.

For Fixed country source fields, entries without a + prefix receive the configured country calling code before storage. Entries that include a + prefix must start with the configured country’s calling code or they are rejected.

All API responses return values in E.164 format regardless of how the user entered them.

Field Options

Phone Number fields support these standard Object field options:

Required: Entries without a value are rejected.
Accept Unique Values Only: Prevents two entries from storing the same phone number. This option can’t be changed after the field is created.
Default Value: Sets a pre-filled value for new entries. The default value must be a valid phone number in E.164 format. For Fixed fields, the value’s country calling code must match the field’s configured country.
Localization: Stores separate phone numbers per language or locale when the object definition enables localization.

Phone Number fields are also available as variables in Expression Builder and Notification Templates.

Using Phone Number Fields with APIs

When querying an object definition’s fields through the Object Admin REST API, each Phone Number field includes "businessType": "PhoneNumber" in its response. Use this property to distinguish Phone Number fields from standard Text fields programmatically.

When creating or updating entries, pass the phone number as a string. You can use E.164 format directly, or use a local number when the field uses a Fixed country source (the calling code is prepended before storage). In forms, Defined by User fields display a country-code picker alongside a local-number input; the field composes the E.164 value automatically before submission. API calls must supply the full E.164 string directly.

curl -X "POST" "http://localhost:8080/o/c/contactRequests?restrictFields=actions" \
     -H "Content-Type: application/json" \
     -u 'test@liferay.com:learn' \
     -d '{"phoneNumber": "+15551234567"}'

Replace phoneNumber with your field’s configured field name and contactRequests with your object’s API endpoint name.

Capability: