---
title: "Create a Group"
method: POST
path: "/v1/issuer/groups"
tags: ["Groups"]
---

# Create a Group

`POST /v1/issuer/groups`

## Request body

- object
  - `name` string, required — Name of the group (for your reference and never shown to the recipient).
  - `course_name` string, required — Name of the course or achievement. This is visible to the recipient.
  - `course_description` string, required — Description of the course or achievement. This is visible to the recipient.
  - `course_link` string — Link to the web page with information related to this Credential. Typically this is a course information or event information page.
  - `language` string — Language for the group. Currently we support "en", "es", "vi", "pt", "ja", "fr", "da", "nl", "fi", "no", "nb", "ro", "sv", "th", "tw", "zh", "tr", "ar", "he", "ms" and "de". Default language is en.
  - `attach_pdf` boolean — PDF of the Credential should be attached to email when recipient is informed. Default is false.
  - `blockchain` boolean — Enable or disable recording of these Credentials on a Blockchain.
  - `design_id` number — DEPRECATED. Certificate Design which the Group will use to display Credentials.
  - `certificate_design_id` number — Certificate Design which the Group will use to display Credentials.
  - `badge_design_id` number — Badge Design which the Group will use to display Credentials.
  - `primary_design_id` number — Primary Design which the Group will use to display Credentials.
  - `department_id` number — Department that the group belongs to. If not defined the group will be assigned to the organizations default department.
  - `meta_data` object — You can use this parameter to attach key-value strings to the object. Meta data is useful for storing additional, structured information on an object.
  - `learning_outcomes` unknown
  - `generate_private_credential` boolean — The default value of `Credential.private` for the Group. The supported values are `true`, `false`, and `null`. When this is set to `true` or `false`, it will override `Department.generate_private_credential` and be used as the default of `Credential.private` when creating a new `Credential`. When this is set to `null`, it won't override `Department.generate_private_credential` which will be used for the default of `Credential.private` instead.
  - `auto_expiry` number — Specifies the number of years from the issue date after which the credential will automatically expire. If the specified value is less than or equal to 0, it will be ignored.
  - `signup_url` string — This provides a direct path for credential viewers to enroll in your course.
  - `signup_url_show` boolean — Show or hide the sign up url. The supported values are `true`, `false` and `null`.
  - `course_link_show` boolean — This links the credential data record to your information about the credential on your website. The supported values are `true`, `false` and `null`.
  - `organization_link_show` boolean — Show or hide the link to your website homepage. The supported values are `true`, `false` and `null`.
  - `allow_duplicate_credentials` boolean — An email address can receive more than one credential. The supported values are `true` & `false`. Defaults to `false`.
  - `skill_category_id` number — ID of the skill category to associate with this group.
  - `collections` unknown
  - `achievement_type` string — The type of achievement, for example 'Award' or 'Certification'. The supported values are listed here https://www.imsglobal.org/spec/ob/v3p0#achievementtype-enumeration
  - `earning_criteria` object[] — Optional list of criteria the recipient must satisfy to earn this credential. Each item creates a new criterion on the group.
    - `kind` 'achievement' | 'certificate' | 'competency' | 'completion' | 'course' | 'degree' | 'exam' | 'experience' | 'knowledge' | 'license' | 'participation' | 'reading' | 'skill' | 'specialization' | 'other', required — Category of the criterion.
    - `text` string, required — Human-readable description of the criterion. Supports a limited set of HTML tags: `<a>` (with `href`, `title`, `target`, `rel`), `<p>`, `<br>`, `<hr>`, `<ul>`, `<ol>`, `<li>`, `<strong>`/`<b>`, `<em>`/`<i>`, `<u>`, `<sub>`, `<sup>`. Other tags and attributes are stripped on save.
    - `required` boolean — Whether the recipient must satisfy this criterion. Defaults to `true`.
    - `position` number — Ordering within the group (1-based). Defaults to the next available position if omitted.
  - `skill_framework_version_id` number, nullable — Id of the Skill Framework version to take skills from, as returned in a framework's `versions` array by [View all Skill Frameworks](#operation/View%20all%20Skill%20Frameworks). Must be sent together with `framework_skills`. Omit both this and `framework_skills` to create a Group that uses free-text `learning_outcomes` instead. This key is write-only. The response reports the Group's pinned version as `skill_framework.version.id` instead, and its skills as `skills`.
  - `framework_skills` object[], nullable — Skills from `skill_framework_version_id` to attach to the Group, each entry a `{ id, breadcrumb_ids }` pair. Must be sent together with `skill_framework_version_id` and contain at least one skill — sending only one of the two keys, or an empty array, attaches nothing and returns a `207` with a `framework_params_incomplete` error. Every valid skill is attached; every invalid one is skipped and itemized in the `errors` array of a `207` response. The Group itself is always created, so read `skills` back from the response to see what was attached.
    - `id` number, required — Id of the skill, as returned by [Search Skills in a Framework Version](#operation/Search%20Skills%20in%20a%20Framework%20Version).
    - `breadcrumb_ids` number[] — Which position in the framework this skill is being attached at: the ids of its ancestors, from the root down to its immediate parent. Copy one of the trails from the skill's `breadcrumbs` in the search response, in the same order. Only omit this, or send `[]`, for a skill that sits at the root of the framework. For a skill that has a parent an empty trail is rejected, and that skill is not attached. To attach the same skill at two different positions in the framework, send it twice with different `breadcrumb_ids`.

## Response `200`

OK

- object
  - `group` object
    - `id` number
    - `name` string
    - `course_description` string
    - `course_name` string
    - `learning_outcomes` string[]
    - `attach_pdf` boolean
    - `course_link` string
    - `language` string
    - `design_name` string
    - `updated_at` string
    - `created_at` string
    - `design_id` number
    - `blockchain` boolean
    - `certificate_design_id` unknown
    - `badge_design_id` unknown
    - `primary_design_id` unknown
    - `department_id` number
    - `meta_data` object
      - `foo` string
    - `generate_private_credential` boolean
    - `auto_expiry` number
    - `signup_url_show` boolean
    - `signup_url` string
    - `course_link_show` boolean
    - `organization_link_show` boolean
    - `skill_category` object
      - `id` number
      - `name` string
    - `achievement_type` string
    - `collections` object[]
      - `id` number, required
      - `name` string, required
      - `description` string, nullable, required
    - `earning_criteria` object[] — Criteria the recipient must satisfy to earn this credential, ordered by `position`.
      - `id` string, uuid, required
      - `kind` 'achievement' | 'certificate' | 'competency' | 'completion' | 'course' | 'degree' | 'exam' | 'experience' | 'knowledge' | 'license' | 'participation' | 'reading' | 'skill' | 'specialization' | 'other', required
      - `text` string, required
      - `required` boolean, required
      - `position` number, required
    - `skill_framework` object, nullable — The Skill Framework this Group's skills come from, with the version pinned on the Group nested under it. `null` when the Group uses free-text `learning_outcomes` instead. Present whenever the Group has a framework version pinned — **including a Group that has a framework but no skills attached**, so an object here does not imply that `skills` is non-empty. `skill_framework.version.id` is the only place a response reports the Group's pinned version id, and it is the value to send back as `skill_framework_version_id` when you write. Retiring a version does not move a Group off it; the version changes only when the Group is explicitly migrated to a newly published one, and that applies retroactively to every credential already issued from the Group. See the [Skills Frameworks](#tag/Skills-Frameworks) endpoints.
      - `id` number
      - `name` string
      - `source_type` 'external' | 'custom' — `external` for a framework maintained by Accredible, `custom` for one uploaded by your organization.
      - `taxonomy` string, nullable — The published taxonomy an external framework comes from: `ONET`, `ESCO` or `NACE`. Always `null` for custom frameworks.
      - `provider` string, nullable — The organization that publishes the framework.
      - `description` string, nullable
      - `attribution` object — Attribution that the framework's licence requires you to display wherever you show its skills.
        - `text` string, nullable
        - `url` string, nullable
      - `version` object — The framework version pinned on this Group — what it is actually issuing against, not the framework's latest. `status` is the version's own status. Unlike [View all Skill Frameworks](#operation/View%20all%20Skill%20Frameworks), a version that is mid-retirement for your Department is not re-presented as `retired` here: that endpoint answers whether you can still select the version, whereas a Group records what it already uses.
        - `id` number
        - `version` string
        - `status` string
    - `skills` object[] — Framework skills attached to this Group, ordered by name. Empty when the Group uses free-text `learning_outcomes`, and when it has a framework selected but no skills that can be tagged — unlike `skill_framework`, this is never `null`. Identical to the `skills` array on [Credential](#tag/Credentials) responses: both are built from the same payload, so the two surfaces cannot disagree. There is one entry per placement in the framework, so a skill sitting at two positions in the taxonomy appears as two entries — the same `id` with different `breadcrumbs`. **Do not key this array by `id`.** This is the read shape, and it differs from the write shape. To set a Group's skills you send `framework_skills` as `{ id, breadcrumb_ids }` pairs; see [Update a Group](#operation/Update%20a%20Group).
      - `id` number, required
      - `name` string, required
      - `identifier` string, nullable, required — The framework's own external identifier for the skill — an O*NET element id, an ESCO URI, or whatever a custom framework was uploaded with. This is the field to match against your own systems. `null` when the framework does not provide one.
      - `description` string, nullable, required
      - `url` string, nullable, required — Link to the skill in the publisher's own taxonomy, when the framework provides one.
      - `breadcrumbs` object[], required — Where this skill sits in the framework: its ancestors from the root down to its immediate parent, with the skill itself excluded. Empty for a skill that sits at the root of the framework. Each node carries its own external `identifier` alongside its `id` and `name`. To write this placement back on the Group, send these `id` values in the same order as `framework_skills[].breadcrumb_ids`.
        - `id` number, required
        - `name` string, required
        - `identifier` string, nullable, required — The ancestor's own external identifier in the framework, when it has one.

## Other responses

- `207` — Multi-Status - the Group was created, but one or more framework skills could not be attached. The Group always exists; only skill attachment is partial.

---

[API](https://skmtc.net/accredible/apis/accredible-credential-api.md) · [All operations](https://skmtc.net/accredible/apis/accredible-credential-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/accredible/accredible-credential-api/revisions/f49e189c5767/schema)