All Collections
Partnerships
How can I access the Rippling integration?
How can I access the Rippling integration?

An overview of Merge’s partnership with Rippling and instructions on how to access the integration

Pritak Patel avatar
Written by Pritak Patel
Updated yesterday

Overview

As of May 2024, Merge is the only Unified API that offers an OAuth-based connection directly from the Rippling App Shop. We’re incredibly excited to have entered into a formal partnership with Rippling to offer a premium Rippling integration to our customers. This integration facilitates a much more streamlined customer experience than in the past and opens up the potential for your product to be featured in the Rippling App Shop, increasing its visibility and reach.

This guide will outline the prerequisites and steps to access the integration and highlight what data will be accessible.

Prerequisites

To access the Rippling integration, you must be on Merge’s Professional or Enterprise plan. If you want to upgrade your plan, please contact us at [email protected] and our team will assist you.

Data availability

The Rippling integration will support these Common Models:

  • Companies

  • Employees

  • Employments

  • Groups

  • Locations

  • Time Off

For a detailed breakdown by field, please refer to our docs here.

Application process

To utilize the Rippling integration, the Merge team must submit an application to the Rippling App Shop on your behalf. The first step of that application process is a pre-vet review.

1. Submit your information for a pre-vet review

If you’re interested in using the Rippling integration, our team is here to guide you. Let your CSM know, and they will submit your company name and website to Rippling for a pre-vet decision. This early step allows us to gauge Rippling's potential approval or rejection, providing you with a clearer path forward.

Pre-vet decisions are typically made within 7 days. Please see the section below on how to interpret Rippling's decision.

2. Apply to the Rippling App Shop

If Rippling has approved the pre-vet, your CSM will work with you to gather all necessary information to apply to the Rippling App Shop. You can preview the questions here.

Please do not apply yourself. Your CSM must apply for you.

Rippling will review all applications within 7 days. Please see the section below on how to interpret Rippling's decision. While you wait for Rippling’s decision, we recommend checking the Building the integration section below for a list of technical requirements you can review now.

Interpreting Rippling’s application decision

Approvals for both the pre-vet and the Rippling App Shop application are at Rippling’s sole discretion, and Rippling may or may not choose to share any information regarding the reason(s) a particular application was approved or denied. Rippling has let us know that the outcome would be the same if you had applied for a partnership directly with Rippling.

Approved

If you are approved following both the pre-vet review and the Rippling App Shop application, your product is on track to be added to the Rippling App Shop at no charge to you. The next step is to build the integration as outlined below and have Rippling check it.

Rejected

If you are rejected during either the pre-vet review or the Rippling App Shop application, you unfortunately won’t be able to integrate with Rippling via Merge or otherwise.

Building the integration

Once your application has been reviewed and approved, Merge will receive access to the following on your behalf:

  1. A Rippling Partner Company login, which will let you build your new app listing and distribute it to customers

  2. A Rippling test company, which will allow you to install your app listing and test the integration

  3. Access to Rippling's partner documentation

Your Merge CSM will add you as a user to the items above, which you will need to complete the remaining steps.

As you build the integration, you’ll need to ensure it meets Rippling's list of technical requirements.

Because Merge automatically handles most of these requirements for you, if you complete just the steps outlined below, your integration will comply with Rippling’s technical requirements

1. Configure your app listing

Access the Rippling Partner Company portal. Under the Manage Listings table, click the arrow on the right.

Next, hit the arrow to the right again on the Listing Versions table.

Set your listing information

The first step will be to set up your listing by uploading logos and writing descriptions. You can do so by clicking Listing Information and navigating through the sub-menus.

  • Icons

  • Descriptions

  • Links

  • Media

  • Referrals

We recommend clicking through other app listings to get a feel for the type of information to include and how it will be displayed. Below is an example from Adobe. You can see other listings here.

You'll be able to view your own listing once you get to the section testing your installation flow.

Set your redirect URL

