---
title: "Search for Groups"
method: POST
path: "/v1/issuer/groups/search"
tags: ["Groups"]
---

# Search for Groups

`POST /v1/issuer/groups/search`

## Request body

- object
  - `ids` number[] — Limit the list of Groups to those id match the given array.
  - `name` string — Limit the list of Groups to those named with the given string. Supports partial matching.
  - `course_name` string — Limit the list of Groups to those whose course name matches the given string. Supports partial matching.
  - `department_id` number — Limit results to a particular Department. Must be a Department accessible to the API key being used; otherwise a `400 Bad Request` is returned. When omitted, results include all Departments the API key can access.
  - `meta_data` object — Key/values for client's own data on group
  - `start_updated_date` string, date — Date after which Groups which have been updated should be returned. Format: YYYY-MM-DD
  - `end_updated_date` string, date — Date before which Groups which have been updated should be returned. Format: YYYY-MM-DD
  - `page_size` number — The pagination response size, default of 50.
  - `page` number — The pagination page.

## Response `200`

OK

- object
  - `groups` object[]
    - `id` number, required
    - `name` string, required
    - `course_description` string, required
    - `course_name` string, required
    - `learning_outcomes` string[], required
    - `attach_pdf` boolean, required
    - `course_link` string, required
    - `language` string, required
    - `design_name` string, required
    - `updated_at` string, required
    - `created_at` string, required
    - `design_id` number, nullable, required
    - `blockchain` boolean, required
    - `certificate_design_id` number, nullable, required
    - `badge_design_id` number, nullable, required
    - `primary_design_id` number, nullable, required
    - `department_id` number, required
    - `meta_data` object, required
      - `course_id` string
    - `generate_private_credential` boolean, required
    - `auto_expiry` number, required
    - `signup_url_show` boolean, required
    - `signup_url` string, required
    - `course_link_show` boolean, required
    - `organization_link_show` boolean, required
    - `skill_category` object, required
      - `id` number
      - `name` string
    - `achievement_type` string
    - `collections` object[], required
      - `id` number, required
      - `name` string, required
      - `description` string, nullable, required
    - `earning_criteria` object[], required — 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, required — 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[], required — 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.
  - `meta` object
    - `current_page` number
    - `next_page` number
    - `prev_page` unknown
    - `total_pages` number
    - `total_count` number

---

[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)