Picking the right fieldKey in /rest/api/2/field/{fieldKey}/option

Hi there,

I’ve scoured the internet and this forum and I am at a loss so hoping someone here can help. I’ve tried creating a single select custom field - both manually in the UI and through the API. For example, in the API, I call:

POST https://oururl/rest/api/2/field/
with the following body

	"name": "Client Site",
	"description": "Some description",
	"type": "com.atlassian.jira.plugin.system.customfieldtypes:select",
	"searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher"

And I get back a success;

    "id": "customfield_10123",
    "key": "customfield_10123",
    "name": "Client Site",
    "custom": true,
    "orderable": true,
    "navigable": true,
    "searchable": true,
    "clauseNames": [
        "Client Site"
    "schema": {
        "type": "option",
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
        "customId": 10123

However, now that I have this field (and I can see it in the UI), literally all other field-related calls fail.
For example, I’d like to add an option to it like so:
POST https://oururl/rest/api/2/field/fieldKey/option
with the following body

	"value": "Test Option"

and I’ve tried all of the following (trying to follow both documentation and suggestions online):


and a lot of other combinations. And for all of them, I get one of two errors. Either

    "errorMessages": [],
    "errors": {
        "fieldKey": "Field key 'whateverKeyITried' is not valid"


    "errorMessages": [
        "The field with the given key does not exist or does not support options"
    "errors": {}

And I just don’t understand… Can anyone help?

1 Like

Hi, @igor. Upon further digging, it seems that this is only possible via the add-on that created the custom field (see this suggestion).

Hope this helps.


@iragudo - I saw that suggestion before I posted it. Here’s my problem with it. It seems to me that a select custom field is provided by the “Custom Field Types & Searchers” plugin that you can see in the Manage add-ons page if you select “All add-ons”. In this plugin, you can see a module for “Select List (single choice)” and the plugin’s add-on key is com.atlassian.jira.plugin.system.customfieldtypes.

Whether I make the custom field in the UI or via the API, it’s “provided” by that add-on.

So according to the documentation, I should be able to see the options if I refer to my custom field properly. In the documentation, it says,

The fields can be referenced in the REST API by a field key with the format: $(add-on-key)__$(field-key).

So the add-on-key should be com.atlassian.jira.plugin.system.customfieldtypes and the field-key should be customfield_10123 and the following should work:


But it doesn’t. I suspect that this really does work if you refer to the field properly. Maybe we can get an Atlassian developer to just weigh in here?



There is a demo project linked in docs you read so it might be helpful to look at it.
Also, add-on-key must be yours addon-key, not some module plugin from atlassian plugin, because i can get my options from my CF :slight_smile:
But mostly i recommend checking demo project, i think it will make things clearer.
I can’t help more because for me there is not enough info on your problem rly. What langauage are you using, any official framework, where you invoking call: client/server, how you do it etc etc.

1 Like

@alexter_pr - thanks for the response. I saw the demo project as well. What I am trying to do is much simpler (I think). It’s not language or framework specific. Let’s keep it simple - I want to use Postman or curl to either see the available options on some Select or to add an option to some Select custom field. In a Jira Cloud instance. That’s it. Language-independent, no add-ons, plugins, etc. And I truly think that the only problem I’m having is that either I am specifying the fieldKey incorrectly because the documentation is not clear or it’s not possible to do this at all outside of an add-in (which seems unlikely for something as simple as a Select field).


1 Like

Specifically, see here in the demo project - https://bitbucket.org/atlassianlabs/jira-issue-field-demo/src/b34a29be83e0019233212fc14b8cfe7d12c21ba2/routes/sync.js?at=master&fileviewer=file-view-default#sync.js-5 - they’re using teams-add-on__team-issue-field as the fieldKey. There has to be a way to reference a field made outside of a custom add-on… I’m just finding it hard to believe otherwise.

1 Like

Hi @igor,

I am a product manager on the Jira Cloud team and I worked on this feature. @alexter_pr is correct – this API is only for managing the options for Issue Fields defined by Atlassian Connect apps. The field must be defined in your apps Atlassian Connect app descriptor, and the key must be the key of the app. You can see the app key and definition of the issue field in the descriptor of the demo project that Alexey linked. The key is teams-add-on and the relevant section of the descriptor is

"jiraIssueFields": [
                "key" : "team-issue-field",
                "name" : {
                    "value" : "Team"
                "description" : {
                    "value" : "Team tied to issue"
                "type": "single_select",
                "extractions": [{
                    "path": "category",
                    "type": "string",
                    "name": "category"

There is no public API for managing the options of a regular custom field, only for Issue Fields defined by apps that have been installed in the site. Apologies for the confusion.


Thanks for the quick response @dmeyer. That is unfortunate. Short of making my own add-in which seems like such an overkill for such a simple use case, is there a recommended approach you’ve seen people take when they want to sync a dropdown field with an external source without manually updating it? Maybe an approach that’s not a dropdown?

Basically, I have an external database with, let’s say, widgets. When I add a widget to it, I wanted to call the Jira API and update the options in a select field to add the widget so I can reference it on an issue. The only alternative I am picturing is making a Widget project or issue type and simply creating a Widget issue every time. But then if I want to link it on a different case, I can only do so through issue links and I had wanted a simple field…

Thanks again,


1 Like

Yes, I am in the exact same situation. You’re documentation does not specify this clearly (if at all). Additionally, the error message received back from the API is misleading. You need to review the solution you have coded - you have wasted the time of other developers / customers. Additionally, you have specified above that it is not possible to achieve updating options lists via the API unless via an AddOn. However, you have not stated why nor attempted to provide a workaround and help the customer. Pretty poor service.


I have the same situation.
Maybe, you should integrate that

1 Like

@dmeyer, beyond the demo that was mentioned above, are there any other Atlassian Connect demos that can be shared? I’m looking for one in PHP, specifically Laravel, that I could use as a starting point.

@igor, what did you end up doing?

My use case is to setup Client as a custom field. Then, populate and keep in sync the options with the list of clients in our billing system. I’m happy to write the API calls. I don’t have enough experience with the Atlassian Connect apps yet to know where to start.

1 Like

Is the any update? I need to sync Client custom field with SalesForce too. Could @dmeyer you provide instruction how to do it


If you know the project and issue type for the issue you plan to create, you can make a request to https://developer.atlassian.com/cloud/jira/platform/rest/#api-api-2-issue-createmeta-get with the expand=projects.issuetypes.fields query parameter to get the available options for the custom field you’re interested in.

Thank you @dmeyer. And how to update a custom field’s options then? I need to add new options to the Client custom field

Hi @alexey,

It’s not currently possible to add new options to custom fields via the REST API. This is why we created Issue Fields for Atlassian Connect apps.

You should consider modifying the endpoint /rest/api/2/field because this one returns all my customfields. With that response, the normal API REST behavior would be the possibility to modify the content of the result by using POST or PUT /rest/api/2/field/customfield_00000/option
In case it is not possible to modify custom fields, then the GET from /rest/api/2/field should only show the Issue Fields.

As many of the devs/customers mentioned here, the documentation and the API design, for this particular use case, is poor and made us waste time.


The documentation on this is absolutely terrible. Not being able to update a custom field’s options with an API endpoint even though the documentation would lead you to believe you could is, well, incomprehensible. Please either add the ability or fix your horrid documentation.


This is a show stopper for us. Is there anyone managing hundreds of clients/customers in Jira? We were planning on creating a custom select field populated from the customer list in our CRM which would allow us to tie our various systems together - similar to how @igor was planning on pulling from his billing database. We are also using Zendesk and have the Zendesk “organization” being populated from our CRM. Is there any way to feed such data into Jira and provide our users with a constrained set of options in a dropdown menu? That is, short of implementing the more complicated Connect app which is out of scope for a small shop such as ours.

Not having this feature is causing issues for us again. Is there any update. Such a simple and logical feature. If it is not going to be done, I need the following:

  • Why it won’t be done?
  • What is the recommended workaround to add and update and existing select list in Jira via the rest api?

Hi everyone,

There is currently no API to manage custom field options, and we also don’t have any immediate plans to add it. That being said, I created an ACJIRA issue with this feature request that you can watch and vote for. It will help us evaluate interest and potential value.

You can find it here: https://ecosystem.atlassian.net/browse/ACJIRA-1626

Best regards