Go to Integration > Redirect to set up a redirect URL. When a customer in Rippling wishes to connect your application using your listing in the Rippling App Shop, they will be redirected to this URL when they click connect.

​You’ll want to set this URL to the page in your product where you have Merge Link embedded or where you will set up the logic to handle the Rippling redirect. See the Configure Merge Link section below for more info.

Set your scopes

  1. Go to Integration > Scopes > Add a scope

  2. You can select any of the public scopes (ones without a lock icon) you need for your use case except for the custom fields scope. Hit Continue after making your selections. Confirm your selections on the following screen.

Set your webhook URL and token

To complete Rippling's User Management requirement discussed in a later section, Merge will need to be able to listen to webhooks sent from Rippling. You'll need to configure these within your listing so they apply to all connected linked accounts.

  1. Go to Integration > Webhook

  2. Ask your Merge CSM for your organization's Webhook URL and enter it into the field in Rippling

  3. Enter any value for the Webhook token, but note it down since you'll need it later once customers connect their accounts

2. Set up the testing environment

Deploy your sandbox app

  1. Go to Testing

  2. Click Deploy sandbox app to get this application deployed and usable in your testing environment

Add your sandbox credentials in the Merge Dashboard

  1. Under Testing, click Sandbox client ID and secret

  2. Grab the URL of your testing application from the Sandbox app status page

  3. Copy these credentials and paste them into your Merge dashboard under Integrations > Rippling after checking the “I am a Rippling Partner” box.

    • OAuth App Shop Url — this URL should be in the following format:
      https://app.rippling.com/apps/PLATFORM/{APPNAME}/authorize

      • APPNAME — replace this with the last part of the sandbox app link you copied earlier. Using the example above, it would be the bold part:
        https://app.rippling.com/app-shop/app/mergedevtestingoauth0e1

      • PLATFORM — leave this as is

      In this example, the final URL you should enter is:
      https://app.rippling.com/apps/PLATFORM/mergedevtestingoauth0e1/authorize

    • OAuth Client Id — paste the sandbox client ID here

    • OAuth Client Secret — paste the sandbox client secret here

    • OAuth Redirect Uri — paste the redirect URL you entered in Rippling in the Set your redirect URL section

Test the installation flow

  1. Switch to the Admin account of your testing integration company. You can do this by navigating to the top right of the Rippling UI, and click Admin account.

  2. Go to the sandbox app link you copied earlier. You should see your app listing.

  3. Hit Connect Account and walk through the installation process. After a few steps, Rippling will redirect you to the redirect URL you set up with a few parameters attached, as detailed in their documentation.

    The most relevant bits are your code and redirect_uri parameters. In the next section, Configure Merge Link, we'll cover how to use both.

3. Configure Merge Link

Rippling customers can install your product from within your app or within Rippling, which is a different flow than other integrations offered through Merge. As a result, your Merge Link setup will need to be slightly modified.

Install initiated from Rippling

  1. Your customer will install your app by hitting the "Connect account" button on your listing in the App Shop

  2. They will be prompted with a few screens to make selections on, one of which is a scopes page they will need to agree to

  3. On the last screen of the flow, they will be redirected back to your product after hitting "Continue". The redirect will take them to the redirect URL you set up earlier.

  4. Once they log in to your product, you'll need to ensure Merge Link opens up automatically, preconfigured with the OAuth information from Rippling. To do that, you'll need to make these modifications to your current Merge Link setup:

    1. When Rippling redirects to your product, you must parse the URL to extract the variables below. Note that you may need to decode the URL before extracting the variables.

      • code

      • redirect_uri

    2. You should have your redirect page automatically open Merge Link but with a new parameter added to the API request made to Merge’s POST /link-token endpoint. Set all the parameters as you would normally, but include a new parameter, integration_specific_config, as shown below. Enter the code retrieved earlier as the oauth_code.

      {
      "end_user_email_address": "[email protected]",
      "end_user_organization_name": "Test Organization",
      "end_user_origin_id": "12345",
      "categories": [
      "hris",
      "ats"
      ],
      ...
      "integration_specific_config": {
      "rippling": {
      "oauth_code": "3h1jj8ssdf31dfji3o1jjdfjasd"
      }
      }
      }

      Important: You will need to update your backend SDK to the latest version before you can use the new "integration_specific_config" field.

    3. Merge Link will open to the "Review your data permissions" screen, and your customer will just have to hit "Next" to complete the connection

  5. Rippling requires that all app installs finish in Rippling, so once your user finishes the linking flow and you retrieve the account token successfully from Merge, you’ll need to redirect back to the redirect_uri that you extracted earlier.

