Send a Recognition

Send a recognition to one or more recipients on behalf of an employee. You can also share the recognition with each recipient's manager and other employees.

Step 1

To post a recognition on behalf of a user, the user needs to authenticate with Achievers and authorize your application. You can obtain a user access token through our 3-step authorization_code OAuth 2.0 flow.

📘
For more information about authorization and authentication, see Authentication.

Step 2

Retrieve the recipient's user information, including username and userId, by using your access token to make a GET request to the /users endpoint. Repeat this for each remaining recipient and for anyone whom you wish to share the recognition with. You can search for an employee by first name, last name or email address.

{
    "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/1085141",
            "method": "GET",
            "rel": "self"
        }
    },
    "profileImageUrl": "https://example.uat.achievers.com/platform_content/system/user/icon_med.jpg",
    "isPersonalizedProfileImage": false
}

📘
If you want to share the recognition with the recipient's manager, you do not need to retrieve the manager's user information, as the system can automatically pull this information from the recipient's profile.
For more information about the /users endpoint, see users.

Step 3

Retrieve a list of recognition criteria (values) that the sender is eligible to recognize the recipient(s) for by using your access token to make an OPTIONS request to the /recognitions endpoint. You will need to provide the username(s) of the recipient(s) in your request. The response will include the point amount that is associated with each criterion (0 for non-monetary recognition criteria, non-zero for points-based recognition criteria).

{
    "paging": {
        "totalItems": 1,
        "totalPages": 1,
        "page": 1,
        "pageSize": 25,
        "self": "https://example.uat.achievers.com/api/v5/recognitions?nominees=cliff.gold",
        "first": "https://example.uat.achievers.com/api/v5/recognitions?nominees=cliff.gold&page=1",
        "last": "https://example.uat.achievers.com/api/v5/recognitions?nominees=cliff.gold&page=1"
    },
    "items": [
        {
            "id": "31536",
            "name": "Everyday Recognition",
            "description": "Why? Because a kind remark today motivates the wins of tomorrow.",
            "bannerURL": "https://example.uat.achievers.com/platform_content/shard_10271/apiexa/private/module/peer_to_peer/31536/banner/en-US/banner.jpg",
            "moduleType": "FREE",
            "criteria": [
                {
                    "id": "28571",
                    "name": "Going the Extra Mile",
                    "description": "You didn't just get the job done. You put in that critical extra effort, which directly impacted your success and the success of those around you.",
                    "criterionBannerUrl": "https://example.uat.achievers.com/platform_content/shard_10271/apiexa/private/module/peer_to_peer/31536/postcard_images/en-US/screen/28571.png",
                    "pointValue": "0"
                },
                {
                    "id": "28581",
                    "name": "Great Progress",
                    "description": "The road may have been bumpy at times, but you have shown great heart and persistence on your journey towards greatness. You’re getting there: don’t stop.",
                    "criterionBannerUrl": "https://example.uat.achievers.com/platform_content/shard_10271/apiexa/private/module/peer_to_peer/31536/postcard_images/en-US/screen/28581.png",
                    "pointValue": "0"
                },
                {
                    "id": "28586",
                    "name": "Teamwork",
                    "description": "As the old saying goes, “many hands make light work.” You have lived that adage, and in doing so you have helped your team succeed.",
                    "criterionBannerUrl": "https://example.uat.achievers.com/platform_content/shard_10271/apiexa/private/module/peer_to_peer/31536/postcard_images/en-US/screen/28586.png",
                    "pointValue": "0"
                },
                {
                    "id": "28601",
                    "name": "a Thank You",
                    "description": "Perhaps you helped a coworker in need or just refilled the office coffee machine. Whatever you did, your thoughtful actions should be celebrated.",
                    "criterionBannerUrl": "https://example.uat.achievers.com/platform_content/shard_10271/apiexa/private/module/peer_to_peer/31536/postcard_images/en-US/screen/28601.png",
                    "pointValue": "0"
                },
                {
                    "id": "28611",
                    "name": "Passion",
                    "description": "You don't just clock your hours and go home; you truly care about the work you do, and it shows. Your passion is inspiring.",
                    "criterionBannerUrl": "https://example.uat.achievers.com/platform_content/shard_10271/apiexa/private/module/peer_to_peer/31536/postcard_images/en-US/screen/28611.png",
                    "pointValue": "0"
                }
            ]
        }
    ]
}

Step 4

If you want to include a custom image or video as part of the recognition, make a POST request to the /uploads endpoint using your access token. The endpoint will return a fileUploadId, which can be referenced in a subsequent POST request to the /recognitions endpoint (see below).

📘
For more information about the /upload endpoint, see uploads.

Step 5

Send the recognition by using your access token to make a POST request to the /recognitions endpoint with the username(s), the id of the criterion and, if applicable, the fileUploadId that you retrieved in the previous steps.

Note that if you are sending userIds for the user-identifying parameters, the useUserIds parameter must be set to true. If you are sending usernames, useUserIds is not required or must be set to false.

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