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
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 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
-
In Postman, click the orange New button in the upper left and select Request.
-
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.
-
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.
-
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.
-
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.
-
Click Save on the right side of your request path.
-
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
-
In Postman, select New > Collection from the menu in the upper-left side of the workspace.
-
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
-
Right-click the collection in the sidebar, then select Edit.
-
Select the Authorization tab.
-
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 .
-
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
-
Right-click the collection in the sidebar, select Edit, then select the Variables tab.
-
For the variable name, enter baseURL.
-
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.
9 Comments
Since you've deactivated the developer console portal over the weekend, without any prior warning, I'm now forced to use postman. Something which I know nothing about. Whilst postman is a 3rd party tool, it would be nice if you could have a proper article on how newbies like myself can actually run a query via Postman.
The above article gets me halfway set up but now I'm stuck and have no idea what to do or how to get my API call to run via postman.
Hey Amie B! Thanks for bringing this up! I was going to write something up about this very topic and I'd love to discuss with you some of the specific issues that you're running into so that I make sure I'm covering as much as is needed. Would you mind sharing a screenshot of the part where you're stuck in Postman and then I'll be able to give you an idea of where we'd need to go next. If you could also let me know any other difficulties that you're running into, I'm happy to help sort those out, as well as incorporate them into an article.
Also, in case this is helpful, Postman's documentation in this area is actually super robust and helpful: https://learning.postman.com/docs/postman/launching-postman/sending-the-first-request/
Hi Amie,
We added a quickstart section to the article:
Quickstart - Making a Zendesk API request
Let us know if it helps.
Charles
Hey team,
I really appreciate the quick turnaround from you both with help and the update to this article with more details. It's def helped me and have been able to successfully run some ZD API calls via postman now. Feeling much more confident now. :)
The bit I was getting stuck with was - I had this (see below) and I couldn't figure out where to input it in Postman to run it against the API call. I managed to figure it out that it needed to go in the Body tab, as RAW and Set to JSON. Once I did that it executed as I expected from there.
Good point. I added a description of how to include request data in step 4 of the quickstart section.
Thanks.
Hi Darren Chan, nice introduction. Maybe i missed it but i could not find.
Why don't you provide a Postman collection for your APIs? I find this kind of solution with Sunshine API at https://developer.zendesk.com/rest_api/docs/sunshine/custom_objects_api#run-in-postman.
That makes life easy while working Zendesk. I am struggling while working Support API.
Thanks for your help.
Hi Enes Dogan — thank you for the feedback and pointing out the need for more Postman collections. It's definitely a valid point and has been requested before.
I can't say when exactly, but improvements to this area and better integration with development tools such as Postman is planned, so we're definitely on the same page!
Darren Chan & @...,
This is a an example of using Postman as a Zendesk Extension for use as a Target in a. Automation or Trigger? This would help those of us who are switching to or following API Led design principals but are just starting with postman.
Hi Dave Kaminsky! Could you explain specifically what you're looking for with this request? I'd be happy to provide a more concrete example for your use-case!
Please sign in to leave a comment.