Setting Up Postman

Follow this guide to setup Postman in the most effective way possible. This setup will allow the most customization locally while still being able to pull in any of our changes without overwriting any of your local configurations.

Find our public Postman collection here. We publish one collection for each available version of the API. Select the version you will be building off of, and create a fork while logged into your Postman account.

Give your fork of the collection a unique label, select the workspace where you want it to live, and make sure to select “Watch original collection” to receive email notifications whenever we release changes to the collection.

After clicking “Fork Collection” you should see the forked collection in your own workspace.

Set up a local environment where you can store your local environment variables. At this point, make sure you've created an application by following the Getting Started Guide. Make note of your apiKey and version.

At a minimum, you must add version and apiKey variables. The version variable should be the version string of the API you’re using (i.e. “2023-12-01, in the above example). And apiKey will be the API key that you saved earlier.

Using the API via Postman

In order to use the API, you must retrieve an access_token. The easiest way to do this is by making a request to the POST /partner_managed_companies endpoint.

We like to use Postman’s predefined variables to randomly generate new values for each request.

{
    "user": {
        "first_name": "{{$randomFirstName}}",
        "last_name": "{{$randomLastName}}",
        "email": "{{$randomExampleEmail}}"
    },
    "company": {
        "name": "From PartnerManaged API {{$randomCompanyName}}",
        "trade_name": ""
    }
}

Before making this request you must make sure the apiKey header is prefixed with the string Token as described in the docs.

After making the POST request, you should receive an API access token, which must be saved as a bearerToken in your environment variables (it is also useful to save the returned company uuid).

At this point you should be able to make a request to any other endpoint in the postman collection using the bearerToken to authenticate.

Some Postman tips

These are some scripts and other tricks that we use internally which make working with Postman even easier.

Setting the version header for each request

By default the version header is set to a placeholder value <version> in our collection, which is meaningless to Postman. A simple way to fill in this header value before each request is by creating the following pre-request script at the collection level.

version = pm.variables.get("version");
pm.request.headers.clear("X-Gusto-API-Version");
pm.request.headers.add({key: 'X-Gusto-API-Version', value: version });

Automatically saving access tokens (and other variables)

We use a Postman Test, which is a script that runs after a response has been received, to automatically save the access_token and company_uuid to our environment. That way we can immediately make subsequent requests.

pm.test("Success", () => {
    pm.response.to.have.status(200);

    const responseJson = pm.response.json();
    pm.environment.set("bearerToken", responseJson.access_token);
    pm.environment.set("refresh_token", responseJson.refresh_token);
    pm.environment.set("company_uuid", responseJson.company_uuid);
});