JiraTeamLens for Jira

How do I set the Jira Team field with the REST API?

By Mortise Apps · 29 October 2026 · 4 min read

To set the Team field on a Jira Cloud work item through the REST API, send an Edit issue request (PUT /rest/api/3/issue/{issueIdOrKey}) with the Team field's custom field id as the key and the team id (a UUID) as the value. The Team field does not accept a team name, and sub-tasks cannot be given their own team: they use the parent's.

Short answer: find the Team field's id (for example customfield_10001, it differs per site), copy the team id from the end of the team's profile URL, then send {"fields": {"customfield_10001": "<team id>"}} in the body of PUT /rest/api/3/issue/ABC-123.

Checked 29 Oct 2026: Atlassian Developer "Team field in Jira REST API" (last updated 15 Sep 2026), the Jira Cloud REST API v3 reference (Issues, Issue fields, Issue search) and the Atlassian knowledge base article on custom field ids, all read 29 Oct 2026. We have not run the requests below on a live site for this article; they follow those pages.

Step 1: find the Team field's custom field id

Atlassian's developer page shows the Team field as customfield_10001 in its examples and notes that the id "may be different in each Jira site". Ways to find yours, from Atlassian's knowledge base article on custom field ids:

• REST API: GET /rest/api/3/field (Get fields) lists every field; look for the one named Team whose schema custom value is com.atlassian.teams:rm-teams-custom-field-team.
• List view, no admin rights needed: search for work that has a team, switch to the list view, add the Team column, sort by it, then switch to advanced JQL. The field id shows in the ORDER BY clause.
• Admin screen: with the Administer Jira permission, go to Settings > Issues > Custom fields, open View field information for Team, and read customFieldId= in the URL.

The field must also be enabled for the site and added to the space's layout before it can be set; see add the Team field to Jira work items.

Step 2: find the team id

The developer page says to open the team's profile page and copy "the last segment in the URL that comes after /team/". It is a long string such as 36885b3c-1bf0-4f85-a357-c5b858c31de4. This same id is what JQL, workflow post functions and the REST API use.

Step 3: send the Edit issue request

PUT /rest/api/3/issue/ABC-123
Content-Type: application/json

{
  "fields": {
    "customfield_10001": "36885b3c-1bf0-4f85-a357-c5b858c31de4"
  }
}

The same fields entry works in a Create issue body. Two details from the reference:

• The Team field's edit metadata lists one operation, set, so you replace the team; there is no add or remove.
• Edit issue has a notifyUsers parameter that defaults to true. If you are back-filling teams on hundreds of old work items, decide whether watchers should get an email for each one.

Sub-tasks take the parent's team

Atlassian's page is explicit: "The Team cannot be changed in subtasks, and will instead use the same Team selected in the parent issue." A script that loops over search results should skip sub-tasks and set the team on the parent instead.

What a read returns

Reading a work item (or search results that include the field) gives an object, not the bare id:

"customfield_10001": {
  "id": "36885b3c-1bf0-4f85-a357-c5b858c31de4",
  "name": "Some Team Name",
  "isVisible": true,
  "title": "Some Team Name",
  "isShared": true
}

So a script that copies a team from one work item to another must send only the id, not the whole object.

Find the work to update, then check it

Search with the issue search API (/rest/api/3/search/jql) and request the Team field's id in fields. The JQL compares by team id and supports =, !=, IS, IS NOT, IN and NOT IN:

project = ABC AND "Team[Team]" is EMPTY AND issuetype not in subTaskIssueTypes()

After the run, the same query should return nothing. We make TeamLens for Jira, which adds the JQL functions noTeam() and teamIn(): the check can read project = ABC AND issue in noTeam(), and a spot check of one team can use its name, issue in teamIn("Platform"), instead of the UUID. Details on the JQL functions page. The plain "Team[Team]" clauses work without the app.

FAQ

Can I send the team's name instead of the id?

No. The developer page describes the value as a Team ID. Look the id up once per team (profile URL) and keep a name-to-id map in your script.

Does the Team field need special endpoints?

No. Atlassian's page says it "can be created, fetched, and updated in the same way as other custom fields", so the normal issue endpoints apply. For a no-code route, Automation can set it from the assignee (guide).

Why does my request fail on a sub-task?

Because sub-tasks follow the parent's team. Set the Team on the parent work item.