Phone Number Fields

Liferay DXP 2026.Q3+

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 () and navigate to Control Panel → 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 drop-down menu appears. Select a country. Users enter their number without a country code, and the configured calling code is 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:

Mandatory: Entries without a value are rejected. The Object Admin REST API exposes this option as required.
Accept Unique Values Only: Prevents two entries from storing the same phone number. Set this when adding the field. You can change it while the object definition is a draft, but not after publishing.
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.
Enable Entry Translation: Stores separate phone numbers per language or locale when the object definition enables localization. This option cannot be changed after the object definition is published.

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. The endpoint name is the lowercase plural of the object’s name, and it appears as restContextPath on the object definition. See Custom Object APIs.