Skip to content

Data Model

The BadgeCert API is built around a small set of core entities that mirror the product: organizations, people who receive credentials, badge definitions, and issuances.

API vs web UI: The REST API exposes people in your organization as the Users resource (for example GET /v1/users). The BadgeCert web application and much of the product experience refer to those same people as earners. When you read UI labels, help articles, or talk to users who work in the app, expect earner; when you call the API, use users and /v1/users.

Most API operations create, retrieve, update, or link these objects, so understanding them makes it easier to map BadgeCert data to your own systems and reason about what each request affects.

Core Entities

Organization

An organization is the tenant in BadgeCert. It owns all relevant data (including badge definitions, users, and issuances) and defines the boundary for administration and reporting.

API keys and integrations are scoped to one organization. In practice, almost every request runs in the context of the organization associated with the API key or access token used to authenticate the request; you do not span multiple organizations with a single key.

User

A user represents a person who can receive badges. User records identify the people who receive credentials in BadgeCert, typically using directory-style information such as email.

The same user may receive multiple badge issuances over time. The user is the “who,” not the individual award.

Badge

A badge is the definition of the credential being awarded: it carries the metadata that describes what is being issued (such as name and description) and what the credential means in your program.

A badge definition can be issued to many users; it is a template, not a single award. Confusing a badge definition with a one-off grant is a common source of integration mistakes.

Issuance

An issuance is a specific grant of a badge to a specific user. It links a badge definition to a user and represents one credential event: this person earned this credential at this point in the lifecycle.

Issuances may be updated when supported by the product and API, depending on the business action being performed.

A user can have many issuances.

Entity Relationships

Conceptually, everything hangs off the organization:

  • Badges belong to an organization.
  • Users belong to an organization.
  • Issuances connect a badge to a user within that organization.

You can picture the hierarchy like this:

Organization
├── Badges
├── Users
└── Issuances (each links one badge to one user)

Issuances always reference an existing badge definition and an existing user; they are not standalone resources.

An issuance always points to one badge and one user; it is the join between the template (badge) and the person (user).

Example Issuance Lifecycle

A typical badge issuance flow, described only in business terms:

  1. A badge definition exists under the organization (the credential is defined and ready to be awarded).
  2. A user exists (or is created) so there is someone to receive the credential.
  3. An issuance is created, linking that badge and that user. That issuance is the concrete “this person earned this badge” record.

This sequence is conceptual; specific operations and endpoints are covered elsewhere.

Implementation Notes

When you design an integration, keep the following in mind:

  • User identity is often aligned with email or another stable identifier your organization already uses; treat user records as the anchor for “who” in your systems.
  • Issuances may change over time when the API and product support updates for the action you are performing.
  • Storing BadgeCert identifiers (for users, badges, issuances, or other resources your integration touches) in your own systems makes reconciliation and support much easier.
  • Your integration should separate the idea of a badge definition (a template many people can earn) from an issuance (one person’s award).