Import Users with a Custom API Integration

Seamlessly onboard new users and sync user updates from your organization’s user identity source of truth - applications such as HRIS, HCM, compensation, and benefits solutions. Create efficiencies for IT and HR by reducing manual overhead and security concerns related to manual data entry and access based on outdated user data.

If you do not see an integration available in the list of HR Directories, Cloud Directories, or application integrations in the Admin Portal, you may be able to create an integration using a custom API integration. Read this article to learn how to configure a custom API integration.

Prerequisites

  • An account with sufficient privileges and scopes to make API calls to the application and to the specific endpoints that will be used for the integration.
  • Detailed REST API documentation for the application that includes the information needed to complete the configuration.
  • Verification that the application API meets the following requirements:
    • Supports API Key, Bearer Token, or OAuth 2.0 authorization code as the authentication method.
    • Supports offset pagination (limit/offset).
    • Accepts JSON requests and returns JSON responses.
    • Has an endpoint that lists all the employees or users and returns the full schema (not a list of ids or a single value).

Important:

This feature is a generic/custom option that has a high likelihood of allowing you to create an integration with applications that meet the requirements noted above, but there may be situations where this option cannot be used.

Considerations

  • An SSO configuration is recommended, not required.
  • A custom API option is provided on all applications that do not have a pre-built identity management integration for convenience. Having this option should not be interpreted as a validation that the application has a REST API or that an integration can be successfully configured. 
  • An integration cannot be created for any application with a custom REST API that:
    • Requires multiple custom headers.
    • Does not return the full schema for the list users endpoint. (e.g., only ids are returned)
    • Returns responses in any format other than JSON.
    • Requires the following authentication methods: OAuth 2.0 basic auth header, client credentials, refresh token, or authorization code with PKCE.
  • Partial configurations are not saved even if the application is saved.
  • The timestamp in the User Import Complete email is UTC.
  • See Troubleshooting below for a list of HRIS solutions for which a custom API integration cannot currently be used to create an integration.

Creating a New Application Connector

Note:

Skip to the next section if you have already configured the application connector.

  1. Log in to the JumpCloud Admin Portal.
  2. Navigate to USER AUTHENTICATION > SSO Applications.
  3. Enter the application name in the Search field:
    • Search for the application in the catalog, and select it.
  4. If the application does not exist in the catalog:
    • Click + Add New Application, select Custom Application and click Next.
  5. Select one of the following and click Next:
    • Import Users from this app (Identity Management).
    • Export users to this app (Identity Management).
    • Add a bookmark (no SSO)
  6. Enter a Display Label.
  7. Enter a Description (optional).
  8. Choose a Display Option (optional).
  9. If this is a bookmark application, enter the URL in the Bookmark URL field.
  10. Select whether to hide or Show in User Portal.
  11. Click Save Application.

Creating a New Identity Management Custom API Integration

  1. Create a new application or select it from the Configured Applications list.
  2. Select the Identity Management tab.
  3. Under Configuration settings > Service Provider Configuration > API Type, choose Custom API.
  4. Select the appropriate Authentication Method:

Authentication Method Configuration

Bearer Token configuration

  1. Enter the Base URL.

Tip:

This information will be located in the REST API documentation for the application.

  1. Follow the service provider’s instructions for generating the token.
  2. Enter the token in the Token Key field.

API Key configuration

  1. Follow the service provider’s instructions for generating the API Key.
  2. Enter the Header name.
  3. Enter the Header value which will include the API Key.
  4. Enter the Base URL.

Tip:

The Header name, the format for the Header value, and Base URL will be located in the REST API documentation for the application.

OAuth 2.0 configuration

  1. Follow the service provider’s instructions for generating the Client ID and Client Secret.
  2. Enter values in the following required fields:
    • Authorization URL
    • Client ID
    • Client Secret
    • Access Token URL
  3. If needed, enter values in optional fields:
    • Revoke URL
    • Scopes

Tip:

If multiple scopes need to be specified, separate each scope with a space.

  1. If successful, you will be redirected to the Service Provider’s page. Click Authorize.
  2. You will be redirected back to the Identity Management tab in your Admin Portal.

Endpoint Configuration

Fill out the required fields specific to your configuration.

Tip:

This information will be located in the REST API documentation for the application.

  1. Base URL – Enter the Service Provider’s Base URL.
  2. List Users:
    • Location:
      • Resource Location – Enter the JSON path for the location of the user or employee object in the API response.
        • If the user array is the root, then the path is “.”.
        • If the user array is a field in the root “fieldname”. Example: users
        • If it’s a nested field “fieldA.fieldB…fieldname”. Example: data.resources.users
      • Method – This field is greyed out (not changeable) and is always set to GET.
      • Endpoint Path – Enter the relative URL used to request the entire list of users from the application in the field.

