Platform Integrations & API

What are platform integrations?

This feature allows institutions to connect their Mainstay data to a third-party platform, such as a Customer Relationship Management system (CRM) or Student Information System (SIS). This enables a 2-way sync of contact record data, including default fields (name, phone, email, etc.) and custom fields created by the partner.

Once an integration instance is configured, this acts as a "set it and forget it" feature. That is, whenever you save a change to a contact in Mainstay or the connected platform, that data can be automatically synced across to the other platform.

Mainstay also offers a public REST API. Documentation is available at https://docs.api.mainstay.com.

View available platforms

1. Log in to the Mainstay platform and navigate to the Settings tool in the navigation bar.
2. Under Third Party Integrations, click on the Browse Available option in the sidebar. This shows the list of currently available third-party platforms.
3. To set up a configuration, click the Learn More button for the specific platform.
4. See these Zendesk articles for more information:
   • Mainstay Sync for Salesforce
   • Mainstay Sync for Hubspot
   • Mainstay Sync for Slate
   • Mainstay Sync for Ellucian Colleague
   • Mainstay Sync for SFTP (including Ellucian Recruit, Ellucian Banner, Workday, and many more!)
   • Mainstay Conversations Export

Using the API directly

1. To use the Mainstay API directly, first, navigate to the "Mainstay API" Settings page.
2. Click + Generate a new token.
3. Enter a name or note and click Create token. On the next screen, copy the API token. You will not be able view it again, but you can always revoke it and create a new one.
4. Refer to https://docs.api.mainstay.com/ to build your API integration.
   • Some services like AirTable and Google Sheets allow you to create your own scripts and run them on a schedule. As a simple example, this block of code will fetch all of your contacts and log them in the console: 

   • let response = await fetch('https://api.mainstay.com/contacts/', {
       method: 'GET',
       headers: {
         'Content-Type': 'application/json',
         'Authorization': 'APIToken YOUR_TOKEN_HERE'
       },
     });
     
     console.log(await response.json());

   • example in AirTable:
   • 
   • The syntax of your script highly depends on the service running it. But a general pattern for syncing contacts might be:

   • let data = await response.json();
     for (let i in data.results) {
       let contact = data.results[i];
       
       // filter out contacts you don't want, for example, those with no phone number
       if (!contact.phone) {
         continue;
       }
     
       // identify contacts already in your table, for example, by matching to CRM ID
       if (YOUR_TABLE.find(record => record.id == contact.crm_id)) {
         // update the existing record here
       }
       
       // other contacts must be new
       else {
         // create a new record here
       }
     }

View error logs

1. In the side bar, click Sync Log, or visit https://app.mainstay.com/settings/sync-log.
2. 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:
   • timestamp
   • id
   • integration (ie, which platform)
   • direction (incoming or outgoing)
   • contact (a link to the Contact page of the affected individual)
   • log message (ie, error code)
3. If you encounter data validation errors while importing contact records, visit the Import Error Dictionary to better understand next steps.

Tips

• Contact records that are designated Test Users will be ignored by platform integrations. See Test Users.
• If a contact record is Archived, reimporting that contact via CSV upload or platform integration will un-archive the contact.
• If a contact record does not have a value for a particular field, that field will not be sent for that contact record in outgoing requests. Similarly, when importing information, if the value for a field is blank or null, it will be skipped.
• However, like the Mainstay API and CSV upload, these platform integrations do support clearing the value of all custom fields and the following default fields. Set the field to UNSET (all capitals) and the value will be cleared out.
  • First Name
  • Last Name
  • Preferred Name
  • Phone
  • Email
  • Enrollment ID
  • CRM ID