You can use the User Images API to let end users upload images to a help center instance.

Uploading a user image is a three-step process:

  1. Make a request to create an image upload URL and a token. See Create Image Upload URL and Token.

  2. Make a PUT request to the image upload URL to upload the image. See Uploading the image with the upload URL.

  3. Make a request to create the image path in the help center. See Create Image Path.

    You can use the path in the body of a post comment to display the image inline.

Create Image Upload URL and Token

  • POST /api/v2/guide/user_images/uploads

Returns an upload URL and token. Use the upload URL in a PUT request to upload the image to the help center. See Uploading the image with the upload URL below.

Use the image token to create the image path after uploading the image. See Create Image Path.

Uploading the image with the upload URL

The endpoint returns an object with two properties url and headers that look as follows:

"headers": {  "Content-Disposition": "attachment; filename=\"01F1D8HVJ3TK6CZH8HM51YEQRG.jpeg\"",  "Content-Type": "image/jpeg",  "X-Amz-Server-Side-Encryption": "AES256"},"url": "https://{subdomain}.zendesk.com.com/aus-uploaded-assets/1/42/01F1D8HVJ3TK6CZH8HM51YEQRG?Content-Type=image%2Fjpeg\u0026X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=ACCESSKEY%2F20210322%2Fus-east-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20210322T152346Z\u0026X-Amz-Expires=3600\u0026X-Amz-Signature=a5fd09fb179fe3dc3e085398423988f1c5fc5f6a6eb66a0c020905f47b72f11b\u0026X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption\u0026x-amz-server-side-encryption=AES256"

Make a PUT request to the URL and with the specified headers to upload the image. Agents, end users, or anonymous users can make the request.

The following curl example uploads the image:

URL='http://{subdomain}.zendesk.com/aus-uploaded-assets/1/42/01F1D8HVJ3TK6CZH8HM51YEQRG?Content-Type=image%2Fjpeg&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ACCESSKEY%2F20210322%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210322T152346Z&X-Amz-Expires=3600&X-Amz-Signature=a5fd09fb179fe3dc3e085398423988f1c5fc5f6a6eb66a0c020905f47b72f11b&X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption&x-amz-server-side-encryption=AES256'curl $URL \  -X PUT \  --upload-file {file} \  -H 'Content-Disposition: attachment; filename="01F1D8HVJ3TK6CZH8HM51YEQRG.jpeg"' \  -H 'Content-Type: image/jpeg' \  -H 'X-Amz-Server-Side-Encryption: AES256'

A successful response will return:

Status 100 Continue

Request Body Format

The request body of POST /api/v2/guide/user_images/uploads must be a JSON object with the following properties:

Name Type Mandatory Description
content_type string true The content type of the file to upload
file_size number true The file size of the file to upload

Allowed for

  • Agents
  • End users
  • Anonymous users

Using curl

curl -X POST https://{subdomain}.zendesk.com/api/v2/guide/user_images/uploads \  --user {email_address}:{password} \  -d '{"content_type": "image/jpeg", "file_size": 169846}'

Example Response

Status 200 OK
{  "upload": {    "headers": {      "Content-Disposition": "attachment; filename=\"01F1D8HVJ3TK6CZH8HM51YEQRG.jpeg\"",      "Content-Type": "image/jpeg",      "X-Amz-Server-Side-Encryption": "AES256"    },    "token": "01F1D8HVJ3TK6CZH8HM51YEQRG",    "url": "https://{subdomain}.zendesk.com.com/aus-uploaded-assets/1/42/01F1D8HVJ3TK6CZH8HM51YEQRG?Content-Type=image%2Fjpeg\u0026X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=ACCESSKEY%2F20210322%2Fus-east-1%2Fs3%2Faws4_request\u0026X-Amz-Date=20210322T152346Z\u0026X-Amz-Expires=3600\u0026X-Amz-Signature=a5fd09fb179fe3dc3e085398423988f1c5fc5f6a6eb66a0c020905f47b72f11b\u0026X-Amz-SignedHeaders=content-disposition%3Bhost%3Bx-amz-server-side-encryption\u0026x-amz-server-side-encryption=AES256"  }}

Create Image Path

  • POST /api/v2/guide/user_images

Returns the image path that you can use to display the image in a community post.

You should only use this endpoint after uploading the image. See Uploading the image with the upload URL.

Request Body Format

The request body must be a JSON object with the following properties:

Name Type Mandatory Description
token string true The image token. See Get User Image Upload URL and Token
brand_id string true The ID of the brand where this image was uploaded

Allowed for

  • Agents
  • End users
  • Anonymous users

Using curl

curl -X POST \  --user {email_address}:{password} \  -d '{"token": "01F1D8HVJ3TK6CZH8HM51YEQRG", "brand_id": "10016"}' \  https://{subdomain}.zendesk.com/api/v2/guide/user_images

Example Response

Status 201 Created
{  "user_image": {    "content_type": "image/jpeg",    "path": "/hc/user_images/Bvj4bPDuRd-7d5hFVszvmQ.jpeg",    "size": 169846  }}