There are two ways to integrate with SmartHR: via OAuth or via API key.For new integrations, we recommend using OAuth as it is simpler to set up.
[Important] Please check your permissions following the SmartHR specification changeWith OAuth integration, employee information can only be retrieved within the scope of the permission group of the SmartHR account used to log in at the time of integration.A SmartHR update scheduled for around August 2026 will let you manage permission settings for employee information separately for “yourself” and “others (other employees)”.As a result, please confirm that the fields Admina retrieves (name, email address, custom fields, and so on) are set to viewable for both “yourself” and “others”.How to check: In SmartHR, go to Settings > Permission Settings and check the settings of the permission group that the integration account belongs to.Note: If either one is set to not viewable, no error appears, but the affected fields stop syncing.
To integrate via API key, confirm the following items.How to Obtain Your Workspace KeyAfter logging in to SmartHR, part of the URL is your workspace key. Copy and save it.https://{workspace-key}.smarthr.jp/ (do not include https://)How to Obtain Your Access KeyThe access token is your access key. Refer to SmartHR’s documentation to issue an access token.How to Issue an Access Token
The following permissions are required: read access for employee information (/crews) and accounts (/users).
If retrieving email addresses from custom employee fields at the time of integration, read permission for the added custom employee field items is also required.
You can connect via [OAuth] or [API].a. OAuth Integration (Recommended): Click the OAuth tab and click Connect. Configure the following options as needed.
Field
Description
Custom employee field name for email address (optional)
Enter the field name shown in the red frame below. This retrieves the email address from a custom employee field. When specified, it is used as the primary address. You can enter multiple field names separated by commas, with the first field used as the primary address. Once connected, automatic matching (merging) by the custom employee field email address becomes available.
Prioritize business name display
If a business name is set in SmartHR, it will be used as the user’s display name.
b. API Key Integration: Select the [API] tab, enter the values for each field below, and click Connect.
Field
Description
Workspace name
Any string (e.g., company name)
Workspace key
The workspace key obtained in the previous step
Access key
The API key issued in the previous step
Custom employee field name for email address (optional)
Enter the field name shown in the red frame below. This retrieves the email address from a custom employee field. When specified, it is used as the primary address. You can enter multiple field names separated by commas, with the first field used as the primary address. Once connected, automatic matching (merging) by the custom employee field email address becomes available.
Prioritize business name display
If a business name is set in SmartHR, it will be used as the user’s display name.
Once the integration with SmartHR is successful, the registered user information will appear in the account list. If the integration does not complete successfully. Click Edit from the Status tab on the integrations screen and try again. If the issue persists, please contact us via chat.
