Using the Phone field

This guide describes how to work with a Phone Number Field custom field that your administrator has already configured. If you don't see the field on your issue screens yet, check with your Jira administrator: most likely it just needs to be added to the right screen.

Capture a phone number on an issue

As of version 3.1.0, the Phone field presents a structured interface with two inline parts:

1. Country selector (searchable dropdown): lists ~250 countries with their flag, name, and dial code. You can type in the dropdown to filter by country name or code (for example, type "Peru" or "51" to select Peru).
2. Local number field (free text): enter only the local part of the number, without prefixing the country code.

To capture a phone number:

1. Open the create, edit, or transition form.
2. Locate the Phone field (the exact name is set by your administrator, for example "Requester phone").
3. Verify that the country selector shows the correct country. If not, click the dropdown and select the appropriate country.
4. Type the local number in the text field (for example, 943 824 375).
5. Save your changes.

The add-on automatically combines the dial code of the selected country with the local number to store the full value (for example, +51 943 824 375).

Country pre-selected from configuration

The country selector is pre-populated with the country your administrator configured for this field in the current context (project or issue type). In most cases it will match your organisation's country, so you won't need to change it.

Keep the separators you prefer

The add-on preserves the spaces, dashes, dots and parentheses you use to group digits in the local number: the number is displayed exactly the way you typed it. Separators are only stripped when building the clickable link, so the dialer doesn't get confused.

If the value isn't a valid phone number, Jira shows "The value is not a valid phone number." and refuses to save until the format is correct.

Viewing the number on an issue

Once saved, the number appears on the issue view as a clickable link preceded by a phone icon and the country code. The display format is like 📱 PE +51 943 824 375. Clicking it:

• On mobile, opens the dialer directly with the number ready to call.
• On macOS or Windows, opens the default phone app (FaceTime, Teams, Skype, etc.) according to your system configuration.

This makes quick outreach easy without copy-pasting the number.

Common error messages

Error message	Cause	How to fix it
"The value is not a valid phone number."	The text contains characters not allowed, or doesn't meet the minimum/maximum length.	Make sure you only use digits and the separators +, space, ., -, (, ), and that the number is between 7 and 25 characters in total (including the dial code).

Searching issues by phone number

You can use JQL to find issues by the exact field value. As of version 3.1.0 the stored value includes the country dial code, so queries should include it:

"Requester phone" = "+51 943 824 375"

"Requester phone" is not EMPTY

Replace Requester phone with the exact name your administrator gave the field.

Partial-text search is not available

The ~ and !~ operators (partial match) are not supported for this field type on Jira Cloud due to a platform limitation. To find multiple phones, use lists: "Requester phone" in (...).