Note:

This value will be appended to the Base URL. Common examples include: /profiles, /employees, or /users.

  1. Total count:
    • Response Parameter Location – Select the appropriate value from the dropdown.
      Note: Review the REST API documentation to determine if the total number of records returned by the API request, often referred to as total count, is included in the header or the body of the response and what the header name or JSON path, respectively, is for that value.
    • If the total count value is returned in the body, enter the json path for the property in in the Response Body JSON Path fieldExample: meta.total_count. 
    • If the total count is returned in the header, enter the header name where the total count will be returned in the Response Header Name field. Example: X-Total-Count.
      Note: If the total number of records is not returned by the service provider, then you can enter a value such as “na”.
  2. Pagination:
    • Limit Name – Enter the parameter name used to control how many results are returned per request from the List endpoint in the field. Common names for this parameter include limit, per_page.
    • Offset Name – Enter the parameter name used to specify on which result to start in the total number of returned results field. Common names for this parameter include offset, skip.
  3. For API Key and Bearer Token Configurations, select Test Connection.
    • If successful – you will receive a success message and the fields for attribute mapping will appear.
    • unsuccessful – you will receive a failure notification that slides out from the right of the panel and the full error responses received from the service provider will be shown at the bottom of the Configuration Settings section.

Tip:

You can share the error message(s) with the service provider of the application to troubleshoot the issue.

Note:

Some integrations will not be possible using this configuration template. Please work with the service provider to verify if an integration is possible based on the considerations noted above and the information requested in this integration.

User Schema Attribute Mapping

  1. Complete the 2 required mapping fields:
    • Company email
    • Username

Important:

You will not be able to preview your schema until the two required mapping fields are completed.

Tip:

You can click Preview to see the full user schema returned by the service provider of the application. You can copy the response into a file and use that as reference for the optional mappings.

  1. Complete the optional mappings.

Tip:

It is highly recommended to map all the listed Optional JumpCloud attributes. The dropdown shows all other user attributes that can be mapped to create a complete user profile.

  1. Click Preview to see how the mappings will be applied in JumpCloud.

Tip:

You can drag the bottom right corner of each section to see the entire schema.

  1. Click ok to close the User schema preview window.
  2. Click Activate.
  3. If successful, you will receive a message saying the Identity Management integration has been successfully verified.
  4. Click save.

Importing New Users and Updates

To import users with the JumpCloud Admin Portal

  1. Create a new application or select it from the Configured Applications list.
  2. Select the Identity Management tab.
  3. There are several settings available for importing users from your custom application to JumpCloud. Warning: Selected import options will apply to both manual and scheduled imports. 
    • Expand the Import Users section.
      • Manual Import – clicking the Start Manual Import button kicks off the process flow for doing an immediate and one-time import of users from your custom application to JumpCloud. 
      • Scheduled Imports (hourly) – enabled by default for all new connectors. The first scheduled import will start within an hour after the new connector is saved. Scheduled imports will then run at the same time every hour as the initial scheduled import. Important: Any connectors created prior to the availability of scheduled imports will have this option disabled. To run scheduled imports, you must enable this option.
      • Selecting the Receive summary email after each scheduled import results in user import complete emails being sent after each hourly import. Tip: It’s recommended to enable this for the first few scheduled imports to ensure the imports are running correctly. 
    • In the Import Settings section, you can optionally choose:
      • Allow reactivation of users on update. Checking the box for this setting will result in the user state changing from Suspended to Active in JumpCloud when a user’s status changes from either Leave or Inactive to Onboarding or Active in your custom application.  
      • Apply Advanced Filters on import (optional). See your custom application’s API documentation for available filters,.

To start a manual user import

  1. Expand the Import Users section and click Start Manual Import.
  2. Select one of the following options: 
    • Import new users and user updates
    • Only import new users
    • Only import user updates
    • View and select specific new users to import (updates not supported)

Note:

If the option selected includes user updates, the following will occur:

  • Any and all changes made to the mapped user attributes in the source application will be made in JumpCloud.
  • Users whose statuses change to one of the defined inactive status will be automatically suspended in JumpCloud.
  • If Allow reactivation of users on update is checked, suspended users in JumpCloud, whose status change from the defined inactive statuses to ones that are not defined as inactive, will have their user state changed back to Active in JumpCloud.
  1. Click Continue.
  2. If you selected the View and select specific new users to import (updates not supported).
    • Select the users you want to import.

