Overview

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

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, your CSM will set up a meeting to go through the remainder of the process.

In addition, they will share the following items which you will need to complete the remaining steps:

Rippling Sandbox OAuth Credentials
Your Webhook Token
The URL for your Sandbox App Shop Listing
Logins for the Rippling Parter Portal and Test Company

1. Configure your app listing

Access the Rippling Partner Company portal here. 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.

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 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.

2. Set up the testing environment

Add your sandbox OAuth credentials in the Merge Dashboard

Under Testing, click Sandbox client ID and secret
Grab the URL of your testing application from the Sandbox app status page
Copy these credentials and paste them into your Merge dashboard under Integrations > Rippling after checking the “I am a Rippling Partner” box.

Test the installation flow

Switch to the Admin account of your testing integration company, as shown below
Go to the sandbox app link your CSM shared with you. You should see your app listing.
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

Your customer will install your app by hitting the "Connect account" button on your listing in the App Shop
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
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.
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 a "Connect your account" screen, where your customer will agree to Merge's End User Terms. Once they hit "Next," the connection is complete.
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.

Go to your app listing and select Capabilities > Capabilities setup
Select Configure Settings
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:

REQ19: Automated retrieval of SAML Metadata from Rippling

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

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"
    }
}'

The response from the passthrough request (shown below) will be compressed as a BASE64_GZIP. You'll need to uncompress the response field to get the final output.

From the final output response (in XML shown below), access the customer’s entityID, X509Certificate, and SingleSignOnService URL, which are referenced in Rippling’s general guide.

<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>

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. We recommend reading through each requirement. Outlined below is guidance on how you can achieve each through Merge:

REQ12: A webhook listener to update your system upon receipt of a webhook.

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

Once a linked account is connected, go to your Merge Dashboard under Linked Accounts > Select the linked account > Webhooks > employee.created
Enter the Webhook Token your CSM provided you as the Signature Key
Hit Enabled to toggle the webhook on
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:

Create a new Merge webhook here.
Subscribe to the Changed data webhook for Employee Updated events. For specific fields, select field_mappings

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.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.

Important considerations:

remote_data needs to be turned on for the Employee Common Model for this new field to show up.
Rippling does not send webhooks for sandbox accounts.

REQ13: At least a 24-hour scheduled sync that updates all employee details (can be more frequent).

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.

REQ14: A manual sync button in your software to update all employees within your app from Rippling at any time.

Have a button in your UI hit Merge’s force resync endpoint.

REQ15: Users should only be provisioned when a webhook event is received or an employee is returned from GET/Employees. Users should NOT be provisioned based on the employee start date.

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.

REQ16: Automated employee matching.

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 to review, let your CSM know, and they will schedule a meeting to verify the requirements have been met. Together you'll submit your app listing to Rippling for final review.

Please do not submit your integration for review without meeting with your CSM first.

Beta testing

Once Rippling has reviewed and approved your integration, you will proceed to beta testing, where shared customers can install your app and test the integration using their production 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.

OAuth App Shop Url — your production App Shop URL will be provided by your CSM and look something like this:

https://app.rippling.com/app-shop/app/acme

Add "/authorize" to the end of it and enter that into this field. In this example, the final URL should be:

https://app.rippling.com/app-shop/app/acme/authorize
OAuth Client Id — paste the production client ID here. You can find this on your listing page under beta testing (see screenshot)
OAuth Client Secret — paste the production client secret here. You can find this on your listing page under beta testing (see screenshot)
OAuth Redirect Uri — this should remain the same as what was used during testing

Final steps

Please refer to Rippling's app listing workflow docs to learn more about the beta testing phase and what comes after.

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.
Fees — Merge covers the cost of partnering with Rippling, so there are no additional fees for you. However, Rippling will still require your customers to purchase its "app package" to access apps from the Rippling App Shop. Note that this fee is Merge-agnostic. For the most accurate information on pricing, we recommend your customers reach out to their Rippling representative.
Adding more admins to your test company - follow this video guide
To see more information and FAQs, refer to Rippling’s documentation here.

Beta Integrations

How do I prepare to onboard my customers?

Webhooks Migration Guide

How do I change requested scopes for OAuth integrations?

What error codes can I expect from Merge and how do I handle them?