Contact Us
Help Center Home > Apps and Integrations > Integrate with Rippling Using a Custom API Connector (Preview)

Integrate with Rippling Using a Custom API Connector (Preview)

Automatically provision, update and deprovision users in JumpCloud from Rippling using the Identity Management integration. Leverage this integration to centralize user lifecycle and identity management in JumpCloud based on user data coming from Rippling. Save time and avoid mistakes, as well as potential security risks, related to manually creating and updating users.

Add options to use existing connector or create new one.

Configuring the Identity Management Integration

To generate a Rippling API Token

  1. Log in to Rippling as an admin for your organization.
  2. Select Tools >Developer.
  3. Navigate to API Tokens.
  4. Click Create API Token.
  5. Enter a clear, descriptive name (e.g., JumpCloud Integration)
  6. Click Continue.
  7. Specify the specific permissions (scopes) you want to give based on the data you want to import from Rippling to JumpCloud: 

Note:

These are the suggested scopes based on our suggested API endpoint and mappings. See the Scopes Details section of the Rippling API documentation for more information about the available scopes to determine which are most appropriate for your integration. 

  • companies.read
  • departments.read
  • employment-types.read
  • job-codes.read
  • job-dimensions.read
  • legal-entities.read
  • levels.read
  • teams.read
  • users.read
  • work-locations.read
  • workers.read
  • workers.sensitive.personal.read
  1. Click Save.
  2. Copy the API Token and store it securely. 

Warning:

The Client ID and Secret (token) may only be shown once. Copy them to a secure location, like the JumpCloud Password Manager, for future reference.

To create a new custom application in JumpCloud

  1. Log in to the JumpCloud Admin Portal.
  2. Navigate to DIRECTORIES > HR Directories Integrations
  3. Select Create Custom Application
  4. Click Next
  5. Select Import users from this app (Identity Management) if you don’t want users to log in to Rippling with their  JumpCloud credentials or 
  6. Click Next
  7. Enter the name for your integration in the Display Label field
  8. Optionally, if you don’t want the integration to show for your users, you can uncheck the Show this application in User Portal option.
  9. Click Save Application
  10. Click Configure Application

To configure the custom API import integration

Note:

Reference the Rippling REST API documentation.

  1. Expand Configuration settings
  2. Select Custom API Import for API Type
  3. Select or enter the following:
    • Use mTLS: Leave unchecked
    • Authentication method: Select Bearer Token
    • Base URL: Enter https://rest.ripplingapis.com
    • Enter the API Token generated in the previous section
    • Endpoint configuration:
      • Resource location: results
      • Endpoint path: /workers
    • Pagination:
      • Pagination Type: Cursor-based
      • Cursor Count Parameter: limit
      • Cursor Field Parameter: cursor
      • Cursor Field JSON Path: next_link
  4. Check the box for Cursor field is a link 
  5. Click Test Connection to verify credentials and the configuration.
  6. If the connection test was successful, the Attribute Mapping section will be displayed. 
  7. Update Endpoint path to /workers?expand=user,manager,employment_type,department,legal_entity,custom_fields to have more complete user information included in the sync.

Note:

The expand query parameters listed here are suggestions based on our recommended attribute mappings. Always refer to the official Rippling API documentation (specifically the Query Parameters > Expand section) to make a final decision on which to include. Your choice of expand parameters should only include the ones needed based on the final attribute mappings you define to ensure only the necessary data is retrieved for your JumpCloud integration. 

User Schema Attribute Mapping

  1. Expand the Attribute Mapping section
  2. Update the first section of the User Schema Attribute Mapping section:
    • Unique id: id
    • User Status status
    • Inactive Status Values: INIT, HIRED, TERMINATED

Mapping Table

Use the example response from the List Workers endpoint in the Rippling API documentation to determine which attributes you want to map. Some suggestions are provided in the table below. 

Required Mappings

JumpCloud AttributeService Provider AttributeNotes
Company Emailwork_email
Usernamework_emailThere is logic that automatically extracts everything before the ‘@’ in the email address and sets that as the username

Optional Mappings

JumpCloud AttributeService Provider AttributeNotes
Display Name{{ or .user.name.preferred_given_name .user.name.given_name }} {{ or .user.name.preferred_family_name .user.name.family_name }}
First Name (suggested){{ or .user.name.preferred_given_name .user.name.given_name }}Expression that will store the person’s preferred given (first) name if populated. Otherwise, it will store the person’s legal first name. 

To use an expression, click the more option at the end of the field (the stacked ellipses) and select “Add Expression”
Last Name (suggested){{ or .user.name.preferred_family_name .user.name.family_name }}Expression that will store the person’s preferred family (last) name if it is populated. Otherwise, it will store the person’s legal family (last) name.