Install initiated from your app

With the Rippling integration enabled in your Merge Dashboard, Merge Link will show the Rippling tile in the integration selector within your product and will return via the GET /api/organizations/integrations endpoint if you've designed your own integration marketplace.

When a customer tries to initiate a connection to Rippling in your product, Merge Link will automatically redirect to your Rippling App Shop listing page.

Your customer will log in to Rippling and install your app through the Rippling App Shop. The remainder of the installation flow will be as outlined above in the Install initiated from Rippling section.

Important: For this to work, you must ensure that when Rippling redirects back to your app, a new link token is created, as explained in step 4b in Install initiated from Rippling.

4. Set up Rippling SSO

Rippling requires that all integrations, by default, support Single Sign-On (SSO) and follow all the requirements outlined in the "Rippling SAML SSO Guide".

  1. Go to your app listing and select Capabilities > Capabilities setup. Toggle on Single sign-on

  2. Select Configure Settings

  3. Select SAML on the next screen and hit Save Edits

From this point onwards, the process should be similar to a standard SSO setup, so we recommend following "Rippling’s SAML SSO Guide". While going through it, note that one requirement requires a setup related to Merge:

For this requirement, you’ll need to use a passthrough request since Merge handles the integration's authentication for you.

  1. Once your customer has connected their account through Merge, use this passthrough request to hit Rippling’s GET SAML Metadata endpoint.

    Request:

    curl --location 'https://api.merge.dev/api/hris/v1/passthrough' \
    --header 'x-account-token: <MERGE_ACCOUNT_TOKEN>' \
    --header 'Authorization: Bearer <MERGE_PRODUCTION_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
    "method": "GET",
    "path": "/saml/idp_metadata",
    "headers":{
    "Content-Type": "application/json"
    }
    }'


    Response:

    <ns0:EntityDescriptor
    xmlns:ns0="urn:oasis:names:tc:SAML:2.0:metadata"
    xmlns:ns1="urn:oasis:names:tc:SAML:metadata:algsupport"
    xmlns:ns2="http://www.w3.org/2000/09/xmldsig#" entityID="https://www.rippling.com/661ec508e8fec64240f2cf6a/idp.xml" validUntil="2034-02-23T19:16:31Z">
    <ns0:Extensions>
    <ns1:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#md5" />
    <ns1:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#ripemd160" />
    <ns1:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
    <ns1:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha224" />
    <ns1:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
    <ns1:DigestMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#sha384" />
    <ns1:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha512" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2009/xmldsig11#dsa-sha256" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha224" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-md5" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-ripemd160" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha224" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha384" />
    <ns1:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha512" />
    </ns0:Extensions>
    <ns0:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" WantAuthnRequestsSigned="false">
    <ns0:KeyDescriptor use="signing">
    <ns2:KeyInfo>
    <ns2:X509Data> <ns2:X509Certificate>MIICfTCCAeYCA2JRIzANBgkqhkiG9w0BAQsFADCBhDELMAkGA1UEBhMCVVMxCzAJ
    BgNVBAgMAkNBMQswCQYDVQQHDAJTRjERMA8GA1UECgwIUmlwcGxpbmcxLTArBgNV
    BAsMJE1lcmdlIElOVENPIG1lcmdlZGV2dGVzdGluZ29hdXRoMGUxMTEZMBcGA1UE
    AwwQd3d3LnJpcHBsaW5nLmNvbTAgFw0yNDA0MTYxOTE2MjlaGA8yMTI0MDMyMzE5
    MTYyOVowgYQxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTELMAkGA1UEBwwCU0Yx
    ETAPBgNVBAoMCFJpcHBsaW5nMS0wKwYDVQQLDCRNZXJnZSBJTlRDTyBtZXJnZWRl
    dnRlc3RpbmdvYXV0aDBlMTExGTAXBgNVBAMMEHd3dy5yaXBwbGluZy5jb20wgZ8w
    DQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKQFauSE8mCNEQLBvOuhFe1jOMDd0nIM
    zmni/F2JIoux6GCrlCvD7sjnf+j/3/UWhM5oXQg9Ks9/Oks2JXxGfqTHDmR7u+iE
    EGqgJL3QR/TBND/BqByCZxsc3917AF7Gg65Mgn/2cZ5bzcytsaUHqXYg22SN3fvH
    Fd6i3+gxbVzlAgMBAAEwDQYJKoZIhvcNAQELBQADgYEAmWSDoVK2SIv1WBWAzrSt
    uq5aH5FiblttEd8iFiz5fcSsy2bFIXAhmynOXto7S8rAwYs/C8otP4Ki5SYTGpXK
    WC6FoxDJAOOHR8qjj2+25FxEuMCW+nGV8FMTlzcKmDUfFS9t22w1F7Pm0waSfbYZ
    WAJJxMteadz67Z7KTDaqBZY=
    </ns2:X509Certificate>
    </ns2:X509Data>
    </ns2:KeyInfo>
    </ns0:KeyDescriptor>
    <ns0:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://www.rippling.com/api/platform/sso/sp-initiated/661ec508e8fec64240f2cf6a" />
    <ns0:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://www.rippling.com/api/platform/sso/sp-initiated/661ec508e8fec64240f2cf6a" />
    </ns0:IDPSSODescriptor>
    <ns0:Organization>
    <ns0:OrganizationName xml:lang="en">Rippling</ns0:OrganizationName>
    <ns0:OrganizationDisplayName xml:lang="en">Rippling</ns0:OrganizationDisplayName>
    <ns0:OrganizationURL xml:lang="en">https://www.rippling.com</ns0:OrganizationURL>
    </ns0:Organization>
    <ns0:ContactPerson contactType="support">
    <ns0:GivenName>Support</ns0:GivenName>
    <ns0:EmailAddress>[email protected]</ns0:EmailAddress>
    </ns0:ContactPerson>
    </ns0:EntityDescriptor>

  2. From the response, access the customer’s entityID, X509Certificate, and SingleSignOnService URL, which are referenced in Rippling’s general guide

