Justworks Partner API (1.7.2)

Partner API is a public-facing API provided by Justworks to partners and customers who want to integrate with Justworks.

Our V1 API uses OAuth2 authentication.

The base URL for the V1 API is https://public-api.justworks.com.

To obtain access to the API, please contact partner-api@justworks.com.

Our API uses scoped tokens. When a token is assigned a scope, it will inherit all the access permissions of its "child scope(s)".

Currencies

Currency values are represented as zero-decimal.

Fixed amounts use 2 significant digits. For example, $45.00 would be represented in the API as 4500.

Percentage amounts use 4 significant digits. For example, 3.7% would be represented as 37000.

Empty values

Our API design follows the guidelines below regarding empty values:

• Single-value types are omitted from responses if they have empty values
• Array types are included in responses as empty arrays if they have no values
• Complex types (i.e., objects) are omitted from responses if they are completely empty or null.
  • If any of a complex type's nested fields have values, that field and any of its populated nested fields will be included.
  • Any of its empty nested fields will be omitted.
• A field is marked required in our API docs if we always expect it to have a value. These fields will never be omitted from responses.

Formats and Data Structures

The V1 API is built with international data in mind. This includes addresses, phone numbers and money fields.

There are also more complex structures that require specific shapes of data and fieldsets that vary from country to country. Such structures include a company's legal corporate structure, tax identifiers and member employment information.

On these types you'll find a hashmap keyed by country code. This map contains typed structures that match the way specific countries track things like corporate legal structure, tax IDs and employment status.

We represent country codes using the ISO 3166-1 alpha-2 standard.

International Members

International members (members with a type of international_employee or employee_eor) are now included in List Members and Get Member datasets.

These members contain a limited subset of datapoints, including the following:

• ids
• name
• type
• active status
• emails
• employment information
• department
• job title
• employment start date
• office
• manager

Justworks's Public API is built around an Authorization Code Flow; customers must explicitly authorize integrations to access their data.

Step 1: Getting a new OAuth Application

Creation of OAuth Applications for our API is not self-service, but the Justworks team is happy to help set one up for you.

We will need the following information:

• Redirect URI: a callback URL the customer will be redirected to after authorizing your application (an OAuth application can have multiple associated redirect URIs)
• Scopes: the set of data your application will need to have access to (see Available Scopes)
• Name: how you want your app identified to your customers (most likely your company/product)

We also support the following optional info, shown to customers when they authorize your application:

• Logo URL
• Terms of Service URL
• Privacy Policy URL

Once created, you will be provided with a client_id and client_secret for your application, along with the Justworks auth url customers should be directed to.

Step 2: Customer Authorization

You will need to construct a URL and direct customers to it, so that they can authorize you to access their information. A common way to do this is to have a button in your UI saying something like "Connect to Justworks".

It is recommended to use an OAuth library to construct the URL, but it will look something like https://payroll.justworks.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&state=STATE_PARAM&scope=SPACE_DELIMITED_SCOPES&redirect_uri=REDIRECT_URI, where:

• response_type: should always be code
• client_id: the client ID of the OAuth application obtained in Step 2
• state: an arbitrary parameter your team can use in validating authenticity of responses from our OAuth server
• scope: a space-delimited list of scopes (see available scopes)
• redirect_uri: one of the callback URLs you provided, to redirect the user to when the flow is complete (success or failure).

The customer will access this link in their browser, log into their Justworks account, and authorize your application to access their information.

Once this is successful, they will be redirected to the specified redirect_uri, with the generated authorization code in the code query string parameter and the state parameter returned for verification.

Step 3: Get an OAuth token

The redirect will call your callback URL with an authorization code; your system can now call the API directly, and exchange this for an OAuth Token.

curl --location 'https://public-api.justworks.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'redirect_uri=REDIRECT_URI' \
--data-urlencode 'code=AUTHORIZATION_CODE'

The parameters for this request:

• grant_type should always be authorization_code when obtaining a token for the first time (i.e., not refreshing a token)
• client_id is the client ID of the OAuth application obtained in Step 1
• client_secret the client secret of the OAuth application obtained in Step 1
• redirect_uri should match the Redirect URI used in the previous step
• code is the authorization code obtained in the previous step

Sample Response: { "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "scope": "SPACE DELIMITED SCOPES", "expires_at": "2024-12-11T13:09:16.688468-06:00" }

Access tokens are valid for 24 hours. Refresh tokens are valid for 30 days.

Step 4: Using the tokens

You can now access the API to retrieve customer data. Simply add the access token to the header with the Bearer prefix:

curl --location 'https://public-api.justworks.com/v1/company' --header 'Authorization: Bearer ACCESS_TOKEN'

Because the access token is short-lived, the refresh token will need to be regularly used to obtain a new access token.

Example refresh request:

curl --location 'https://public-api.justworks.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=REFRESH_TOKEN'

Parameters:

• grant_type should always be refresh_token when refreshing a token
• client_id is the client ID of the OAuth application obtained in Step 1
• client_secret is the client secret of the OAuth application obtained in Step 1
• refresh_token the refresh_token value from the original token response in Step 3

Response:

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "scope": "SPACE DELIMITED SCOPES",
  "expires_at": "2024-12-11T13:09:16.688468-06:00"
}

When a customer disconnects your application, you should revoke the access token to prevent further access to their data.

curl --location 'https://public-api.justworks.com/v1/oauth/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET' \
--data-urlencode 'token={ACCESS_TOKEN|REFRESH_TOKEN}' \
--data-urlencode 'token_type_hint={access_token|refresh_token}'

The parameters for this request:

• client_id is the client ID of the OAuth application obtained in Step 1
• client_secret is the client secret of the OAuth application obtained in Step 1
• token is the access token or refresh token you want to revoke
• token_type_hint is optional, but recommended. Both access_token and refresh_token will be looked up at the best effort, but specifying the type will allow us to optimize the lookup.
  • If you are revoking an access token, use access_token
  • If you are revoking a refresh token, use refresh_token

Note: The older /oauth/revoke endpoint is deprecated and will be removed in the future. Please always use /v1/oauth/revoke