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 or remove badges
slug string no yes A unique (within the brand) textual code of the badge category. Used in the Templating language 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

Parameters

Name Type In Required Description
brand_id integer Query false Returns badge categories for the specified brand

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