5. Set up user management

Rippling requires that all integrations, by default, support User Management and follow all the requirements outlined in the "Rippling User Management Guide".

Go to your app listing and select Capabilities > Capabilities setup. Toggle on User Management. Note this may already be turned on if you followed the SSO section above.

From this point onwards, we recommend reading through the "Rippling User Management Guide" to understand each requirement. Outlined below is guidance on how you can achieve each of the requirements through Merge:

Merge already supports webhooks for Rippling’s employee.created and employee.deleted events, but you will need to configure these for each Rippling linked account. Rippling doesn't currently support the programmatic configuration of these webhooks.

Configure the third-party webhook

  1. Once a linked account is connected, go to your Merge Dashboard under Linked Accounts > Select the linked account > Webhooks > employee.created

  2. Enter the Webhook Token you entered in the Rippling partner portal in the Set your webhook URL and token section as the Signature Key

  3. Hit Enabled to toggle the webhook on

  4. Repeat the same process for the employee.deleted webhook

Configure the Merge webhook

Now that Merge is receiving webhooks from Rippling, you can subscribe to Merge’s webhooks to receive these updates:

  1. Create a new Merge webhook here.

  2. Subscribe to the Changed data webhook for Employee Created and Updated events

New Merge field

Merge has added an org-wide field mapping automatically set up each time a Rippling linked account is connected:

