Automated Badge Assignment

Overview

Use the Badges API to programmatically award badges based on external triggers, such as completing a training module, hitting a performance milestone, or reaching a service anniversary in your HR system.

Recognition programmes are most effective when they're timely and consistent. However, manually awarding badges - checking who completed training, who hit their sales target, who reached a work anniversary - doesn't scale. Someone has to remember, verify, and then log into Workvivo to assign the badge. Inevitably, achievements get missed, recognition arrives late, and the programme loses credibility.

The Workvivo Badges API lets you automate the entire process. When your LMS reports a course completion, your CRM logs a sales milestone, or your HRIS calculates a service anniversary, your system can immediately assign the corresponding Workvivo badge - no human intervention required. You can also create badges programmatically, query who has received them, and unassign them if needed. The API supports both Workvivo user IDs and external IDs, so you can drive badge assignments directly from your source systems.

Value & Benefits

Recognise achievements instantly. Badges are awarded the moment a milestone is reached in the source system - no delay between achievement and recognition.

Ensure no achievement goes unrecognised. Automated triggers mean every qualifying employee receives their badge, eliminating the human error of forgetting or overlooking someone.

Scale recognition programmes effortlessly. Whether you're awarding badges to 10 employees or 10,000, the API handles it programmatically without increasing admin workload.

Connect recognition to real business outcomes. Tie badges directly to measurable achievements in external systems (training completions, sales targets, safety milestones) rather than relying on subjective manual awards.

Maintain programme integrity. Programmatic assignment ensures consistent criteria are applied; every employee who meets the threshold gets the badge, and the "Badge already assigned to this user" guard prevents duplicates.

Applications

Training and certification completion. When an employee completes a course or earns a certification in your LMS (Cornerstone, Docebo, Litmos), automatically award the corresponding Workvivo badge to publicly recognise their development.

Sales and performance milestones. When a salesperson hits their quarterly target or closes their 100th deal in your CRM, trigger a badge assignment to celebrate the achievement visibly across the organisation.

Service anniversaries. Use your HRIS data to automatically award anniversary badges (1 year, 5 years, 10 years) on the exact date, ensuring no milestone is missed.

Safety milestones. Award safety badges when teams or individuals reach incident-free milestones (e.g., 100 days without incident), driven by data from your safety management system.

Onboarding completion. When a new hire completes all onboarding tasks (forms submitted, training done, first-week checklist complete), automatically award an "Onboarding Champion" badge.

Community participation. Award badges based on engagement metrics pulled from external analytics - e.g., employees who contributed to 10+ knowledge base articles or answered 50+ questions in support channels.

Technical Details

Before using these examples, complete Quick Start to create an app and API key and find your Base URL and Workvivo-Id.

Create a Badge

curl -X POST https://api.workvivo.com/v1/badges \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json" \
  -F "title=Training Complete - Data Security" \
  -F "description=Awarded for completing the mandatory Data Security training module." \
  -F "type=standard" \
  -F "award_confetti=1" \
  -F "award_confetti_colours[]=#30A69A" \
  -F "award_confetti_colours[]=#ffffff"

{
    "data": {
        "id": 14,
        "title": "Training Complete - Data Security",
        "description": "Awarded for completing the mandatory Data Security training module.",
        "type": "standard",
        "value": null,
        "rules_active": null,
        "rules_needed": null,
        "award_msg": null,
        "award_confetti": true,
        "award_confetti_colours": ["#30A69A", "#ffffff"],
        "badge_received_count": 0,
        "image": null,
        "award_image": null,
        "created_at": "2026-06-17T10:00:00Z",
        "updated_at": "2026-06-17T10:00:00Z",
        "permalink": "https://yourcompany.workvivo.com/directory/people/badges/14"
    },
    "status": "success",
    "meta": {}
}

Assign a Badge to a User

curl -X POST https://api.workvivo.com/v1/users/42/badges/14 \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

curl -X POST https://api.workvivo.com/v1/users/by-external-id/emp-1001/badges/14 \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

{
    "data": {
        "user_id": 42,
        "badge_id": 14,
        "external_user_id": "emp-1001"
    },
    "status": "success",
    "meta": {}
}

The external_user_id value is the user's external ID when one is set; otherwise it is null.

Unassign a Badge

curl -X DELETE https://api.workvivo.com/v1/users/42/badges/14 \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

{
    "data": {
        "user_id": 42,
        "badge_id": 14,
        "external_user_id": null
    },
    "status": "success",
    "meta": {}
}

List Users Who Have a Badge

curl -X GET "https://api.workvivo.com/v1/badges/14/users?skip=0&take=50" \
  -H "Authorization: Bearer $WORKVIVO_TOKEN" \
  -H "Workvivo-Id: $WORKVIVO_ORG_ID" \
  -H "Accept: application/json"

{
    "data": [
        {
            "user": {
                "id": 4,
                "external_id": null,
                "email": "kb@example.com",
                "name": "Kate Banks",
                "first_name": "Kate",
                "last_name": "Banks",
                "display_name": null,
                "avatar_url": "https://cdn.workvivo.com/img/users/kb.jpg",
                "job_title": "Internal Communications",
                "timezone": null,
                "locale": null,
                "hire_date": null,
                "manager_id": 14,
                "date_of_birth": null,
                "mobile_phone": null,
                "direct_dial": null,
                "has_logged_in": true,
                "created_at": "2024-04-06T13:08:44Z",
                "permalink": "https://yourcompany.workvivo.com/directory/people/4"
            },
            "created_at": "2024-04-06T13:50:42Z"
        }
    ],
    "status": "success",
    "meta": {
        "pagination": {
            "skip": 0,
            "take": 50,
            "total_records": 1,
            "next_page": null
        }
    }
}

JavaScript Integration Example

Receive a course-completion event from an LMS and award the corresponding Workvivo badge to the employee.

import express from 'express';

const app = express();
const apiUrl = 'https://api.workvivo.com/v1';
const headers = {
    Authorization: `Bearer ${process.env.WORKVIVO_TOKEN}`,
    'Workvivo-Id': process.env.WORKVIVO_ORG_ID,
    Accept: 'application/json',
};

app.use(express.json());

const courseBadges = {
    'SEC-101': 14,
    'LEAD-200': 15,
    'SAFE-050': 16,
    ONBOARD: 17,
};

app.post('/webhooks/course-completed', async (request, response) => {
    const { course_id: courseId, employee_id: employeeId } = request.body;
    const badgeId = courseBadges[courseId];

    if (!badgeId) {
        return response.status(200).json({ status: 'no_badge_configured' });
    }

    const result = await assignBadge(employeeId, badgeId);

    return response.status(200).json(result);
});

async function assignBadge(userExternalId, badgeId) {
    const encodedUserId = encodeURIComponent(userExternalId);
    const response = await fetch(
        `${apiUrl}/users/by-external-id/${encodedUserId}/badges/${badgeId}`,
        { method: 'POST', headers },
    );

    const result = await response.json();

    if (response.ok) {
        return { status: 'badge_awarded', badge: result.data };
    }

    const errors = JSON.stringify(result.meta?.errors ?? []);
    if (response.status === 400 && errors.includes('already assigned')) {
        return { status: 'already_assigned' };
    }

    if (!response.ok) {
        throw new Error(`Badge assignment failed: ${response.status}`);
    }
}

app.listen(3000);