How integrations work

An integration sends the people who sign up in your campaigns to another tool, such as your newsletter system or CRM. It works in two steps: first you connect the tool to your Scratcher account, then you turn it on in each campaign where you want to use it.

Every tool has its own page with the exact steps, including where to find the API key in that tool and which permissions it needs. See All integrations.

Step 1: Connect the tool to your account

1. Go to Settings > Integrations (under Developers). Search for the tool, or use By type to show only Newsletter systems, E-commerce or CRM tools.
2. Click the tool. The dialog has the tabs Installation and Features (what the integration can do).
3. Fill in what the tool asks for. There are two kinds of tools:
   • Tools you log in to, such as Mailchimp, HubSpot and Drip. The dialog says "You will be redirected securely to ... to authorize access. No API keys or manual credentials required."
   • Tools that need an API key or other credentials, such as Klaviyo or ActiveCampaign. Paste them in the fields. The Setup guide box in the dialog tells you where to find them, when the tool has one.
4. Click Install integration. Scratcher checks the credentials right away. If they don't work, you see "All or some of the fields are invalid. The integration failed to validate the fields."

When it works, you see "The integration has been installed." Connecting the tool doesn't send any leads yet.

You can also install a tool from inside a campaign (Step 2). Then it is turned on for that campaign at the same time.

Step 2: Turn it on in a campaign

1. Open the campaign in the editor and go to Connect > Integrations. Type in the search box (Type to search…) to find the tool. Tools that are on for this campaign have the badge Active.
2. Click the tool and then Activate. The panel says "Integration is active."
3. If you have connected more than one account of the tool, choose it under Select account. Click (+ add new) to connect another account.
4. Under External list, choose the list or audience people should be added to. Some tools have no lists; then this field isn't shown.
5. Under Field mappings, click Add field mapping for each piece of data you want to send. See "Map your fields" below.
6. Under Filter by permissions (optional), choose your marketing consent checkbox, so only people who ticked it are sent. See "Send only people who said yes" below.
7. Fill in any extra settings the tool has, such as Tags.
8. Click Save. You see "The integration has been updated."
9. Click Test to send a test lead. See "Test the integration" below.

Map your fields

Field mapping decides which Scratcher data goes into which field in the other tool. The header shows how many fields are mapped, for example "3 mapped".

1. Click Add field mapping. A new row appears with a Scratcher field on the left and a Destination field on the right.
2. In Choose a field, pick the Scratcher data to send. The fields are grouped:
   • Lead: the fields on your form (for example "Lead - First name"), ID, Phone number, Created at and Participated at. For each consent checkbox you also get Accepted, Content (the text the person agreed to), Date and IP address.
   • Campaign: ID and Name.
   • Participant: Channel (where the person came from).
   • Quiz: the answers to named quiz questions, if the campaign has a quiz.
   • Prize: ID, Name, Value, Coupon code and Won at, for winners.
3. To send the same fixed text for everyone, choose Use custom value and type the text, for example the name of the campaign or "Scratcher". Click Use Scratcher field to go back to a field.
4. In the Destination field, choose the field in the other tool. The list comes from your own account in that tool, so your custom fields are there too. For a few tools you type the name instead (External field name).
5. Click the gear (Show settings) for more options:
   • Skip field if empty: "This ensures that the field is not sent to the integration if the data you are trying to send is empty." Use it so empty answers don't overwrite data the tool already has.
   • Format (phone numbers only): Include + and country code (e.g. +4512345678), Include country code (e.g. 4512345678) or Exclude country code (e.g. 12345678). Choose what the other tool expects.
6. Click the bin (Delete mapping) to remove a row.

Good to know: the email address is always sent, and most tools also get the phone number automatically. The tool's own page says which fields are filled in for you.

Send only people who said yes

Filter by permissions (optional) lists the consent checkboxes in your campaign. "Select the permissions that should be used to filter the leads. If the lead has not accepted all of the selected permissions, it will not be sent to the integration."

• Leave it empty ("Leave empty to send all leads") to send everyone.
• Choose your marketing consent checkbox to send only people who ticked it. If you choose several, people must have ticked all of them.

People who are left out aren't sent and don't show under Delivery status. Many tools add the people you send as subscribers, so always use the filter if your marketing checkbox is optional. See Consent and permissions.

Test the integration

1. Save the integration first, so all fields are available in the test.
2. Click Test. The panel Test your integration opens.
3. Choose the list under Select list (for tools with lists), type an Email and fill in a value for every mapped field.
4. Click Send test. You see "The data has been sent over successfully" or the error message from the other tool.
5. Check that the test person arrived in the other tool, and delete them there afterwards.

The test sends to the other tool even if you use Filter by permissions. If you see "You must enter a value into all the fields", fill in every field.

When are leads sent?

• Scratcher checks for new sign-ups every minute and sends them in the background, so new leads arrive within a minute or two.
• When you activate an integration on a campaign that already has leads, those leads are sent too.
• When someone takes part again, their data is sent again, so the tool is updated with the newest answers.
• For tools with a list, nothing is sent until you have chosen a list. Tools without a list start sending as soon as you click Activate.

Good to know: set up the field mappings and the consent filter before the campaign goes live. Leads that were already sent aren't sent again when you change the mappings later. You can resend them under Delivery status.

Check that it works

Settings > Integrations > Delivery status shows every lead sent to your tools, whether it was a new or an existing contact, and the error if it failed. See Check the delivery status and resend leads.

Manage connected accounts

Click an installed tool under Settings > Integrations. The tab Overview reminds you to activate it in your campaigns. The tab Accounts ("Your connected accounts") lists the accounts you have connected:

• Use the Actions menu (...) and Rename to give an account a name you recognise, for example "Newsletter DK". Type it in Name in the Rename account dialog and click Save.
• Delete disconnects the account: "This will disable any running integrations that use this account".
• Add new account connects one more account of the same tool, for example a second Mailchimp account.

Turn it off

• In the campaign, open the integration and click Deactivate. Nothing more is sent from that campaign.
• To remove the tool from your account and all campaigns, open it under Settings > Integrations and click Uninstall. "Are you sure you want to uninstall this integration? This will also remove the integration from all campaigns."

Who can use integrations?

• Integrations are part of the paid plans. HubSpot and Salesforce Marketing Cloud need a plan that includes all native integrations. If a tool is locked, see Your trial, plans and what happens when the trial ends.
• Users with the role Owner, Admin or Manager can install and set up integrations. Analyst users can't.