Badge Assignments

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

Assigning a badge adds a badge to a particular user's profile in Help Center.

Badges are available on the Gather Professional plan.

JSON Format

Badges assignments are JSON objects with the following properties:

Name Type Read-only Mandatory Comment
id string yes no Automatically assigned when the badge assignment is created
badge_id string no yes The id of the badge
user_id string no yes The id of the user
created_at timestamp yes no When the badge assignment was created
Example
{
  "id": "01E86XPXH5BK09KRWTDVEKVVY8",
  "badge_id": "01E86XPPRDCNHYTSVWSRMD76R0",
  "user_id": "57919551",
  "created_at": "2020-05-13T11:46:26.000Z"
}

Badge assignments can be filtered by any combination of the following:

  • ?user_id={user_id} - only assignments for this user
  • ?badge_id={badge_id} - only assignments for this badge
  • ?badge_category_id={badge_category_id} - only assignments for badges under this category
  • ?brand_id={brand_id} - only assignments within this brand

For example:

List Assignments for User

GET /api/v2/gather/badge_assignments?user_id={user_id}

Lists all badge assignments for the given user.

List Assignments for User within a Brand

GET /api/v2/gather/badge_assignments?user_id={user_id}&brand_id={brand_id}

Lists all badge assignments for the given user within the given brand.

List Assignments for Badge

GET /api/v2/gather/badge_assignments?badge_id={badge_id}

Lists all assignments for the given badge.

List Assignments for Badges within a Badge Category

GET /api/v2/gather/badge_assignments?badge_category_id={badge_category_id}

Lists all assignments for badges within the given badge category.

Allowed for
  • Help Center managers
Using curl
curl 'https://{subdomain}.zendesk.com/api/v2/gather/badge_assignments?badge_id=01E89DZ2NA6ZPMBMRPFRXC2BRY' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "badge_assignments": [
        {
            "id": "01E86XPXH5BK09KRWTDVEKVVY8",
            "badge_id": "01E89DZ2NA6ZPMBMRPFRXC2BRY",
            "user_id": "57919551",
            "created_at": "2020-05-13T11:46:26.000Z"
        }
    ]
}

Create Badge Assignment

POST /api/v2/gather/badge_assignments

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badges \
  -v -u {email_address}:{password} -d '{"badge_assignment": {"badge_id": "{{badge_id}}", "user_id": "{{user_id}}"}}' \
  -X POST -H "Content-Type: application/json"

Delete Badge Assignment

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

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