DocumentationAPI Reference

Badges

A badge is a reward that can be added to a user's profile in the help center. For more information, see About Gather badges in Zendesk help.

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

Badges are available on the Gather Professional plan.

JSON format

Badges have the following properties:

NameTypeRead-onlyMandatoryComment
idstringyesnoAutomatically assigned when the badge is created
badge_category_idstringyesyesThe id of the badge category of the badge
namestringnoyesThe name of the badge
descriptionstringnoyesThe description of the badge. May be an empty string
icon_urlstringnonoThe URL of the badge's icon
created_attimestampyesnoWhen the badge was created
updated_attimestampyesnoWhen 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.

Parameters

NameTypeInRequiredDescription
brand_idintegerQueryfalseReturns the badges for the specified 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_upload_id, or set it to null.

To create a badge with an icon:

  1. Request a badge icon upload URL.
  2. Upload the icon to the provided URL with the attached headers.
  3. Send the POST /api/v2/gather/badges request while setting the icon_upload_id to the value of badge_icon_upload.id from the response of step 1.

The base64-based upload mechanism involving icon_url has been deprecated.

Allowed for

  • Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/gather/badges \  -d '{"badge": { "badge_category_id": "...", "name": "Community Superhero", "description": "Saving the day in the community!", "icon_upload_id": "01EYV0KR9EA8VGFMFDMEKPT15C"}}' \  -v -u {email_address}:{password}  -X POST -H "Content-Type: application/json"

Request Badge Icon Upload URL

  • POST /api/v2/gather/badges/icon_uploads

Returns a badge_icon_upload object consisting of the following properties:

NameTypeDescription
idstringA string identifying the badge icon upload. Used later when creating or updating a badge
urlstringA pre-signed AWS S3 URL where the badge icon will be uploaded in a separate request. The URL expires one hour after it's created
headersobjectAn object containing the signed header key-value pairs that must be included in the request to the pre-signed S3 URL when uploading the badge icon

The request body takes an object with the following properties:

NameTypeDescription
content_typestringThe content type of badge icon to be uploaded. Allowed types: "image/svg+xml", "image/png", "image/jpeg", or "image/gif"
file_sizeintegerThe badge icon size in bytes

Allowed for

  • Help Center managers

Using curl

curl https://{subdomain}.zendesk.com/api/v2/gather/badges/icon_uploads \  -v -u {email_address}:{password} -d '{"content_type": "image/svg+xml", "file_size": 420000}'\  -X POST -H "Content-Type: application/json"

Example Response

Status: 201 Created{  "badge_icon_upload": {    "id": "01EYV0KR9EA8VGFMFDMEKPT15C",    "url": "https://aus-uploaded-assets-production.s3.amazonaws.com/26/1749971/01EYV0KR9EA8VGFMFDMEKPT15C?Content-Type=image%2Fsvg%2Bxml&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYSPZOXOPSGBVQTMA%2F20210218%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210218T164716Z&X-Amz-Expires=3600&X-Amz-Signature=0d297b81820ffe8b609e0f801e73eb5a62b6a6108cd076d26a378a3a22e5efde&X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption&x-amz-server-side-encryption=AES256",    "headers": {      "Content-Disposition": "attachment; filename=\"01EYV0KR9EA8VGFMFDMEKPT15C.svg\"",      "Content-Type": "image/svg+xml",      "X-Amz-Server-Side-Encryption": "AES256"    }  }}

Upload Badge Icon

  • PUT {path_to_icon}

Uploads the specified local image to the location specified by the URL returned by the Request Badge Icon Upload URL endpoint. The URL is specified in the url property of the badge_icon_upload object. Append the headers from the headers property of the badge_icon_upload object to the PUT request.

Using curl

curl -X PUT -T /path/to/your/image.svg \     -H "Content-Type: image/svg+xml" \     -H "Content-Disposition: attachment; filename=\"01EYV0KR9EA8VGFMFDMEKPT15C.svg\"" \     -H "X-Amz-Server-Side-Encryption: AES256" \     -L "https://aus-uploaded-assets-production.s3.amazonaws.com/26/1749971/01EYV0KR9EA8VGFMFDMEKPT15C?Content-Type=image%2Fsvg%2Bxml&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYSPZOXOPSGBVQTMA%2F20210218%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210218T164716Z&X-Amz-Expires=3600&X-Amz-Signature=0d297b81820ffe8b609e0f801e73eb5a62b6a6108cd076d26a378a3a22e5efde&X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption&x-amz-server-side-encryption=AES256"

Update Badge

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

To update a badge not to have an icon, set icon_upload_id to null.

To leave the existing icon unchanged, omit icon_upload_id.

To update a badge with a new icon:

  1. Request a badge icon upload URL.
  2. Upload the icon to the provided URL with the attached headers.
  3. Send the PUT /api/v2/gather/badges/{id} request while setting the icon_upload_id to the value of badge_icon_upload.id from the response of step 1.

The base64-based upload mechanism involving icon_url has been deprecated.

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!"}}' \  -X PUT -H "Content-Type: application/json"

Delete Badge

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

Deleting a badge also deletes 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