Badges

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

A badge is a reward that can be added to a user's profile in Help Center.

Badges are organized by different badge categories and they are linked to users using badge assignments.

Badges are available on the Gather Professional plan.

JSON Format

Badges have the following properties:

Name Type Read-only Mandatory Comment
id string yes no Automatically assigned when the badge is created
badge_category_id string yes yes The id of the badge category of the badge
name string no yes The name of the badge
description string no yes The description of the badge. May be an empty string
icon_url string no no The URL of the badge's icon
created_at timestamp yes no When the badge was created
updated_at timestamp yes no When the badge was last updated
Example
{
  "id": "01E86XPPRDCNHYTSVWSRMD76R0",
  "badge_category_id": "01E86XPM9459S78F83VH8CD69H",
  "name": "Community Superhero",
  "description": "Saving the day in the community!",
  "icon_url": "https://...",
  "created_at": "2020-05-13T11:46:19.000Z",
  "updated_at": "2020-05-13T11:46:19.000Z"
}

List badges

GET /api/v2/gather/badges

Lists all badges.

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/badges \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "badges": [
        {
            "id": "01E86XPPRDCNHYTSVWSRMD76R0",
            "badge_category_id": "01E86XPM9459S78F83VH8CD69H",
            "name": "Community Superhero",
            "description": "Saving the day in the community!",
            "icon_url": "https://...",
            "created_at": "2020-05-13T11:46:19.000Z",
            "updated_at": "2020-05-13T11:46:19.000Z"
        },
        {
            "id": "01E89DZ2NA6ZPMBMRPFRXC2BRY",
            "badge_category_id": "01E86XPM9459S78F83VH8CD69H",
            "name": "Smart Cookie",
            "description": "Clever answers to difficult questions.",
            "icon_url": null,
            "created_at": "2020-05-14T11:08:59.000Z",
            "updated_at": "2020-05-14T11:08:59.000Z"
        }
    ]
}

Show Badge

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

Shows information about a single badge.

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

{
    "badge": {
        "id": "01E86XPPRDCNHYTSVWSRMD76R0",
        "badge_category_id": "01E86XPM9459S78F83VH8CD69H",
        "name": "Community Superhero",
        "description": "You're saving the day in the community!",
        "icon_url": "https://...",
        "created_at": "2020-05-13T11:46:19.000Z",
        "updated_at": "2020-05-13T11:46:19.000Z"
    }
}

Create Badge

POST /api/v2/gather/badges

