Overview
💡 Josys provides a public API. By using this feature, you can leverage the API to automatically import external data into Josys or retrieve data from Josys.
- For details on how to use it, please refer to the API Documentation (specifications for the Josys API).
Eligible Users
- Available to all subscribed customers.
How to Issue an ID Token (API Key)
- Click
Menu > Developer > API Credentials. Click the "Create" button in the upper right corner. - Enter a label name, then click the "Create" button.
- The "API User Key" and "API Secret Key" will be displayed. Copy and save them.
⚠️ The "API Secret Key" cannot be displayed again, so please make sure to save it securely.
API Integration Procedures with Major SaaS
Please check the following for integration procedures:
Important Notes
⚠️
The previous version of the Josys API (v1) was discontinued at the end of February 2025.
In the current Josys API, URLs for the user APIs start with
In the current Josys API, URLs for the user APIs start with
/api/v2/, and URLs for all other APIs start with /api/v1/. APIs whose URLs start with /api/v1/ are not the discontinued old API (v1). They are currently supported and can continue to be used as is. For details on each API, see the API Documentation.URLs by API
Append the following paths to the endpoint https://developer.josys.it.
| Target | Path |
|---|---|
| Issue tokens |
/api/v1/oauth/tokens
|
| Users (create, retrieve, update, delete, search, custom fields, custom app assignments) |
Paths starting with /api/v2/user_profiles
|
| Retrieve integrated apps assigned to a user |
/api/v1/data/user_profiles/{uuid}/apps
|
| Integrated apps and custom apps |
Paths starting with /api/v1/data/integrated_apps or /api/v1/data/tracked_apps
|
| Work Locations |
Paths starting with /api/v1/work_locations
|
| Departments |
Paths starting with /api/v1/departments
|
| Devices |
Paths starting with /api/v1/devices
|
Employment Status Values
When the user API was migrated from the old API (v1) to the current version, the employment status values changed as shown below. If you use a program created for the old API (v1), map the values accordingly.
| Label on Screen | Old API (v1) | Current API (v2) |
|---|---|---|
| Pre-onboarding |
ONBOARDED_INITIATED
|
INITIATED
|
| Active |
ONBOARDED
|
ACTIVE
|
| On Leave |
TEMPORARY_LEAVE
|
SUSPENDED
|
| Terminated |
OFFBOARD_INITIATED
|
TERMINATED
|
| Unknown |
UNKNOWN
|
UNKNOWN
|
| Deleted |
DELETED
|
DELETED
|
| Others |
OTHERS
|
OTHERS
|
Frequently Asked Questions
-
Q: Can I issue an API key with restricted permissions, such as read-only?
There is no feature for setting a scope such as read-only for each API key. The permissions of the administrator account that issued the API key apply to it as is.
Note that the member and device APIs, including data retrieval, require the issuing administrator account to have the User Admin and IT Device Admin permissions (with CSV download). API keys issued with Viewer permissions or "No CSV Download" permissions return a 403 error. -
Q: Does the Josys API have rate limits?
As a guideline, the limit is approximately 4 requests per second per organization. -
Q: How current is the data retrieved through the Josys API?
The API retrieves the latest data stored in Josys at that point in time. Because it retrieves the same data that is shown on the admin console, information imported from integrated apps depends on when Josys runs an automatic or manual sync. -
Q: Is there a limit on the number of results the device search API can return?
The device search (POST /api/v1/devices/search) returns up to 25,000 of the devices that match the conditions. If more than 25,000 devices match, narrow your search conditions and retrieve the results in multiple requests.