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

Related information:

Requirements

To make Sunshine API requests, you will need the following requirements:

  • A Zendesk account on a Zendesk Suite plan. You can also request a sponsored test account for testing purposes.
  • Postman app - Download and install the app by signing up for a free account on the Postman website.
  • Authentication method for making API requests - You must first be a verified user to make Zendesk API requests. You can authorize against the API using either basic authentication with your email address and password, or with your email address and an API token. This is configured in the Admin Center interface in Apps and integrations > APIs > Zendesk APIs. For more information, see Security and Authentication in the Zendesk Support API reference.

Import the Postman collections

Postman allows collections to be created containing a series of pre-built API requests. Zendesk provides Postman collections for the Sunshine Custom Objects API, Profiles API, and Events API.

To import the Postman collections

  1. Download the Postman collections for Custom Objects API, Profiles API, or Events API.
  2. Open your Postman application.
  3. Click Import to open the import window.
  4. Drag and drop the Postman collection files in the window to import the collections.

Set up environment variables

Before making an API call in Postman using the collections, you need to configure the following variables for the collection.

Authorization

In Postman, 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 are using an API token, append "/token" to your username, and for the password paste the API token generated in the Zendesk Support admin interface.

  4. If you are 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.

  5. Click Update.

Zendesk subdomain

In the collection, the double curly braces in the URL path defines a variable. You can set the value for a collection, so it will be used for all API requests.

{{baseUrl}}/api/v2/user_profiles/:profile_id

The URL parameter for your Zendesk subdomain is {{baseUrl}} for profiles and events, or {{subdomain}} for custom objects.

To set your Zendesk subdomain

  1. Right-click the collection in the sidebar, select Edit, then select the Variables tab.
  2. For the variable name, enter "subdomain" for the custom objects collection, or "baseURL" for the profiles collection or events collection.
  3. Under Initial value, enter your Zendesk account subdomain, and click Update.

Request format

The Content-Type entity header indicates the resource media type. This varies depending on the HTTP method:

  • POST requests require a "Content-Type: application/json" header
  • PATCH requests require a "Content-Type: application/merge-patch+json" header for custom objects, and "Content-Type: application/json" header for profiles and events
  • GET requests should return "Content-Type: application/json"

The Accept header is set to “application/json” header for all requests.

In Postman, you can set the header for an HTTP method in a collection.

To set up headers for an HTTP method in a collection

  1. In the sidebar, select an API request from the collection.
  2. Select the Headers tab.
  3. In the Key field, enter “Content-Type”, and in the Value field, select from the drop-down list the applicable value for the HTTP method mentioned earlier in this section.
  4. In the Key field, enter “Accept”, and in the Value field, select “application/json”.
  5. Click Save. The request header is retained for the requests with the same HTTP method in the collection.

Set up request parameters

An API request can also contain request parameters. A colon before an element in the path creates a path variable in the Params tab.

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

You can also add query parameters to the path using the colon and element format. They are added to the Params tab and the values can be changed and saved. This is particularly useful for identifier queries in the profiles API.

For more details about identifier queries, see Using identifier queries with profiles.