Quickstart

Use this guide to set up your development environment and make your first API calls.

Prerequisites

1. A Gusto Developer Portal account, sign up here.
   1. Important note: When creating an account, you’ll be asked Are you building embedded payroll? → select Yes.
2. (Highly recommended) Postman, install the collection by clicking here: or follow the instructions in our Postman guide.

Create your organization and application

An Organization represents the entity that will be using the Embedded Payroll API. This top-level structure allows you to manage team members, Applications, demo companies, and other resources associated with your API implementation.

An Application generates the credentials (client ID and secret key) necessary for making API calls. You can create multiple applications for testing in our Demo environment on the Gusto Developer Portal.

📘

New applications default to the latest stable API version.

Step 1: Create an organization

To create an organization:

1. Sign in to the Gusto Developer Portal.
2. On the left-hand navigation, click Organizations.
3. Click + Create organization.
   1. Add Organization name, team email, and website details
4. Click Create

Step 2: Create an application

To create an application:

1. On the left-hand navigation, click Applications
2. Click + Create application
   1. Add Application name
   2. Provide at least one redirect URI (required for OAuth2)
3. Click Create

Your application will generate a unique client_id and client_secret. Store these securely, because you'll need them for authentication.

Step 3: Set up authentication

Generate a system access token to make your first API calls by calling the POST /oauth/token endpoint with a “grant_type” of “system_access”:

Sample request:

curl --request POST \
  --url 'https://api.gusto-demo.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "system_access"
  }'

Sample response:

{
  "access_token": "system_access_token",
  "token_type": "bearer",
  "created_at": 1728518070,
  "expires_in": 7200
}

🚧

Important

Access tokens expire after 2 hours.

Step 4: Create your first company

Use your system access token to call the POST /v1/partner_managed_companies endpoint:

curl --request POST \
  --url 'https://api.gusto-demo.com/v1/partner_managed_companies' \
  --header 'Authorization: Bearer SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "first_name": "Test",
      "last_name": "User",
      "email": "[email protected]"
    },
    "company": {
      "name": "Test Company Inc",
      "ein": "123456789"
    }
  }'

Sample response:

{
  "company_uuid": "ce80a710-eed2-4623-b879-16181abef0ec",
  "access_token": "company_specific_access_token",
  "refresh_token": "company_specific_refresh_token",
  "expires_in": 7200
}

Access tokens

All steps going forward use the company-specific access and refresh tokens. Access tokens expire after 2 hours. Read about more in our Authentication guides.

Troubleshooting

Here are a few common issues and solutions:

📘

Need help?

Contact our Support team at [email protected].

Next steps

If you'd like to use Postman to test and interact with the Gusto Embedded API, check out our Postman guide, where we cover how to set up and maintain your Postman environment—including recommended scripts for automating storage of access tokens.

Or, if you'd like a more in-depth walkthrough of how to get started, see our Getting started guide.