Badge Categories

Note: The Badges API is currently in early access. Learn more.

A badge category provides a way to group together related badges.

Badges are available on the Gather Professional plan.

JSON Format

Badge categories are JSON objects with the following properties:

Name Type Read-only Mandatory Comment
id string yes no Automatically assigned when the badge category is created
brand_id string no yes The brand that the badge category pertains to (can only be set when the badge category is created)
name string no yes The name of the badge category (shown to users who award/remove badges)
slug string no yes A unique (within the brand) textual code of the badge category (used in the Templating API as a keyword for filtering)
created_at timestamp yes no When the badge category was created
updated_at timestamp yes no When the badge category was last updated
Example
{
  "id": "01E89E1AD4BG6JA2XSZZN5BZVC",
  "brand_id": "7056041",
  "name": "Achievements",
  "slug": "achievements",
  "created_at": "2020-05-13T11:46:16.000Z",
  "updated_at": "2020-05-13T11:46:16.000Z"
}

List Badge Categories

GET /api/v2/gather/badge_categories

Lists all badge categories.

This request can be further filtered using the brand_id query string parameter to only show badge categories within a particular brand.

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badge_categories \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "badge_categories": [
        {
            "id": "01E86XPM9459S78F83VH8CD69H",
            "brand_id": "7056041",
            "name": "Titles",
            "slug": "titles",
            "created_at": "2020-05-13T11:46:16.000Z",
            "updated_at": "2020-05-13T11:46:16.000Z"
        },
        {
            "id": "01E89E1AD4BG6JA2XSZZN5BZVC",
            "brand_id": "7056041",
            "name": "Achievements",
            "slug": "achievements",
            "created_at": "2020-05-14T11:10:13.000Z",
            "updated_at": "2020-05-14T11:10:13.000Z"
        }
    ]
}

Show Badge Category

GET /api/v2/gather/badge_categories/{id}

Shows information about a single badge category.

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badge_categories/{id} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "badge_category": {
        "id": "01E89E1AD4BG6JA2XSZZN5BZVC",
        "brand_id": "7056041",
        "name": "Achievements",
        "slug": "achievements",
        "created_at": "2020-05-13T11:46:16.000Z",
        "updated_at": "2020-05-13T11:46:16.000Z"
    }
}

Create Badge category

POST /api/v2/gather/badge_categories

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badge_category \
  -v -u {email_address}:{password} -d '{"badge_category": {"brand_id": "{{brand_id}}", "name": "Certifications", "slug": "certs" }}' \
  -X POST -H "Content-Type: application/json"

Delete Badge Category

DELETE /api/v2/gather/badge_categories/{id}

Badge categories can only be deleted if they do not contain any badges.

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badge_categories/{id} \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content