Exploring Zendesk APIs with Postman

Postman is a popular application for testing APIs. This article explains how to set up Postman to make Zendesk API requests.

Topics covered in this article:

• Requirements
• Quickstart - Making a Zendesk API request
• Creating a collection in Postman
• Adding requests to your collection
• Configuring your collection
• Setting up request parameters

Disclaimer: Zendesk can't provide support for third-party tools such as Postman. Refer to the Postman documentation or search online for a solution.

Requirements

To make Zendesk API requests, you'll need the following:

• A Zendesk Support account. If you don't already have a Zendesk Support account, register to start a free trial at https://www.zendesk.com/register/.

• The Postman app. Download and install the app by signing up for a free account on the Postman website.

• An authentication method for making API requests. You must first be a verified user to make Zendesk API requests. You can authorize against most Zendesk APIs using either basic authentication with your email address and password, or with your email address and an API token. This is configured in the Zendesk Support admin interface in Admin > Channels > API. For more information, see Security and Authentication in the Zendesk Support API reference.

  Chat and Sell API users must authenticate with an OAuth access token. For Chat, see Using an OAuth access token in the Chat developer docs. For Sell, see OAuth2 in the Sell developer docs.

Quickstart - Making a Zendesk API request

Make a quick request to the Zendesk Support API to get started. You'll use the Show the Current User endpoint:

GET /api/v2/users/me.json

The first step is to gather information about the request in the developer docs. The Show the Current User doc looks as follows:

To make the request

1. In Postman, click the orange New button in the upper left and select Request.

   

2. Name the request "Show Me", select a collection to save it to, and click Save.

   If you haven't created a collection yet, click +Create Collection.

   

3. In the Postman request editor, enter the API endpoint:

   https://{subdomain}.zendesk.com/api/v2/users/me.json

   Replace {subdomain} with your own Zendesk subdomain.

   

   You can define a baseURL variable as described in API base URL below. The other examples in this quickstart show the variable.

4. Make sure GET is selected as the method on the left side.

   The doc for the endpoint specifies this is a GET request. If you were making a PUT (update), POST (create), or DELETE request, you'd select the corresponding method.

   If making a PUT or POST request, you'd also need to send some JSON data with the request. Click the Body tab below your request path. Make sure the raw and JSON options are selected, then enter your data. Example:

   

   You don't need to do this for the GET endpoint in this quickstart.

5. Click the Authorization tab below your request path, select Basic Auth from the types, and enter your Zendesk email and password.

   

   This only authorizes this particular request. You can authorize all the requests in the collection. For instructions, see Authorization below.

6. Click Save on the right side of your request path.

7. Click Send to make the request.

   A response like the following should appear:

   

The rest of this article gives more details about working with Postman.

Creating a collection in Postman

Postman collections let you group API endpoints any way you want. For example, you could create a Tickets collection for testing ticket-related endpoints or a Chat collection for trying out Chat API endpoints.

To create a Postman collection

1. In Postman, select New > Collection from the menu in the upper-left side of the workspace.

2. Give your collection a name and click Create.

Adding requests to your collection

For instructions, see Requests in the Postman documentation.

Consult the Zendesk API documentation for the details of each request. See Zendesk APIs.

See Quickstart - Making a Zendesk API request.

Configuring your collection

To work more efficiently in Postman, you can configure the following settings for your collection:

• Set the authorization method and credentials for all the requests in the collection

• Define the base URL of all the requests in the collection

Authorization

You can configure the authorization method for a collection. Don’t forget to first enable and configure your authorization method in your Zendesk Support admin interface at https://{your_subdomain}.zendesk.com/agent/admin/api/settings.

To set up authorization for a collection

1. Right-click the collection in the sidebar, then select Edit.

2. Select the Authorization tab.

3. Under the Type drop-down options, select Basic Auth and enter your username and password you enabled in the Zendesk Support admin interface. If you're using an API token, append "/token" to your username, and for the password paste the API token generated in the Zendesk Support admin interface.

   

   

   If you're using an OAuth access token, under the Type drop-down options, select Bearer Token, and paste the token. For information about OAuth authentication, see Using OAuth authentication with your application .

4. Click Update.

API base URL

Most Zendesk APIs have a subdomain variable in the base URL. The value depends on your Zendesk account. Example:

https://{subdomain}.zendesk.com/api/v2/{resource}

The Chat and Sell APIs use different conventions:

https://www.zopim.com/api/v2/{resource}

https://api.getbase.com/v2/{resource}

Postman lets you define variables in API paths using double curly braces. You can set a value for a collection so it will be used for all API requests in that collection. For example, you can define a baseUrl variable and then use it in a request as follows:

{{baseUrl}}/api/v2/users.json

To set a Zendesk base URL variable

1. Right-click the collection in the sidebar, select Edit, then select the Variables tab.

2. For the variable name, enter baseURL.

3. Under Initial value, enter the base URL of the Zendesk API you're using, and click Update.

   

Setting up request parameters

Some API requests have path or query parameters. A colon before an element in the path creates a path parameter in the Params tab. Example:

In the Params tab, add the key and value, then click Save to save the endpoint.

You can also add query parameters using a key/value format. They are added to the Params tab and the values can be changed and saved. This is particularly useful for search endpoints.