Overview

Postman is a popular cross-platform application that helps development teams building integrations to manually use and test APIs. This guide is a step-by-step instruction on setting up a personal postman workspace, configuring to so that you will be alerted when changes to existing or new APIs are released, and making your first API test call with Paylocity-provided credentials to a sandbox environment.

Prerequisites

1. An account with Postman (it's free)
2. The Postman Desktop App
3. Paylocity API client credentials for authentication
4. A sandbox companyID your credentials are authorized to access

Create your Postman workspace

1. Login to Postman

2. Navigate to the official Paylocity APIs for Integration-building workspace and click the "Run in Postman" button on the collection overview page.

3. Follow the steps displayed on screen to fork the collection; forking creates a copy of the collection in your personal workspace and enables you to perform changes without affecting the original. The label for the fork may be anything, but it's recommended to use a descriptor that makes it easily identifiable to you and your team that it's for Paylocity Integrations. Checking the box for notifications will enable alerts to be sent when new updates are released for the collection that can be pulled and merged into your workspace.

   

4. When successfully forked, a "Paylocity APIs (Latest Version)" will appear in your personal Postman workspace area, referencing the source from which it was created.

Configure your workspace for sandbox access

1. Open the Postman App
   Note: It is always recommended to use the Postman App when making API calls. The web version of Postman has documented limitations that may result in errors when attempting to make API calls via their Browser agent.
2. Navigate to the Postman Vault and create two entries for your Sandbox API credentials.

• sandbox-id
• sandbox-secret

Set Environment Parameters (company ID)

Navigate to the Environment area of your workspace and select the Sandbox environment.

Under the "companyId" variable, in the current value column enter the sandbox companyID your credentials are authorized to access. Then save your configuration change. Making this change will ensure that for any API call with Postman where the parameter {companyID} is referenced, the value entered here will be used.

Making your first API call

1. In the upper right corner of the Postman UI set the environment to Sandbox
2. Navigate to the top level of the collection and go to the Authorization tab
3. The Configure New Token section of the authorization tab should appear similar to below, with parameter variables shown in blue, meaning they are correctly linked to the environment variable URL and Vault credentials.
4. Click the Get New Access Token button to Auth with Paylocity and generate your bearer token to be used with API calls.

5. When authorized, you will be presented with a series of success and confirmation screens. Click the "Proceed" then "Use Token" buttons to use the generated bearer token with further API calls.

   

That's it. Postman has been setup and you will be able to make your first API call.

Navigate to the endpoint to which the credentials have access, fill in the appropriate query parameters and click the send button. Reference our Errors document to troubleshoot any error codes received.