Integrations connect Simplesat to your helpdesk, PSA, CRM or other tool. You connect a tool once, with Authenticate on its page under Integrations, using an account or key from that tool. Each integration on the page then does one thing through that connection, such as adding feedback to a ticket as a note.
Every tool you connect this way, except Intercom and Dropbox, runs on an integration platform that's one of Simplesat's subprocessors. Those two connect directly to Simplesat, which stores their tokens, and they have their own articles.
How it works
The integration platform runs on Simplesat's own servers in AWS, in Ireland (eu-west-1), and keeps each workspace's connections and integrations separate.
A tool's page has one connection. That connection holds the credential from your tool, and every integration on the page uses it. You switch each integration on with Activate integration and off with Deactivate integration.
Most integrations start in Simplesat. When a response arrives, Simplesat sends it to each integration switched on for its survey, and sends it again when the response changes. The integration then reads from or writes to your tool. The rest start in your tool, when it reports an event such as a ticket closing, or on a check every hour or once a day.
Security & privacy lists Simplesat's subprocessors and where Simplesat stores data, and it includes the Data Processing Agreement.
Who can connect and change integrations
Connecting a tool, switching integrations on and off, changing their settings and revoking access all need the Manage integrations permission. Owner and Admin have it by default. A custom role has it only when Manage integrations is ticked on that role. Without the permission, every card on the Integrations page is grayed out and won't open.
Users & permissions explains roles and custom roles.
The account or key you connect with
What Authenticate asks for depends on the tool. It might be a sign-in to your account there, an API key, a username and password, or fields such as a URL, an ID and keys.
For a tool that connects by sign-in, Authenticate opens the tool's sign-in page through integration.simplesat.io. You sign in and approve access there, then return to Simplesat. The integration platform holds the token your tool issues, and the token isn't passed to Simplesat's app or database.
When a tool asks for a key, a password or other fields, what you enter goes straight to the integration platform, which stores it. For most tools, Simplesat checks it with your tool before showing the tool as connected. Simplesat's own database records that the tool is connected, but not the credential.
Once the tool is connected, its page shows Authenticated with and your tool's name, next to Revoke access. You can't edit a saved credential. To change the account, key, password or instance, click Revoke access and connect again.
Heads up: Simplesat doesn't check the credential again after you connect. If the key is revoked, the password changes or the user is deactivated in your tool, the page still shows the tool as authenticated, and the integrations fail when they run.
Every integration on the page acts as the account you connected with and is limited to that account's access in your tool.
Tip: Connect with an account that doesn't belong to one employee, such as a dedicated API user. That way the integrations keep running when someone leaves.
What Simplesat sends to an integration
Each response Simplesat sends to an integration includes:
The survey, the response's tags, when it was created and last changed, and its source
The ticket: its ID in Simplesat and in your tool, its subject and its custom attributes
Each team member credited: name, email, their ID in your tool, their groups and custom attributes, their role, and whether they're the primary team member
The customer: name, email, company, tags, their ID in your tool, and custom attributes
Every answer: the question text and metric, the rating and its label, the comment, sentiment, topics and follow-up answers
A file-upload answer goes as a link that expires after five minutes, not as the file. A response that's withheld, hidden or spam isn't sent while it stays that way. A withheld response is sent as soon as it's released.
You choose which surveys an integration receives under When should this integration run? in its settings:
Every response from all current and future surveys
Every response from Zendesk surveys, for an integration that works on tickets, with your own tool's name in place of Zendesk
Let me choose, which lists your surveys so you can pick the ones you want
A new integration starts with every survey. An integration that works on tickets receives responses only from surveys set up for that tool. Some integrations also have sentiment settings that narrow which responses they receive.
What integrations read and write in your tool
Each kind of integration makes a fixed set of calls to your tool, using the connection's credential. Field lookups in an integration's settings also call your tool, and they work while the integration is switched off.
Integration | Reads from your tool | Writes to your tool |
Pull ticket, conversation, case or order details | The ticket, conversation, case or order, and records linked to it, such as the contact, company, agent and time entries | Nothing. The details go onto the response in Simplesat |
Contact sync | Contacts and their companies, every hour, once a day, or when your tool reports a change | No records. Contacts become customers in Simplesat |
Send a survey from your tool | The ticket, conversation or order, with its contact and agent, when your tool reports an event or on a check every hour or once a day | No records for email surveys, which Simplesat sends. Chat and SMS surveys go out through your tool, as a message in the conversation or as a text message. An integration that starts from an event creates a webhook in your tool when you switch it on, unless its settings show a Webhook URL for you to add yourself |
Add feedback as a note or comment | In some tools, the ticket or contact, to find it | Adds a note or comment to a record, such as a ticket, conversation, case, contact or deal |
Write feedback to custom fields | In some tools, the ticket or contact, to find it | Updates the custom fields you map on a record such as the ticket, contact or company. Some create the fields in your tool when they don't exist yet |
Add rating and sentiment tags or labels | In some tools, the record's current tags or labels | Adds tags or labels to a record, such as a ticket, conversation, contact or user. Some remove tags or labels from it first, and some create a tag or label that doesn't exist yet |
Create a follow-up ticket | In some tools, the contact or company. In HaloPSA, the rated ticket | Creates a ticket, case, issue or task |
Create other records from feedback | In some tools, related records | Creates a record, such as a contact and account in Salesforce, a custom object in HubSpot, or a satisfaction rating in Zendesk |
Export to a data warehouse or spreadsheet | What the export needs from the destination, such as your list of spreadsheets in Google Sheets or statement results in Redshift | Adds or updates rows in the table or sheet you name. Some create the table, sheet or dataset first |
No integration deletes a ticket, contact, company or other record in your helpdesk, PSA or CRM.
Give the account you connect with read access to the records your switched-on integrations use, and permission to create or update the records they write to. Where an integration creates a field, tag or label, the account also needs permission to create it. Where one creates a webhook in your tool, the account needs permission to manage webhooks too. Each tool names these permissions its own way. In Zendesk, only an admin can manage webhooks or create ticket and user fields, so connect Zendesk with an admin account.
Each kind of integration has its own article:
Attribution: linking feedback to tickets, customers and agents covers pulling details
Contact sync from a connected tool covers contact sync
Writing feedback back, and mapping the fields covers notes, custom fields and tags
Creating a follow-up ticket from feedback covers follow-up tickets
Revoke access and connect again
Revoke access disconnects the tool from Simplesat and deletes the credential stored for it.
Warning: Revoke access has no confirmation step. One click disconnects the tool and switches off every integration on its page, including contact syncs and surveys sent from your tool.
Before you click it, write down which integrations are on. Connecting again won't switch them back on, and the page keeps no list.
Click Revoke access.
Click Authenticate and enter the new account, key, password or instance details.
Open each integration you wrote down and click Activate integration.
Every integration and its settings stay in Simplesat, field mappings included. Responses that arrive while an integration is off aren't sent to it when you switch it back on, so switch each one on as soon as you've connected. Support can also read an integration's log and re-run anything that failed in the last 30 days.
If you're retiring the account or key you connected with, remove it in your tool too, or remove the app's access there.
Reset integration is a different control. After you confirm, it returns one integration to its default settings and deletes the ones you set. It's offered only while the integration is switched off.
Troubleshooting
All my integrations are grayed out
Your role doesn't include Manage integrations. Owner and Admin include it. If you're on a custom role, even one called Admin, it includes the permission only when Manage integrations is ticked on it. Ask an Owner or Admin to grant it.
If the cards open but the controls on one tool's page are locked, the tool isn't connected yet. Activate integration becomes available once it is. An integration's survey and sentiment settings open up once that integration is switched on.
My tool rejects the API user even though the details look right
The integration acts as that account, so your tool decides what it can do. Simplesat can't see the account's permissions, so check them in your tool. The account needs read access to the records your switched-on integrations use and permission to create or update the records they write to, such as contacts and companies for contact sync, or tickets for a note on a ticket. It also needs permission to create any field, tag or label an integration adds, and to manage webhooks for any integration that starts from an event in your tool.
If your tool, or a firewall in front of it, limits which IP addresses can reach its API, see IP addresses and domains.
To find out what a specific error message means, see Integration error messages and what they mean.
Our API user has admin rights and the integration still fails
Admin rights are normally enough to run any integration, but some tools, such as Autotask, want a dedicated API user instead. An integration acts as the account it was connected with, and the page doesn't show which account that is. If that account was changed, deactivated or lost access after you connected, the page still shows something like Authenticated with ConnectWise. To be sure which account is in use, click Revoke access, connect with the account you mean, then switch each integration back on. Support can also read the integration's log.
Our integration stopped working after someone left or we rotated the API token
Simplesat doesn't check the credential after you connect. A deactivated user, a changed password or a revoked key leaves the page showing something like Authenticated with HaloPSA while the integrations fail. To fix it:
Write down which integrations are on.
Click Revoke access.
Click Authenticate and connect with a current account or key.
Click Activate integration on each integration you wrote down.
Once the connection works, ask support to re-run what failed in the last 30 days. Connecting with a dedicated API user rather than one employee's account keeps the integrations running the next time someone leaves.
I reconnected and everything I had set up is off
Revoke access switched off every integration on that tool's page, and connecting again didn't switch them back on. The integrations and their settings are still in Simplesat. Click Activate integration on each one you use. Responses that arrived while the integrations were off aren't sent to them when you switch them back on.
The page has no list of which integrations were on. Your audit log records each time an integration was switched on, so it can help you work out which ones you were using. Audit logs explains what else it records.
FAQ
Which permissions or scopes does the integration need in my tool?
Give it read access to the records your switched-on integrations use, and permission to create or update the records they write to. It also needs permission to create fields, tags or labels where an integration creates them, and to manage webhooks where an integration starts from an event in your tool. For example, contact sync reads contacts and their companies, a note integration adds a note to a ticket or other record, and some tag integrations create a tag that doesn't exist yet. You switch each integration on separately, so you can grant access for just the ones you use. Each tool names these permissions differently.
Giving the integration full access isn't acceptable to us. What does it actually need?
Each integration makes a fixed set of calls. Pulling details, contact sync and email surveys read from your tool without creating or changing a ticket, contact or other record. Integrations that write add notes or comments, update the custom fields you map, add or remove tags or labels, or create records such as follow-up tickets. None of them deletes a ticket, contact, company or other record in your helpdesk, PSA or CRM. Grant read access to the records your switched-on integrations use, and permission to create or update the records they write to. An integration that starts from an event in your tool needs permission to manage webhooks too, because switching it on creates a webhook there. Field lookups in an integration's settings also call your tool.
Which permission lets the integration write to a custom field on the ticket?
Edit access to the record that holds the field: tickets for a ticket field, and contacts or companies for a field on those. Some integrations create the field when it doesn't exist yet, such as the Zendesk integrations that write to ticket fields and user fields. Those also need permission to create fields.
What data does Simplesat read from my tool?
For every tool except Intercom and Dropbox, the integration platform makes the calls with the connection's credential. What's read depends on the integration. Pulling details reads the ticket, conversation, case or order and records linked to it, such as the contact, company, agent and time entries. Contact sync reads contacts and their companies. Sending a survey from your tool reads the ticket, conversation or order with its contact and agent. Integrations that write back may first read the record, or its current tags, to find it. Field lookups in an integration's settings also call your tool.
Does your connected app meet our security requirements, such as PKCE, refresh token rotation and IP allowlisting?
For tools that connect by sign-in, the sign-in and the token exchange happen on integration.simplesat.io, and the token goes to the integration platform, not to Simplesat's app. The Zendesk and Salesforce connections use PKCE, refresh tokens that expire after 30 days, and refresh token rotation, because those tools require them. Connections to other tools use what each tool supports, so for another tool, contact us with the requirements you need checked. For IP allowlisting, the addresses are in IP addresses and domains.
Do access tokens expire, and will we have to reconnect?
Simplesat doesn't check the connection after you connect. An expired or revoked token shows up as integrations failing while the page still shows something like Authenticated with Zendesk. To connect again, click Revoke access, then Authenticate, then click Activate integration on each integration you use.
Our credentials are changing. Do I revoke access and connect again, and will that break the rest of my setup?
Yes. You can't edit a saved credential, so revoke access and connect with the new one. Revoking keeps the integrations and their settings in Simplesat. It also switches off every integration on that tool's page, and connecting again won't switch them back on. Write down which integrations are on before you start, then click Activate integration on each one after you connect.
How do I reconnect without disturbing the destinations I already set up?
Revoke access keeps every integration and its settings in Simplesat, field mappings included. Connect again with an account that can reach every record and field the integrations write to. An account with less access can still connect, but the integrations then fail when they write. After you connect, click Activate integration on each integration you use.
Do the changes support made to our integration, such as excluded fields, survive a reconnect?
Yes. Any change support made to an integration stays in place when you revoke access and connect again, along with its settings and field mappings. After you connect, click Activate integration on each one you use.
How long are integrations down while I reconnect?
Each integration is down from the moment you click Revoke access until you switch it back on. Connecting again doesn't switch integrations back on, so switch each one on right after you connect. Responses that arrive in between aren't sent to it when you do. An integration that starts from your tool, such as a survey sent when a ticket closes, can also miss what happened in your tool while it was off.
My helpdesk subdomain or instance changed. What do I need to do in Simplesat?
Connect the tool again with the new instance:
Write down which integrations are on.
Click Revoke access.
Click Authenticate and enter the new instance's details.
Click Activate integration on each integration you wrote down.
The integrations keep their settings and field mappings.
Does rotating a Simplesat API key affect my integrations?
No. Integrations connected on the Integrations page don't use any key on the API keys page, the Legacy account key included. Rotating or deleting one of those keys still stops any tool you gave it to, such as Make, n8n or Power BI. API keys has more on them.