To use an expression, click the more option at the end of the field (the stacked ellipses) and select “Add Expression”
Middle Nameuser.name.middle_name
Alternate Email (suggested)personal_email
Location (suggested)location.type
Manager Email (suggested)manager.work_email
Employee Identifier (suggested)number
Employee Type (suggested)employment_type.label
Job Title (suggested)title
Work Phone{{range .user.phone_numbers}}{{if (eq .type "WORK")}}{{ .value}}{{end}}{{end}}Expression that searches the phone_numbers array in the user object for the work phone number and stores it if populated.
Company (suggested){{ or .legal_entity.company.doing_business_as_name .legal_entity.company.legal_name}}Add Expression OR type the name of your company
Department (suggested)department.name
Work Cell Phone{{range .user.phone_numbers}}{{if (eq .type "MOBILE")}}{{ .value}}{{end}}{{end}}Expression that searches the phone_numbers array in the user object for the mobile phone number and stores it if populated.
Work Countrycountry
Home State{{range .user.addresses}}{{if (eq .type "HOME")}}{{ .region}}{{end}}{{end}}Expression that searches the addresses array in the user object for the region value of user’s home address and stores it if populated.
Home City{{range .user.addresses}}{{if (eq .type "HOME")}}{{ .locality}}{{end}}{{end}}Expression that searches the addresses array in the user object for the locality value of user’s home address and stores it if populated.
Home Country{{range .user.addresses}}{{if (eq .type "HOME")}}{{ .country}}{{end}}{{end}}Expression that searches the addresses array in the user object for the country value of user’s home address and stores it if populated.
Home Street Address{{range .user.addresses}}{{if (eq .type "HOME")}}{{ .street_address}}{{end}}{{end}}Expression that searches the addresses array in the user object for the street address value of user’s home address and stores it if populated.
Home Postal Code{{range .user.addresses}}{{if (eq .type "HOME")}}{{ .postal_code}}{{end}}{{end}}Expression that searches the addresses array in the user object for the postal code value of user’s home address and stores it if populated.

Expressions

You can use expressions to manipulate the information before storing it in JumpCloud. Read Use Expressions in Custom API Import Integrations to learn more about expressions.  

To preview Mappings 

Use this option to see the values being returned from Rippling and what values will be set in JumpCloud. 

  1. Click Preview Mappings
  2. Add query parameters supported by Rippling to return certain records and click Update Preview.
    • For example, enter filter=work_email+eq+'your.name@company.com' to do the preview for a specific user
  3. Click Close
  4. Edit the mappings as needed
  5. Repeat these steps until the results meet your requirements

To activate the Integration

Once you are satisfied with the attribute mappings, click Activate. 

Importing Users

To verify the Integration

Important:

Before you import more than a few test user, you will need to provide your integration app id to your Customer Success Manager or open a case with Customer Support and ask them to have engineering enable the Rippling integration bulk import functionality. The app id will be found at the end of the URL when you have the integration configuration page open.

Perform a manual import to verify the integration

  1. Expand the Import Users section 
  2. Check the box for Apply advanced filters on import (optional)
    • If you want to test by importing a specific users, append the following to the value in the Import Filter field: filter=work_email+eq+'your.name@company.com'
      • Replacing the example email address with the actual email address of the user you want to import.
      • Reference the List Workers API documentation for a complete list of filters you can use. 
  3. Click Start Manual Import
  4. Select the last option View and select specific new users to import (updates not supported)
  5. Click Continue
  6. Select a new user to import
  7. Click Import
  8. Verify the user was imported and had all the attributes you mapped
  9. Follow the steps above and choose the other import options to do manual bulk imports

To enable Scheduled Imports

Once you are comfortable with how the integration is working, you can enable the scheduled sync. 

  1. Expand the Import Users section 
  2. If you haven’t already, add the import filters
    • If you want to test by importing a specific users, append the following to the value in the Import Filter field: filter=work_email+eq+'your.name@company.com' to bring in a specific user
      • Replacing the example email address with the actual email address of the user you want to import
      • Reference the List Workers API documentation for a complete list of filters you can use
  3. Toggle the Schedule hourly imports of users and user updates from SAML2.0 (disabled) to enable hourly imports.
  4. If you want to receive an email every time the import runs, check the box for Receive summary email after each scheduled import:
    • If you prefer not to get so many emails, the import results can be accessed by clicking the Import Results link, from the Scheduled User Import Errors (past 24 hours) widget on the Home Page, or in Directory Insights
Back to Top

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