Get a List of Recognitions

You can retrieve a list of recognitions that have been sent to or received from an employee by calling the /recognitions endpoint with the employee's username or userId. These recognitions can then be displayed on a profile page or a dashboard within another application. You can also use a collection of recognitions for analysis, such as viewing patterns in sending and receiving or identifying themes across sent recognitions.

Step 1

Obtain a system access token through our 1-step client_credentials OAuth 2.0 flow.

📘
For more information about authentication, see Authentication.

Step 2

Retrieve the employee's user information, including username and userId, by using your access token to make a GET request to the /users endpoint. You can search for the employee by first name, last name or email address.

{
  "paging": {
    "totalItems": 2,
    "totalPages": 1,
    "page": 1,
    "pageSize": 25,
    "self": "http://example.uat.achievers.com/api/v5/users",
    "first": "http://example.uat.achievers.com/api/v5/users?page=1",
    "last": "http://example.uat.achievers.com/api/v5/users?page=1"
  },
  "items": [
    {
      "id": 10726811,
      "firstName": "Adele",
      "lastName": "Olson",
      "username": "adele.olson",
      "emailAddress": "[email protected]",
      "dateCreated": "2016-02-19T14:22:11-05:00",
      "links": {
        "self": {
          "href": "https://example.uat.achievers.com/api/v5/users/10726811",
          "method": "GET",
          "rel": "self"
        }
      },
      "profileImageUrl": "https://example.uat.achievers.com/platform_content/system/user/icon_med.jpg",
      "isPersonalizedProfileImage": false
    },
    {
      "id": 10726846,
      "firstName": "Brady",
      "lastName": "Garfinkel",
      "username": "brady.garfinkel",
      "emailAddress": "[email protected]",
      "dateCreated": "2016-02-19T14:22:13-05:00",
      "links": {
        "self": {
          "href": "https://example.uat.achievers.com/api/v5/users/10726846",
          "method": "GET",
          "rel": "self"
        }
      },
      "profileImageUrl": "https://example.uat.achievers.com/platform_content/system/user/icon_med.jpg",
      "isPersonalizedProfileImage": false
  ]
}

📘
For more information about the /users endpoint, see users.

Step 3

Retrieve the recognitions by using your access token to make a GET request to the /recognitions endpoint with the employee's username. Include an optional startDate and an optional endDate to filter the results by date.

Note that if you are sending userId instead of username, the useUserIds parameter must be set to true. If you are sending username, useUserIds is not required or must be set to false.

{
    "paging": {
        "totalItems": 1,
        "totalPages": 1,
        "page": 1,
        "pageSize": 25,
        "self": "https://example.uat.achievers.com/api/v5/recognitions?userId=10726811&page=1&pageSize=25&useUserIds=true",
        "first": "https://example.uat.achievers.com/api/v5/recognitions?userId=10726811&page=1&pageSize=25&useUserIds=true",
        "last": "https://example.uat.achievers.com/api/v5/recognitions?userId=10726811&page=1&pageSize=25&useUserIds=true"
    },
    "items": [
        {
            "recognitionId": 85994936,
            "nominator": {
                "id": 10726846,
                "name": "Brady Garfinkel",
                "profileImageUrl": "https://example.uat.achievers.com/platform_content/system/user/icon_med.jpg",
                "href": "https://example.uat.achievers.com/api/v5/users/10726846",
                "method": "GET",
                "rel": "nominator"
            },
            "nominees": [
                {
                    "id": 10726811,
                    "name": "Adele Olson",
                    "profileImageUrl": "https://example.uat.achievers.com/platform_content/system/user/icon_med.jpg",
                    "href": "https://example.uat.achievers.com/api/v5/users/10726811",
                    "method": "GET",
                    "rel": "nominees"
                }
            ],
            "recognitionText": "Awesome job on your presentation yesterday! You've been such a great addition to our team and your performance continues to be outstanding! Keep up the great work!",
            "dateCreated": null,
            "status": "APPROVED",
            "criterion": "Going the extra mile",
            "pointsAwarded": "0",
            "newsfeedEventId": "71423136",
            "newsfeedEventURL": "https://example.uat.achievers.com/event/71423136/bcdfkmnqrsvy34abcdefgijlmnrtwy12/"
        }
    ]
}

📘
For more information about the /recognitions endpoint, see recognitions.