Mapping Jira statuses to Jira Align statuses

Summary

Use this article to map Jira Align states to Jira issue statuses per project via the Jira Align REST API, so state changes in Align automatically update the corresponding Jira status.

image of Jira project screen to map Jira Align state to Jira status

Jira Align State → Jira Status Mappings UI

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

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

Solution

Retrieve project state mappings

Retrieve all Align → Jira state mappings for a specific project.

Endpoint: GET /Connectors/{connectorId}/projects/{projectKey}/mappings/states

Query parameters:

WorkItemTypeId (optional): Filter by work item type ID
$top, $skip, $filter, $orderby (OData query options)

Example request:

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

Example response:

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

Retrieve single project state mapping

Retrieve a specific Align-to-Jira state mapping by ID for a project.

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

Example request:

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

Create a project state mapping

Create a new Align-to-Jira state mapping for a specific project.

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

Request body:

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

Example request:

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

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

Example response (201 Created):

{
  "id": 10,
  "connectorId": 123,
  "projectKey": "PROJ",
  "workItemTypeId": 3,
  "jiraStatusId": 10001,
  "jiraStatusName": "To Do",
  "alignStateId": 1,
  "alignStateName": "Ready to Start"
}

Notes:

You can configure the same Jira status against more than one Align state

Update project state mapping

Update an existing Align-to-Jira state mapping for a project. Only the jiraStatusId field is mutable for Align → Jira state mappings.

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

Request body:

{
  "jiraStatusId": 10002  // Only mutable field - required
}

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

workItemTypeId
alignStateId
projectKey
connectorId
mappingId

Example request:

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

{
  "jiraStatusId": 10002
}

Example response:

204 No Content on success

Delete a project state mapping

Delete an Align-to-Jira state mapping for a project.

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

Example request:

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

Example response:

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 statuses

Summary

Solution

Retrieve project state mappings

Retrieve single project state mapping

Create a project state mapping

Update project state mapping

Delete a project state mapping

Still need help?