Note:

Free accounts can import unlimited users, but will be prompted to upgrade to a paid subscription after 30 days. Similarly, accounts managed by an MSP, that have a license limit, are only allowed to import users up to their license limit and will be prompted to contact their provider once that limit is reached.

  1. The count of users to be imported will show at the bottom left hand of the list. If this is correct, click Import
  2. Review the information in the results modal.
  3. Click one of the tiles to navigate to the Users page, User Groups page, or Device Groups page or close the modal.​

Note:

If you close this modal, you will return to the Identity Management configuration panel.

  1. You will receive a User Import Complete email with a summary of the import results and a link for downloading a copy of the import results.
  2. You can now connect users to all their JumpCloud resources. Learn more in the Authorize Users to an SSO App and Connect New Users to Resources articles.

Note:

Imported users must be members of a user group bound to an application  for JumpCloud to manage their identity in and access to the application.

To import users with the JumpCloud API

Note:

The import flow using this new API endpoint will only create new users who have an active status in your custom application. By default, Leave and Inactive are considered inactive statuses and Onboarding and Active are considered active statuses. See Documentation for this API endpoint.

  1. Get the application ID for your integration. There are 2 ways:
    • Retrieve the application ID from the JumpCloud Admin Portal:
      • Log in to JumpCloud Admin Portal.
      • Go to USER AUTHENTICATION > SSO Applications.
      • Open your custom application by clicking on it.
      • Note the ID from the URL which is just before “/details”: https://console.jumpcloud.com/#/sso/{222220da1f777fbe7502cde}/details
    • Retrieve the application ID by making a GET /applications request:

curl command example:   

curl --request GET \
--url 'https://console.jumpcloud.com/api/applications?fields=id&filter=displayLabel:$eq:Personio' \
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --header 'x-org-id: REPLACE_ORG_ID_VALUE'

  1. To do a manual import, make a POST /applications/{application_id}/import/jobs request using the application ID from the preceding steps.

curl command example for importing new users and user updates with reactivation of users allowed:

curl --request POST \
--url 'https://console.jumpcloud.com/api/v2/applications/{application_id}/import/jobs' \
 --header 'accept: application/json' \
  --header 'Content-Type: application/json'\
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --header 'x-org-id: REPLACE_ORG_ID_VALUE'\

--data '{ 
      "allowUserReactivation": true, 
      "operations": [ 
    "users.create", 
         "users.update" 
    ]
  }'

curl command example for importing only user updates:

 curl --request POST \
--url 'https://console.jumpcloud.com/api/v2/applications/{application_id}/import/jobs'
 --header 'accept: application/json' \
  --header 'Content-Type: application/json'\
  --header 'x-api-key: REPLACE_KEY_VALUE' \
  --header 'x-org-id: REPLACE_ORG_ID_VALUE'\

--data '{
      "allowUserReactivation": true,
      "operations": [
         "users.update"
      ]
  }'

  1. To run scheduled hourly imports:

curl command that allows reactivation, sends an advanced import filter, and sends the user import complete email after the hourly sync occurs:

curl --request POST \
  --url https://console.jumpcloud.com/api/v2/applications/{applicationObjectId}/import/schedules \
  --header 'content-type: application/json' \
  --data '{"allowUserReactivation":true,"operations":{"userCreate":true,"userUpdate":true},"query":"string","sendEmail":true}'

Updating a Custom API Connector

  1. Log in to the JumpCloud Admin Portal.
  2. Navigate to USER AUTHENTICATION > SSO Applications.
  3. Open the application by clicking on it.
  4. Select the Identity Management tab.
  5. Make the desired changes in the Configuration Settings section.

Note:

If you are using OAuth 2.0 authentication and have changed the credentials or URL, you will need to complete the Authorization flow before the changes will be saved.

  1. Click update.

Deactivating the Custom API Integration

Note:

Deactivating deletes the Custom API integration between JumpCloud and the application. All users are left as-is on both systems.

  1. Log in to the JumpCloud Admin Portal.
  2. Go to USER AUTHENTICATION > SSO Applications.
  3. Search for the application that you’d like to deactivate and click to open its details panel. 
  4. Under the company name and logo of the left hand panel at the very bottom, click the Deactivate IdM connection link.
  5. Click confirm to deactivate Identity Management for the application. 

Troubleshooting

See Troubleshoot: Custom API Integrations.

List IconIn this Article

Still Have Questions?

If you cannot find an answer to your question in our FAQ, you can always contact us.

Submit a Case