To create a badge without an icon, omit icon_url, or set it to null. To create a badge with an icon, set icon_url to a data: URL, including the icon's MIME type, and with the content encoded using base64.

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badges \
  -v -u {email_address}:{password} -d '{"badge": { "badge_category_id": "...", "name": "Community Superhero", "description": "Saving the day in the community!", "icon_url": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iNDRweCIgaGVpZ2h0PSI0NHB4IiB2aWV3Qm94PSIwIDAgNDQgNDQiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+CiAgICA8dGl0bGU+U2tpbGwgbGV2ZWwgLSBOb3ZpY2UgKGJyb256ZSk8L3RpdGxlPgogICAgPGRlZnM+CiAgICAgICAgPHJlY3QgaWQ9InBhdGgtMSIgeD0iMCIgeT0iMCIgd2lkdGg9IjQwIiBoZWlnaHQ9IjQwIiByeD0iNCI+PC9yZWN0PgogICAgICAgIDxmaWx0ZXIgeD0iLTguOCUiIHk9Ii02LjIlIiB3aWR0aD0iMTE3LjUlIiBoZWlnaHQ9IjExNy41JSIgZmlsdGVyVW5pdHM9Im9iamVjdEJvdW5kaW5nQm94IiBpZD0iZmlsdGVyLTMiPgogICAgICAgICAgICA8ZmVPZmZzZXQgZHg9IjAiIGR5PSIxIiBpbj0iU291cmNlQWxwaGEiIHJlc3VsdD0ic2hhZG93T2Zmc2V0T3V0ZXIxIj48L2ZlT2Zmc2V0PgogICAgICAgICAgICA8ZmVHYXVzc2lhbkJsdXIgc3RkRGV2aWF0aW9uPSIxIiBpbj0ic2hhZG93T2Zmc2V0T3V0ZXIxIiByZXN1bHQ9InNoYWRvd0JsdXJPdXRlcjEiPjwvZmVHYXVzc2lhbkJsdXI+CiAgICAgICAgICAgIDxmZUNvbG9yTWF0cml4IHZhbHVlcz0iMCAwIDAgMCAwLjE4NDMxMzcyNSAgIDAgMCAwIDAgMC4yMjM1Mjk0MTIgICAwIDAgMCAwIDAuMjU0OTAxOTYxICAwIDAgMCAwLjQgMCIgdHlwZT0ibWF0cml4IiBpbj0ic2hhZG93Qmx1ck91dGVyMSI+PC9mZUNvbG9yTWF0cml4PgogICAgICAgIDwvZmlsdGVyPgogICAgICAgIDxjaXJjbGUgaWQ9InBhdGgtNCIgY3g9IjE5LjkyIiBjeT0iMTUuMiIgcj0iOCI+PC9jaXJjbGU+CiAgICAgICAgPGZpbHRlciB4PSItMjEuOSUiIHk9Ii0xNS42JSIgd2lkdGg9IjE0My44JSIgaGVpZ2h0PSIxNDMuOCUiIGZpbHRlclVuaXRzPSJvYmplY3RCb3VuZGluZ0JveCIgaWQ9ImZpbHRlci01Ij4KICAgICAgICAgICAgPGZlT2Zmc2V0IGR4PSIwIiBkeT0iMSIgaW49IlNvdXJjZUFscGhhIiByZXN1bHQ9InNoYWRvd09mZnNldE91dGVyMSI+PC9mZU9mZnNldD4KICAgICAgICAgICAgPGZlR2F1c3NpYW5CbHVyIHN0ZERldmlhdGlvbj0iMSIgaW49InNoYWRvd09mZnNldE91dGVyMSIgcmVzdWx0PSJzaGFkb3dCbHVyT3V0ZXIxIj48L2ZlR2F1c3NpYW5CbHVyPgogICAgICAgICAgICA8ZmVDb2xvck1hdHJpeCB2YWx1ZXM9IjAgMCAwIDAgMC4xODQzMTM3MjUgICAwIDAgMCAwIDAuMjIzNTI5NDEyICAgMCAwIDAgMCAwLjI1NDkwMTk2MSAgMCAwIDAgMC40IDAiIHR5cGU9Im1hdHJpeCIgaW49InNoYWRvd0JsdXJPdXRlcjEiPjwvZmVDb2xvck1hdHJpeD4KICAgICAgICA8L2ZpbHRlcj4KICAgICAgICA8cG9seWdvbiBpZD0icGF0aC02IiBwb2ludHM9IjE0LjQ4IDMyLjI0IDEzLjIgMjcuOTIgOC44IDI5LjI4IDEyLjU2IDIyLjE2IDE4LjI0IDI1LjIiPjwvcG9seWdvbj4KICAgICAgICA8ZmlsdGVyIHg9Ii0zNy4xJSIgeT0iLTI0LjglIiB3aWR0aD0iMTc0LjIlIiBoZWlnaHQ9IjE2OS40JSIgZmlsdGVyVW5pdHM9Im9iamVjdEJvdW5kaW5nQm94IiBpZD0iZmlsdGVyLTciPgogICAgICAgICAgICA8ZmVPZmZzZXQgZHg9IjAiIGR5PSIxIiBpbj0iU291cmNlQWxwaGEiIHJlc3VsdD0ic2hhZG93T2Zmc2V0T3V0ZXIxIj48L2ZlT2Zmc2V0PgogICAgICAgICAgICA8ZmVHYXVzc2lhbkJsdXIgc3RkRGV2aWF0aW9uPSIxIiBpbj0ic2hhZG93T2Zmc2V0T3V0ZXIxIiByZXN1bHQ9InNoYWRvd0JsdXJPdXRlcjEiPjwvZmVHYXVzc2lhbkJsdXI+CiAgICAgICAgICAgIDxmZUNvbG9yTWF0cml4IHZhbHVlcz0iMCAwIDAgMCAwLjE4NDMxMzcyNSAgIDAgMCAwIDAgMC4yMjM1Mjk0MTIgICAwIDAgMCAwIDAuMjU0OTAxOTYxICAwIDAgMCAwLjQgMCIgdHlwZT0ibWF0cml4IiBpbj0ic2hhZG93Qmx1ck91dGVyMSI+PC9mZUNvbG9yTWF0cml4PgogICAgICAgIDwvZmlsdGVyPgogICAgICAgIDxwb2x5Z29uIGlkPSJwYXRoLTgiIHBvaW50cz0iMjUuMzYgMzIuMjQgMjYuNjQgMjcuOTIgMzEuMDQgMjkuMjggMjcuMjggMjIuMTYgMjEuNiAyNS4yIj48L3BvbHlnb24+CiAgICAgICAgPGZpbHRlciB4PSItMzcuMSUiIHk9Ii0yNC44JSIgd2lkdGg9IjE3NC4yJSIgaGVpZ2h0PSIxNjkuNCUiIGZpbHRlclVuaXRzPSJvYmplY3RCb3VuZGluZ0JveCIgaWQ9ImZpbHRlci05Ij4KICAgICAgICAgICAgPGZlT2Zmc2V0IGR4PSIwIiBkeT0iMSIgaW49IlNvdXJjZUFscGhhIiByZXN1bHQ9InNoYWRvd09mZnNldE91dGVyMSI+PC9mZU9mZnNldD4KICAgICAgICAgICAgPGZlR2F1c3NpYW5CbHVyIHN0ZERldmlhdGlvbj0iMSIgaW49InNoYWRvd09mZnNldE91dGVyMSIgcmVzdWx0PSJzaGFkb3dCbHVyT3V0ZXIxIj48L2ZlR2F1c3NpYW5CbHVyPgogICAgICAgICAgICA8ZmVDb2xvck1hdHJpeCB2YWx1ZXM9IjAgMCAwIDAgMC4xODQzMTM3MjUgICAwIDAgMCAwIDAuMjIzNTI5NDEyICAgMCAwIDAgMCAwLjI1NDkwMTk2MSAgMCAwIDAgMC40IDAiIHR5cGU9Im1hdHJpeCIgaW49InNoYWRvd0JsdXJPdXRlcjEiPjwvZmVDb2xvck1hdHJpeD4KICAgICAgICA8L2ZpbHRlcj4KICAgIDwvZGVmcz4KICAgIDxnIGlkPSLwn4+dLVVzZXItYmFkZ2VzLWV4cGxvcmF0aW9ucyIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICAgICAgPGcgaWQ9IkJhZGdlLWV4YW1wbGVzLS0tLVByb3Bvc2Fscy0zIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMjk5LjAwMDAwMCwgLTE1OS4wMDAwMDApIj4KICAgICAgICAgICAgPGcgaWQ9IkFyY2hpdmVtZW50LWJhZGdlcyIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoNjEuMDAwMDAwLCAxNjAuMDAwMDAwKSI+CiAgICAgICAgICAgICAgICA8ZyBpZD0iU2tpbGwtbGV2ZWxzIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgyNDAuMDAwMDAwLCAwLjAwMDAwMCkiPgogICAgICAgICAgICAgICAgICAgIDxnIGlkPSJTa2lsbC1sZXZlbC0tLU5vdmljZS0oYnJvbnplKSI+CiAgICAgICAgICAgICAgICAgICAgICAgIDxtYXNrIGlkPSJtYXNrLTIiIGZpbGw9IndoaXRlIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx1c2UgeGxpbms6aHJlZj0iI3BhdGgtMSI+PC91c2U+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvbWFzaz4KICAgICAgICAgICAgICAgICAgICAgICAgPGcgaWQ9Ik1hc2siPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPHVzZSBmaWxsPSJibGFjayIgZmlsbC1vcGFjaXR5PSIxIiBmaWx0ZXI9InVybCgjZmlsdGVyLTMpIiB4bGluazpocmVmPSIjcGF0aC0xIj48L3VzZT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx1c2UgZmlsbD0iI0IzNTgyNyIgZmlsbC1ydWxlPSJldmVub2RkIiB4bGluazpocmVmPSIjcGF0aC0xIj48L3VzZT4KICAgICAgICAgICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICAgICAgICAgICAgICA8ZyBpZD0iT3ZhbCIgZmlsbC1ydWxlPSJub256ZXJvIiBtYXNrPSJ1cmwoI21hc2stMikiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPHVzZSBmaWxsPSJibGFjayIgZmlsbC1vcGFjaXR5PSIxIiBmaWx0ZXI9InVybCgjZmlsdGVyLTUpIiB4bGluazpocmVmPSIjcGF0aC00Ij48L3VzZT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx1c2UgZmlsbD0iI0ZGRkZGRiIgeGxpbms6aHJlZj0iI3BhdGgtNCI+PC91c2U+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvZz4KICAgICAgICAgICAgICAgICAgICAgICAgPGcgaWQ9IlBhdGgiIGZpbGwtcnVsZT0ibm9uemVybyIgbWFzaz0idXJsKCNtYXNrLTIpIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx1c2UgZmlsbD0iYmxhY2siIGZpbGwtb3BhY2l0eT0iMSIgZmlsdGVyPSJ1cmwoI2ZpbHRlci03KSIgeGxpbms6aHJlZj0iI3BhdGgtNiI+PC91c2U+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8dXNlIGZpbGw9IiNGRkZGRkYiIHhsaW5rOmhyZWY9IiNwYXRoLTYiPjwvdXNlPgogICAgICAgICAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgICAgICAgICAgICAgIDxnIGlkPSJQYXRoIiBmaWxsLXJ1bGU9Im5vbnplcm8iIG1hc2s9InVybCgjbWFzay0yKSI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8dXNlIGZpbGw9ImJsYWNrIiBmaWxsLW9wYWNpdHk9IjEiIGZpbHRlcj0idXJsKCNmaWx0ZXItOSkiIHhsaW5rOmhyZWY9IiNwYXRoLTgiPjwvdXNlPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPHVzZSBmaWxsPSIjRkZGRkZGIiB4bGluazpocmVmPSIjcGF0aC04Ij48L3VzZT4KICAgICAgICAgICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICAgICAgICAgIDwvZz4KICAgICAgICAgICAgICAgIDwvZz4KICAgICAgICAgICAgPC9nPgogICAgICAgIDwvZz4KICAgIDwvZz4KPC9zdmc+"}}' \
  -X POST -H "Content-Type: application/json"

Update badge

PUT /api/v2/gather/badges/{id}

To update a badge to have a new icon, set icon_url to a data: URL, including the icon's MIME type, and with the content encoded using base64. To update a badge not to have an icon, set icon_url to null. To leave the existing icon unchanged, provide icon_url with its current value (as given by either Show or List).

Allowed for
  • Help Center managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/gather/badges/{id} \
  -v -u {email_address}:{password} -d '{"badge": { "badge_category_id": "...", "name": "Community Superhero", "description": "Saving the day in the community!", "icon_url": "https://..."}}' \
  -X PUT -H "Content-Type: application/json"

Delete badge

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

Deleting a badge will also delete all badge assignments that pertain to the badge.

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