Migrate from API 1.0 to API 2.0

API 1.0 will be removed from Jira Align in version 10.130.0, which is scheduled for February 16, 2024. We encourage you to migrate your integrations, queries, and other API calls to API 2.0 soon to prepare for this change. Use the following info to migrate to API 2.0.

On this page:

• Authentication changes
• URL changes
• Endpoint changes
• Headers
• Query parameters
• Payload changes

Authentication changes

API 2.0 requires a different API token that can be found and generated in the user profile menu, below the API v1 token:

URL changes

URL paths change slightly when using API 2.0. For example, consider the Users endpoint:

• API 1.0: https://yoursite.jiraalign.com/api/Users/28
• API 2.0: https://yoursite.jiraalign.com/rest/align/api/2/Users/28

Endpoint changes

Review the table below to see how endpoints are affected between API 1.0 and API 2.0:

Headers

Basic authentication headers are not supported. Review the Authentication changes section above.

Query parameters

API 2.0 supports powerful query capabilities. Refer to the documentation for more info regarding $select, $top, $skip, $orderby, and $filter parameters. If you use existing API 1.0 query parameters, which are endpoint specific, you will need to rewrite your queries to use the generic API 2.0 query parameters.

Payload changes

Please refer to the API 1.0 and API 2.0 documentation to map the attributes of each endpoint.

The collection response format is the most significant change between 1.0 and 2.0:

• API 1.0 returns an object containing an array of entities.

  • {
      "Filter": null,
      "TotalResults": 924,
      "Results": [
        {
          "ID": 1,
          "Name": "Washington DC Area",
          "RegionID": 1,
          "LastModified": "2019-09-22T14:58:44",
          "Image": "DC",
          "ApplyTimeTracking": true
        },
    ...
        {
          "ID": 988,
          "Name": "City 0XW972ZLNPHK9O42AS",
          "RegionID": 1358,
          "LastModified": "2023-12-11T12:39:40.657",
          "Image": null,
          "ApplyTimeTracking": false
        }
     ],
     "Self": "/api/Cities/"
    } 

• API 2.0 returns an array. 

  • [
      {
        "id": 1,
        "name": "Washington DC Area",
        "regionId": 1,
        "lastUpdatedDate": "2019-09-22T14:58:44Z",
        "applyTimeTracking": true,
        "image": "DC",
        "self": "https://environmentname.jiraalign.com/rest/align/api/2/cities/1"
      },
    ...
      {
        "id": 108,
        "name": "City DRHVKDMSHLP8EAG428",
        "regionId": 125,
        "lastUpdatedDate": "2023-11-10T05:31:39Z",
        "applyTimeTracking": false,
        "image": null,
        "self": "https://environmentname.jiraalign.com/rest/align/api/2/cities/108"
    }
    ]

For each entity, payloads present minor differences, most commonly with attribute keys. Compare the payload of GET Users/{id} :

• API 1.0:

  • /api/users/28

  • {
      "User": {
      "ID": 28,
      "Email": "user@automation.test",
      "FirstName": "Automation",
      "LastName": "User",
      "Title": "TAQA",
      "UID": "28",
      "RoleID": 9,
      "ExternalID": "",
      "Locked": false,
      "CreateDate": "2018-05-23T13:51:46Z",
      "EnterpirseHierarchy": 15,
      "CostCenterID": 1,
      "RegionID": 5,
      "CityID": 17,
      "HolidayCalendar": 5,
      "TimeTrackRoles": [],
      "EmployeeClassification": 1,
      "StartDate": "2018-05-23T13:51:46Z",
      "UserStartDate": "2018-05-23",
      "IncludeHours": false,
      "IsComplianceManager": false,
      "IsUserManager": false,
      "Company": "",
      "CompanyID": "",
      "EmployeeID": "",
      "IsTimeTracker": false,
      "LastLoginDate": "2023-09-19T23:43:53Z",
      "Notes": "",
      "LastModified": "2020-07-01T15:33:19Z",
      "HolidayCityID": 17,
      "Teams": [
       {
        "TeamId": 5,
        "Name": "NoCapabilitiesHierarchy.Portfolio.Program1 Team",
        "TeamRole": {
         "TeamRoleId": 12,
         "Name": "Team of Team"
        }
       },
    ...
       {
        "TeamId": 1694,
        "Name": "AUT Test Program GPD91NATB5TH0TGBZG Team",
        "TeamRole": {
         "TeamRoleId": 12,
         "Name": "Team of Team"
        }
      }
     ],
     "TimeZoneId": "E. Europe Standard Time",
     "UserTimeTrackingPermissions": {
      "HasTimeEntryPermission": false,
      "HasTimeApprovalPermission": false
     },
      "Avatar": "data:image/png;base64,R0lG...,
      "Self": "https://environmentname.jiraalign.com/api/users/28"
      }
    }

• API 2.0

  • /rest/align/api/2/users/28

  • {
     "id": 28,
     "uid": "28",
     "firstName": "Automation",
     "lastName": "User",
     "fullName": "Automation User",
     "email": "user@automation.test",
     "userStartDate": "2018-05-23T00:00:00Z",
     "userEndDate": null,
     "isExternal": 0,
     "externalId": null,
     "isLocked": 0,
     "status": "Active",
     "employeeId": "",
     "regionId": 5,
     "title": "TAQA",
     "roleId": 9,
     "cityId": 17,
     "company": null,
     "companyId": null,
     "divisionId": 15,
     "costCenterId": 1,
     "notes": "",
     "timeZone": "E. Europe Standard Time",
     "viewPublicErs": 0,
     "lastLoginDate": "2023-09-19T19:43:53Z",
     "employeeClassification": 1,
     "isTimeTracking": 0,
     "timeTrackingRoles": null,
     "includeHours": 0,
     "holidayRegionId": 5,
     "holidayCityId": 17,
     "isUserManager": 0,
     "managerId": null,
     "timeTrackingStartDate": null,
     "timeApproverId": null,
     "isComplianceManager": 0,
     "createDate": "2018-05-23T09:51:46Z",
     "lastUpdatedDate": null,
     "connectorId": null,
     "userType": null,
     "enterpriseHierarchyId": 15,
     "teams": [
      {
       "teamId": 5,
       "teamName": "NoCapabilitiesHierarchy.Portfolio.Program1 Team",
       "teamType": 2,
       "roleId": 12,
       "roleName": "TeamOfTeam"
      },
    ...
      {
       "teamId": 1694,
       "teamName": "AUT Test Program GPD91NATB5TH0TGBZG Team",
       "teamType": 2,
       "roleId": 12,
       "roleName": "TeamOfTeam"
      }
     ],
     "self": "https://environmentname.jiraalign.com/rest/align/api/2/users/28"
    }