--- updatedAt: 2026-04-17T16:55:10.000Z --- Fetch the complete documentation index at: https://docs.gusto.com/embedded-payroll/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Postman Learn how to set up and maintain your Postman environment 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](https://dev.gusto.com/) and have your `client_id` and `secret` ready. If you haven't done this yet, check out our [Quickstart](https://docs.gusto.com/embedded-payroll/docs/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. Run In Postman **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: | Variable | Value | Description | | :-------------------- | :------------------------------- | :----------------------------------------------------- | | `version` | 2026-02-01 | Your API version (replace with your chosen version) | | `bearerToken` | (empty for now) | Will be auto-populated by scripts | | `company_uuid` | (empty for now) | Will be auto-populated by scripts | | `refresh_token` | (empty for now) | Will be auto-populated by scripts | | `system_access_token` | (empty for now) | Will be auto-populated by scripts | | `client_id` | Your application's client ID | Find this on your application in the Developer Portal. | | `client_secret` | Your application's client secret | Find this on your application in the Developer Portal. | ### Set up system access token request 1. Click on **Collections** > **\[GUSTO\_API\_VERSION]** (for example, Gusto API v2026-02-01) > **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: ```javascript 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: ```javascript 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**: ```javascript 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 | Changelog type | Description | | :---------------------- | :----------------------------------------------------------------------------------------------------------------- | | New endpoint added | Safe to accept—adds new functionality without breaking existing requests | | New parameter added | Usually safe—typically optional parameters that enhance existing endpoints | | URL parameters modified | Review carefully—might affect how you structure requests | | Conflicting changes | **Pro tip**: Always choose **Keep Destination** to preserve your customizations, then manually review what changed | ### Use Postman variables ### 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: ## 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](https://learning.postman.com/docs/collections/use-collections/manage-collections/#revert-collection-changes) 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.