What are platform integrations?
This feature allows institutions to connect their Mainstay data to a third-party platform, such as Hubspot. This enables a 2-way sync of contact record data, including default fields (name, phone, email, etc.) and custom fields created by the partner. To learn more, visit Platform Integrations.
Add an integration instance
- From the Browse Available page, click Learn More for the individual platform, in this case, Hubspot.
- In the Available Integrations section, there will generally be two options: an incoming integration that will send data from Hubspot into Mainstay, and an outgoing integration that will send data from Mainstay to Hubspot.
- Click the green Add New button to view a configuration modal for a new integration instance.
- Alternately, in the Configured section below, click the pencil icon on an existing integration instance to adjust its configuration.
Add or Edit an integration instance
1. Within the Configuration Wizard, on the Instance Details screen, create a display name and description for this instance. This is what will appear in the list; these values are only used for internal display purposes.
2. Next, on the Authentication screen, authorize access to Hubspot by selecting a previously used account or adding a new account. You will be prompted to log in to that platform in a separate pop-up window. (Developer API Key and API Key can be left blank; these were required for a previous Hubspot API version and are included for legacy purposes.)
3. Finally, on the Data Mapping screen, determine which Mainstay fields match to which Hubspot fields.
- The Mainstay CRM ID is already mapped to the Hubspot Record ID.
- Note that all Mainstay contacts are required to have First name, Last name, and Phone, so these fields must be mapped to something on Hubspot.
- Also note that Hubspot requires Email, so this should be mapped to a Mainstay email-type field (either a custom field or the built-in Email field).
- The dropdown menus will present all existing fields in each platform.
- Click the trashcan icon to remove a field mapping.
- Optionally select one or more filtering fields with corresponding values. This will prevent contacts from syncing if they do not have the required value for each filtering field.
- Hubspot --> Mainstay
- Mainstay --> Hubspot
- Click Finish to complete the data mapping.
Enable/Disable or Delete an integration instance
- On the screen listing all instances for a specific platform, click the toggle to switch between enabled (to the right, with green showing) and disabled (to the left, with gray showing).
- Alternately, click the trashcan icon to remove this instance and configuration altogether.
When sending data from Hubspot to Mainstay:
- If Mainstay ID (admithub_id) is present, this is generally a guaranteed match. All fields can be updated.
- If no match is found, that's an error.
- Otherwise, if CRM ID (hubspot id) is present AND/OR phone is present, we look for a matching contact to update. All fields except Mainstay ID, CRM ID, and phone can be updated this way.
- If both fields are included, but there is a conflict - for example, a contact with the same CRM ID but a different phone - this results in an error, and the contact is skipped.
- Otherwise, a new contact is created in Mainstay.
- If CRM ID (hubspot id) is present, this is generally a guaranteed match. All fields can be updated.
- If no match is found, that's an error.
- Otherwise, if email is included, we try to find an existing Hubspot contact with the same email.
- Then we set the CRM ID (hubspot id) on Mainstay for next time.
- Otherwise, we search Hubspot for contacts with the same First name and Last name. If there are any results, we check them against the phone number to ensure it's the right person (ie, there could be many "John Smith"s).
- If a match is found, we set the CRM ID (hubspot id) on Mainstay for next time.
- Otherwise, a new contact is created in Hubspot.
- Again, the contact's CRM ID (hubspot id) is set on the Mainstay record for next time.
View error logs
- In the side bar, click Sync Log, or visit https://app.mainstay.com/settings/sync-log.
- This table presents a list of errors encountered while attempting to sync data between Mainstay and third-party platforms. Each log includes the following fields:
- integration (ie, which platform)
- direction (incoming or outgoing)
- contact (a link to the Contact page of the affected individual)
- log message (ie, error code)
- If you encounter data validation errors while importing contact records, visit the Import Error Dictionary to better understand next steps.
- You can also download this data for a specific time range by clicking Download Logs in the top-right corner.