Phone Number Custom Field

The Phone Number Field custom field stores a single phone number per work item, validates the format on save, and renders it on the issue view as a clickable tel: link. It fits use cases such as service-desk requester records, customer profiles, contact details for sales prospects, and any other workflow where a number captured today should be one tap away from a call tomorrow.

Create the Phone field

1. In Jira, click the Settings (gear) icon in the top-right corner.

2. Select Issues.

3. In the left sidebar, under Fields, click Custom fields.

4. Click Create custom field in the top-right corner.

5. On the "Select a field type" screen, find and pick Phone Number Field. Click Next.

   💡 You'll recognize it by its description: "Stores a single phone number." and the phone icon.

   

6. Name and description:

   • Enter a Name (e.g. "Requester phone", "Sales contact").
   • Add an optional Description.

7. Click Create.

8. Associate to screens: Pick the relevant screens (create, edit, transition, view) and click Update.

The field is now ready to be captured on issues.

Accepted formats

The add-on validates each number on the client (as the user types) and on the server (on save) with the same pattern, so an invalid number cannot slip through the REST API.

The following formats are accepted:

• International (E.164): +51999888777, +1 800 555 0100.
• Local with separators: 999-888-777, (01) 234-5678.
• Reasonable mix of spaces, dots, dashes, and parentheses around the digits.

Constraints:

• Total length between 7 and 20 characters (including the optional leading +).
• Only digits and the visual separators +, space, ., -, (, ).
• The first meaningful character must be a digit or + (no letters, no symbols like & or #).

If the value fails any rule, Jira shows "The value is not a valid phone number." and refuses to save.

Uniform validation, including the REST API

Because final validation runs as a Jira expression on the server, it also applies when an issue is created or edited via the Jira Cloud REST API or external integrations. Invalid numbers cannot bypass browser-side validation by going through a different door.

Entry on the create screen

In the Create issue dialog, the field appears as a plain text input. As the user types, the add-on validates the format after a brief pause. If the value is invalid, an error message shows below the field and the Create button blocks the submit until it is corrected.

Rendering on the issue view

Once saved, the number appears on the issue view next to a mobile icon, rendered as a clickable tel: link. Clicking it opens the user's default phone app (the system dialer on mobile devices; FaceTime, Teams, Skype, etc. on desktops where one is configured).

The link only contains digits (plus an optional leading +): visual separators are stripped when building the href, so the dialer doesn't try to dial them. The number the user sees keeps the separators as they were typed.

Search and JQL support

The field is registered with type: string, which enables JQL's exact-match string operators:

Operator	Supported	Example
=	✅	"Requester phone" = "+51 999 888 777"
!=	✅	"Requester phone" != "+51 000 000 000"
in / not in	✅	"Requester phone" in ("+51 999 888 777", "+51 998 765 432")
is EMPTY / is not EMPTY	✅	"Requester phone" is not EMPTY
~ / !~ (partial)	❌	(not supported by Forge for type: string)

Partial-text search is not available

Partial-match operators (~, !~) are not supported for Forge string custom fields. This is an Atlassian Forge platform limitation, not an add-on issue. For lists of phones use the in (...) operator.

Optional field behaviour

If the field is not marked as required in your project, it can be left blank without error and the issue is saved with no value.