Postman

Ready to start building with Gusto's API? This guide will get you set up with Postman, complete with automation scripts and best practices our team uses internally.

Prerequisites

Make sure you've created an application in the Gusto Developer Portal and have your client_id and secret ready. If you haven't done this yet, check out our Quickstart.

Step 1: Fork our collection

We publish separate collections for each API version.

📘

Use the latest stable version unless you have a specific reason to stick with an older one.

Create your fork:

1. Find your version in our Postman collections.
2. Click Fork Collection while signed in to Postman.
3. Give it a unique name (like "Gusto API - [YOUR_COMPANY] Dev")
4. Select the workspace where you want your fork to live.
5. Enable Watch original collection—this is crucial! You'll get email notifications when we release updates.

Why fork instead of just importing? Forking creates a connection to our original collection, so you can pull in our updates without losing your customizations.

Step 2: Set up your local environment

Environment variables

Create a new environment in Postman with these essential variables:

Set up system access token request

1. Click on Collections > [GUSTO_API_VERSION] (for example, Gusto API v2025-06-15) > Introspection
2. Click the three dots next to the POST Refresh access token request, and select Duplicate.
3. Update the Title and Body of the request:
   1. Name this new request “System access token”
   2. Update the body to include the following:
      
      
      JSON

      {  
        "client_id": "{{client_id}}",  
        "client_secret": "{{client_secret}}",  
        "grant_type": "system_access"  
      }
      

4. Click Save.

Step 3: Set up scripts

Postman supports adding pre-request and post-response scripts. We recommend adding the following scripts to make development easier.

Collection pre-request: Version header

Add this script at the collection level (Collection → Scripts → Pre-request), not at the individual request level, to automatically set the version header for every request:

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

OAuth token post-response: System access token

Gusto leverages system access tokens so you can properly perform system-level operations such as creating partner-managed companies, subscribing to webhooks, and retrieving invoicing data.

Select your new POST System access token request, then select Scripts > Post-response to add the following script:

var jsonData = JSON.parse(responseBody)
pm.environment.set("system_access_token", jsonData.access_token);
pm.environment.set("refresh_token", jsonData.refresh_token);

Company creation post-response: Token management

Automatically save tokens to your environment after a successful company creation.

Add the following to your POST Create a partner managed company request under Scripts > Post-response:

var responseJson = JSON.parse(responseBody);

pm.environment.set("bearerToken", responseJson.access_token);
pm.environment.set("refresh_token", responseJson.refresh_token);
pm.environment.set("company_uuid", responseJson.company_uuid);

Step 4: Generate your first tokens

Now that you’ve set up your environment, it’s time to make some requests.

Retrieve system access token

From your collection:

1. Click Introspection > System access token.
2. Click Send.
3. (Optional) In your selected Environment, confirm the system_access_token was automatically populated.

Create a partner-managed company

Now for the fun part: creating a test company, and retrieving your access tokens.

1. Under your collection > Company > Companies, select POST create a partner managed company.

2. Select Body and add the following to the body of your request:

   JSON

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

   📘

   Why those {{$random...}} variables?

   Postman's predefined variables generate fresh data for each request.

3. Click Send.

4. (Optional) In your selected Environment, confirm the bearer_token, refresh_token, and company_uuid were automatically populated.

Step 5: Test your setup

Quick verification: Try making a request to any endpoint using your bearerToken.

Common issues and fixes:

• 401 Unauthorized? Check that your bearerToken was saved correctly
• Version header errors? Verify your version variable matches your collection version
• Collection not found? Make sure you forked (not just imported) the collection

For more help, check out the Troubleshooting section.

Best practices

You'll get an email when we push collection updates, but here are some tips for staying up to date on API changes and managing your Postman setup.

Pull changes like a pro

1. Check for updates: Click the dropdown on your collection → Pull Changes
2. Review the changelog: See exactly what changed before you commit
3. Handle conflicts wisely: If we've updated something you've customized, choose Keep Destination to preserve your customization instead of overwriting it

Understand changelog types

Use Postman variables

// Generate realistic test data
{{$randomFirstName}}
{{$randomLastName}}
{{$randomExampleEmail}}
{{$randomCompanyName}}
{{$randomJobTitle}}
{{$randomBankAccount}}

Create separate environments

We recommend you create environments depending on your use case:

• Development (your experimental playground)
• Demo (for user-facing presentations)
• Testing (for systematic testing scenarios)

Debug your scripts

Add console.log() statements to your scripts to debug issues:

console.log("Current version:", pm.variables.get("version"));
console.log("Response:", pm.response.json());

Troubleshooting

"Version header not set" error

Make sure your pre-request script is at the collection level, not the request level.

Lost customizations after update

Refer to the Postman docs to revert pulled changes.

To prevent this: always review changelogs before pulling changes. When in doubt, choose Keep Destination and manually review.

Token expired errors

Re-run your company creation request to generate fresh tokens.

Collection not syncing

Verify you have Watch original collection enabled in your fork settings.