---
title: "Update a Group"
method: PUT
path: "/v1/issuer/groups/{group_id}"
tags: ["Groups"]
---

# Update a Group

`PUT /v1/issuer/groups/{group_id}`

## Path parameters

- `group_id` number, required

## 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.
  - `langauge` 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.
  - `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
  - `collections` unknown
  - `earning_criteria` object[], nullable — Full list of earning criteria to associate to this group. **Omit the key** to leave existing criteria untouched. **Send `[]` or `null`** to delete every criterion on the group. Otherwise the array is treated as the complete desired state: - Items **with** an `id` matching an existing criterion are updated in place. - Items **without** an `id` are created. - Existing criteria **absent** from the array are deleted. If any supplied `id` does not belong to the target group, the entire request fails with HTTP 400 and no changes are persisted.
    - `id` string, uuid — Include to update an existing criterion. Omit to create a new one.
    - `kind` 'achievement' | 'certificate' | 'competency' | 'completion' | 'course' | 'degree' | 'exam' | 'experience' | 'knowledge' | 'license' | 'participation' | 'reading' | 'skill' | 'specialization' | 'other' — Category of the criterion. Required when creating a new criterion.
    - `text` string — Human-readable description of the criterion. Required when creating a new 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` when creating.
    - `position` number — Ordering within the group (1-based).
  - `skill_framework_version_id` number, nullable — Id of the Skill Framework version the Group's skills should come from, as returned in a framework's `versions` array by [View all Skill Frameworks](#operation/View%20all%20Skill%20Frameworks). Send it together with `framework_skills` to set or change the Group's framework. 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 — Full list of framework skills for the Group, each entry a `{ id, breadcrumb_ids }` pair. The array **replaces** the Group's current skills rather than adding to them. - **Omit both this and `skill_framework_version_id`** to leave the Group's framework and skills exactly as they are. - **Send `null` or `[]`** without `skill_framework_version_id` to move the Group off frameworks: the framework is cleared, every attached skill is removed, and `learning_outcomes` can be set in the same request. - **Send both keys** to make the Group's skills exactly what you supply. Passing a different version also moves the Group to that version. Every valid skill is attached; every invalid one is skipped and itemized in the `errors` array of a `207` response. If none of the supplied skills are valid, the Group keeps the framework and skills it already had.
    - `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` unknown
    - `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 updated, but one or more framework skills could not be attached. Non-framework changes in the request are still saved.
- `403` — Forbidden - your plan does not include access to skills frameworks, and the request tried to change the framework skills of a Group that is already framework-backed. Nothing in the request is saved, including changes to unrelated fields. The Group's framework and skills stay saved and readable, and moving it to free-text skills by sending `"framework_skills": null` is still allowed.

---

[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/versions/56b317c13686/schema)