How do issue fields self-identify?

The issue fields returned by GET /rest/api/2/field have both an id and a key. What’s the difference in the purposes of those two attributes?


id is an integer for custom fields like 10123. key is string like customfield_10123. Practically one of them should be enough but I think there is a historical reason for this but I don’t know why.

The key is still required if you use custom fields defined by apps in the descriptor. The key is then appKey_customFieldKeyFromDescriptor.

Using the key in that case is the only way to reference the custom field AFAIK (you should be able to use it to find ID through the endpoint you linked).

That’s what I would have imagined, but it’s not so. Here’s an example of a field returned by the aforementioned REST end-point:

    "id": "customfield_10021",
    "key": "customfield_10021",
    "name": "Rank",

Hi @david.pinn,

Thanks for posing this question. Through observation, my understanding of the semantics are as follows:

Issue ID: An immutable identifier of an issue that is not designed to be human friendly. Issue IDs are positive integers.
Issue Key: A mutable identifier of an issue that is designed to be somewhat human friendly since it follows a standard two part format where the first part is the issue’s current project key and the second part is a sequentially allocated positive integer.

If an issue is moved from one project to another, its key will change, but its ID will not.

I should point out that the above semantics are just based on my observations. To ensure we get a more reliable understanding, I’ve created ACJIRA-2303 to request the semantics be documented properly.


1 Like

Thanks for your response, Dugald. I always like your contributions because they usually come with some kind of action, as in this case. This question, though, is about issue field IDs and keys, not issue IDs and keys.


I believe that issue keys are values that survive export/import operations, whereas the ID values are assigned during import. That might be the case with issue fields too, but there’s nothing about them to indicate that. Unlike issue keys, issue field keys are both string values, and with the exception of issue fields created by apps, they exactly the same values as the corresponding ID values.


For our app, I’d like to store references in our database to various issue fields. For that purpose, I want to use the most persistent, most stable, identifying attribute. Not sure which attribute that is.

1 Like

Just as extra information. I have just checked that Jira Server does not return “key” field. It only returns “id” field in the form of “custom field_10021”. Although both returns the same information, I think “key” should be preffered over “id” since it is newer.

key is a human friendly identifier, assigned to fields created by apps. Its purpose is for the apps to not have to find out what ID was created for their field on each tenant, but instead have the same identifier across all tenants. It is supposed to make interacting with such fields easier. id is created automatically based on an auto-incrementing sequence, meaning the same field has different IDs on different tenants. Fields that do not have unique keys (in practice, any field provided by Jira itself), have keys equal to IDs.


@kkercz Is there by any chance a way to add that key to issue details provided by Jira while creating/updating one?

We’ve created a custom field with options and allowed user to select one, but when /issue-created endpoint is called, we only receive custom field id, so we need to store that id in our db for each client anyway. Adding the key to data would make things much easier :slight_smile:

1 Like

No, I’m afraid that’s not possible. But it sounds like a reasonable feature request, I would suggest creating a ticket for it in the ACJIRA project.