Skip to main content
Version: 1.1.0

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​

When the Phone field is part of the Create, Edit or Transition screen, it appears as a text input ready to accept 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. Type the number in any of the accepted formats:
    • International: +51 999 888 777, +1 800 555 0100.
    • Local: 999-888-777, (01) 234-5678.
  4. Save your changes.

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.

Keep the + and the separators you prefer

The add-on preserves the spaces, dashes, dots and parentheses you use to group digits: 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.

Viewing the number on an issue​

Once saved, the number appears on the issue view as a clickable link preceded by a phone icon. 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 messageCauseHow 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 20 characters in total.

Searching issues by phone number​

You can use JQL to find issues by the exact field value:

"Requester phone" = "+51 999 888 777"
"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 (...).