Mapping Jira statuses to Jira Align states

Summary

This article explains how to map Jira issue statuses to Jira Align states using the Jira Align REST API. Use this guide when you want Jira status transitions (for example, “To Do” → “In Progress” → “Done”) to automatically update the corresponding state on Jira Align work items.

image of screen to map Jira status to Jira Align state

Jira Status → Jira Align state mappings UI.

Purpose: When a Jira issue status changes, the corresponding Jira Align state is updated.

See the parent page for full mapping details: Mapping States, Process Steps, and Statuses between Align and Jira via API

Solution

Retrieve state mappings

Endpoint: GET /connectors/{connectorId}/mappings/states

Query parameters:

ProjectKey (optional):
- Omit to return company-managed project mappings only.
- Set to a project key to return team-managed project mappings for that project.
WorkItemTypeId (optional): Filter by work item type ID.
$top, $skip, $filter, $orderby: OData query options.

Example request for company-managed project:

GET /align/api/2/Connectors/123/mappings/states?WorkItemTypeId=1Authorization: Bearer {your-api-token}

Example request for team-managed project:

GET /align/api/2/Connectors/123/mappings/states?ProjectKey=PROJ&WorkItemTypeId=1Authorization: Bearer {your-api-token}

Example response:

[
  {
    "id": 1,
    "connectorId": 123,
    "workItemTypeId": 3,
    "jiraStatusId": 10001,
    "jiraStatusName": "To Do",
    "alignStateId": 1,
    "alignStateName": "Ready to Start",
  },
  {
    "id": 2,
    "connectorId": 123,
    "workItemTypeId": 3,
    "jiraStatusId": 10002,
    "jiraStatusName": "In Progress",
    "alignStateId": 2,
    "alignStateName": "In Progress",
  }
]

Retrieve a single state mapping

Retrieve a specific state mapping by ID.

Endpoint: GET /Connectors/{connectorId}/mappings/states/{mappingId}

Example request:

GET /align/api/2/Connectors/123/mappings/states/1Authorization: Bearer {your-api-token}

Create a state mapping

Create a new Jira → Jira Align state mapping.

Endpoint: POST /Connectors/{connectorId}/mappings/states

Request body:

{
  "workItemTypeId": 3,
  "jiraStatusId": 10001,
  "alignStateId": 1,
  "projectKey": "PROJ"  // Required for team-managed projects, omit for company-managed projects
}

Example request for company-managed project:

POST /align/api/2/Connectors/123/mappings/states
Authorization: Bearer {your-api-token}
Content-Type: application/json

{
  "workItemTypeId": 3,
  "jiraStatusId": 10001,
  "alignStateId": 1
}

Example request for team-managed project:

POST /align/api/2/Connectors/123/mappings/states
Authorization: Bearer {your-api-token}
Content-Type: application/json

{
  "workItemTypeId": 3,
  "jiraStatusId": 10001,
  "alignStateId": 1,
  "projectKey": "PROJ"
}

Example response (201 Created):

{
  "id": 1,
  "connectorId": 123,
  "workItemTypeId": 3,
  "jiraStatusId": 10001,
  "jiraStatusName": "To Do",
  "alignStateId": 1,
  "alignStateName": "Ready to Start"
  "projectKey": "PROJ" //returned for Team Managed projects only
}

Update a state mapping

Only the alignStateId field is mutable for Jira → Jira Align state mappings.

Endpoint: PUT /Connectors/{connectorId}/mappings/states/{mappingId}

Request Body:

{
  "alignStateId": 2  // Only mutable field - required
}

Note: The following fields are not mutable and will be ignored if provided:

workItemTypeId
jiraStatusId
projectKey
connectorId
mappingId

Example request:

PUT /align/api/2/Connectors/123/mappings/states/1
Authorization: Bearer {your-api-token}
Content-Type: application/json

{
  "alignStateId": 2
}

Example response:

204 No Content on successDelete State Mapping

Delete a state mapping

Endpoint: DELETE /Connectors/{connectorId}/mappings/states/{mappingId}

Example request:

DELETE /align/api/2/Connectors/123/mappings/states/1
Authorization: Bearer {your-api-token}

Example responses:

204 No Content on success
404 Not Found if mapping doesn't exist

Updated on February 18, 2026

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Atlassian Support

Mapping Jira statuses to Jira Align states

Summary

Solution

Retrieve state mappings

Retrieve a single state mapping

Create a state mapping

Update a state mapping

Delete a state mapping

Still need help?