Exploring Zendesk APIs with Postman

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

Disclaimer: Zendesk doesn't provide support for Postman or other third-party tools. For help, see the Postman documentation.

What you'll need

To use Postman with the Zendesk APIs, you'll need the following:

• A Zendesk account

• A free Postman account

You can use Postman as a web or desktop app. This article uses the web app. To install the desktop app, see Installing and updating Postman in the Postman documentation.

Forking a Zendesk API collection

Postman groups and organizes API endpoints into collections. Collections are housed in workspaces. When you create a Postman account, Postman creates a personal workspace for you. By default, this workspace is visible only to you.

The Zendesk Public API workspace is a public workspace that publishes collections for the Zendesk APIs. The collections in this workspace are managed by Zendesk and are visible to anyone.

To use a collection from the Zendesk Public API workspace, you first need to fork the collection. Forking saves a copy of the collection to one of your workspaces, such as your personal workspace. This lets you do the following:

• Send Zendesk API requests using endpoints in the collection. You can't send requests from the public workspace.

• Make changes to the collection, such as configuring authorization or variables, without affecting the public version.

• Create pull requests to contribute bug fixes to the public version of the collection.

Making your Postman profile public

To fork a collection from a public workspace, you must make your Postman profile public. This lets others see your fork and any public contributions you make. For more information about public profiles, see Making your profile public in the Postman documentation.

Using the "Run in Postman" button

Most introduction pages in the Zendesk API reference, such as the Ticketing Introduction and Help Center Introduction, include a Run in Postman button. You can use this button to fork a collection for the related API into your workspace.

To fork a collection using the "Run in Postman" button

1. On an introduction page in the Zendesk API reference, click the Run in Postman button. Example:

   

   This opens a Postman page containing a Fork collection into your workspace modal.

   

2. Click Fork Collection.

   If prompted, sign in to Postman.

3. On the Fork Collection page, enter a Fork label and select a workspace.

   

4. Click Fork Collection.

5. If prompted, make your profile public. A public profile is required to fork a collection from the Zendesk Public API workspace.

The collection appears in the sidebar of the workspace you selected.

Syncing a forked collection

Zendesk periodically updates collections in the Zendesk Public API workspace to add functionality, remove deprecated features, and fix bugs. You can pull these updates into your fork.

To sync a forked collection

1. In the left sidebar, click the more actions icon () next to the collection name.

2. Click Pull changes.

3. Review the diff and click Pull changes.

Configuring a collection

Before making API requests, configure the following settings for your forked collection:

• Authorization

• Variables

Authorization

Configure the authentication method and credentials used for requests to the collection's endpoints. For more information about supported authentication methods, see Security and authentication in the Zendesk API reference.

To configure authorization for a collection

1. In the left sidebar, click the more actions icon () next to the collection name.

2. Click Edit.

3. Click the Authorization tab.

4. Select Basic Auth using the Type drop-down.

   Append "/token" to your email address, and enter your API token as the password.

   

   If you're using an OAuth access token, under the Type drop-down options, select Bearer Token, and enter the token.

   

5. Click the Save icon ().

Variables

Zendesk API collections use variables to build the base URL of API requests. The values of these variables depend on the API and your Zendesk account.

To set variable values

1. In the left sidebar, click the more actions icon () next to the collection name.

2. Click Edit.

3. Click the Variables tab.

   

4. In the Variables tab, set the CURRENT VALUE for the collection's variables.

   If the collection has only a baseUrl variable, use a value of "https://{subdomain}.zendesk.com". Replace "{subdomain}" with your Zendesk subdomain.

   Important: For Sell APIs, use a baseUrl value of "https://api.getbase.com" instead.

   If the collection has the host, subdomain, and baseUrl variables, set host to "zendesk" and subdomain to your Zendesk subdomain. Leave the baseUrl value as "https://{{subdomain}}.{{host}}.com".

5. Click Persist All. This sets each variable's CURRENT VALUE as the INITIAL VALUE.

6. Click the Save icon ().

Making a Zendesk API request

After configuring your forked collection, you can use Postman to send Zendesk API requests using the collection's endpoints.

To make a Zendesk API request

1. In the left sidebar, click the collection name and navigate to the endpoint you want to work with. Then click the endpoint name.

   Some endpoints are organized into subfolders. For example, endpoints that require a resource id as a path parameter are in a {resource_id} subfolder. Example:

   

2. Click the Params tab.

   If needed, select and specify path or query parameters for the request. You can view supported values in the corresponding section of the API reference.

   

3. Click the Body tab.

   If needed, specify a JSON body for the request. You can view supported properties in the corresponding section of the API reference.

4. Click Send to make the request.

   A response appears in the bottom pane.