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, Admina reads employee information through the SmartHR account used to log in. It sees only what that account’s permission group allows.A SmartHR update planned for around August 2026 splits these permission settings in two. You will manage employee information separately for “yourself” and for “others (other employees)”.Please confirm that the fields Admina retrieves are viewable for both. This covers name, email address, custom fields, and so on.To check this, open Settings > Permission Settings in SmartHR. Review 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.
For details on the fields synced from SmartHR, please refer to SmartHR Plus.You can set SmartHR as the data source for the employment period start and end dates in Directory Settings. In that case, Admina uses these SmartHR fields:
Start date: the contract start date, or the joining date if it is blank
End date: the contract end date, or the resignation date if it is blank