Target Field Name: is_rippling_provisioned

You won't see this target field in the Merge dashboard, and it won't be editable, but when you hit Merge’s GET /employees or receive a webhook via the Employee.created or Employee.updated events for a Rippling linked account, you’ll see the following returned as part of the regular response body:

"field_mappings": {
"organization_defined_targets": {
"is_rippling_provisioned": "true/false"
}
}
...

When this field is marked "true", it represents an employee that should have provisioned access to your app. If marked "false", this is an employee in Rippling that should not have access to your app. You should use this field to provision and deprovision users within your product.

As long as you are on Merge’s daily or highest sync plans, you should already update all employee data every 24 hours or more frequently. You should additionally use the new is_rippling_provisioned field to provision and de-provision users within your product during these recurring syncs.

Note that this requirement is optional. If you want to implement it, you can have a button in your UI hit Merge’s force resync endpoint.

You should use the new is_rippling_provisioned field to provision and de-provision users within your product instead of any other field you may be using for other integrations.

Merge stores third-party system IDs in each common model's remote_id field. In this case, we recommend storing the remote_id of employees along with the rest of the data you need for your use case.

Integration review

Once you’ve tested your integration and think it is ready for Rippling to review, hit the Complete form button in the Rippling Partner Company portal.

Verify that your integration meets all the requirements on the following screen by checking off each one. Then, hit Complete & submit listing to submit your listing for Rippling’s review.

Please let your Merge CSM know once you’ve submitted your listing so we can track the approval process with Rippling.

Beta testing

Once Rippling has reviewed your integration, you will proceed to testing, where shared customers can install your app and test the integration using their Rippling companies.

Before testing with live customers, make sure you swap out your partner credentials in the Merge dashboard under Integrations > Rippling for the production equivalents. Your production credentials in Rippling are in the app portal under Integration > Credentials > Production.

Here's how you should fill them out in the Merge dashboard:

  • OAuth App Shop Url — After your app shop listing's approval, you'll get a URL from Rippling for the production listing. What you enter into Merge needs to be in the following format:
    https://app.rippling.com/apps/PLATFORM/{APPNAME}/authorize

    • APPNAME — replace this with the last part of the production listing URL you get from Rippling. It would be the bold part in the example below:
      https://app.rippling.com/app-shop/app/mergedevtestingoauth

    • PLATFORM — leave this as is

    In this example, the final URL you should enter is:
    https://app.rippling.com/apps/PLATFORM/mergedevtestingoauth/authorize

  • OAuth Client Id — paste the production client ID here

  • OAuth Client Secret — paste the production client secret here

  • OAuth Redirect Uri — paste the redirect URL you entered in Rippling in the Set your redirect URL section

Launch

Once testing is completed and the integration receives approval from the Rippling team, the application will be made publicly visible and searchable in the Rippling App Shop.

A beta tag will be attached to all applications when they are initially launched. The beta tag will be removed if either of the following conditions are met:

  • The app receives 5 or more installs

  • The app has been live for a month or longer

Important notes

  • Uninstalls — Rippling doesn't currently provide a way to support uninstalling a Rippling app via API. The admin in your customer's Rippling account is the only person who can uninstall the application. This means if a linked account is deleted in Merge, you'll need to have your customer also delete the application in Rippling. And, if the application is deleted in Rippling, your end user should request the linked account be deleted in Merge. You can delete linked accounts in Merge via the Merge dashboard or by using the POST /delete-account endpoint.

  • End-user fees — Rippling will still require your customers to purchase its "app package" to connect any apps from the Rippling App Shop. Note that this is a fee to access all apps, not a specific fee for this integration. For the most accurate information on pricing, we recommend your customers reach out to their Rippling representative.

  • To see more information and FAQs, refer to Rippling’s documentation here.

Did this answer your question?