Salesforce Integration Guide

Article Overview

Artisan seamlessly integrates with Salesforce to export your enriched leads as Leads or Contacts. This guide explains how our Salesforce integration works, what data we sync, and the advanced features available to customize your workflow.

Getting Started

To connect your Salesforce account with Artisan:

1. Navigate to Settings → Integrations → Salesforce

2. Click Connect Salesforce

3. Log in to your Salesforce org and authorize Artisan

4. Configure your export preferences (object mapping, export triggers)

Once connected, Artisan can automatically export leads to Salesforce based on your preferences.

Object Mapping: Leads vs Contacts

Artisan supports exporting to either the Lead or Contact object in Salesforce. This is configured at the account level.

Export as Leads (Default)

When configured to export as Leads, Artisan creates new Lead records in Salesforce.

Export as Contacts

When configured to export as Contacts, Artisan creates new Contact records in Salesforce.

Note: The Contact object doesn’t have standard Company and Website fields like the Lead object. By default, we map Company to Department and Website to Description. You can use Custom Field Name Mapping to map these to your custom fields.

Duplicate Handling
Before creating a new record, Artisan checks if a Lead or Contact with the same email already exists in Salesforce:

• If a Lead exists:
  We link the Artisan lead to the existing Salesforce Lead and sync messages

• If a Contact exists:
  We link the Artisan lead to the existing Salesforce Contact and sync messages

• If neither exists:
  We create a new Lead or Contact based on your object mapping setting

This prevents duplicate records in your Salesforce org.

Field Mapping

Standard Field Mapping

Field Length Constraints

Salesforce enforces maximum field lengths. Artisan automatically truncates values to comply:

• FirstName: Maximum 40 characters

• Title: Maximum 128 characters

Lead Status & Sentiment Mapping
Artisan automatically sets the Lead Status based on engagement and sentiment analysis. This only applies when exporting as Leads
(Contacts don’t have a Status field).

Default Status Mapping

Custom Status Mapping

You can customize how Artisan maps lead statuses to match your Salesforce workflow:

{

"not_engaged": "Open - Not Contacted",

"engaged": "Working - Contacted",

"3": "Qualified",

"2": "Working - Contacted",

"1": "Unqualified"

}

Sentiment values:

• 3 = Positive sentiment (interested, wants to learn more)

• 2 = Neutral sentiment (asked a question, ambiguous)

• 1 = Negative sentiment (not interested, unsubscribe request)

This allows you to automatically qualify or disqualify leads based on their reply sentiment.

Advanced Features

The features below are configured on the backend by the Artisan team. To enable or update any of these settings, contact your Artisan account team with the configuration you'd like applied. We'll set it up for you and confirm once it's live.

Custom LeadSource

By default, Artisan sets the LeadSource field to "Artisan AI" on all exported records. You can request a custom value to match your attribution model.

Example — request this configuration:

{

"lead_source": "Partner Outbound"

}

This sets LeadSource to "Partner Outbound" for all new leads and contacts exported by Artisan.

Custom Attribution Property

You can request that Artisan populates a custom Salesforce field with a specific value on every record we export. This is useful for tracking the data source in a dedicated field separate from LeadSource.

Example — request this configuration:

{

"custom_attribution_property": "artisanai__data_source_c__c",

"attribution_value": "Artisan AI Platform"

}

This adds the field artisanai__data_source_c__c with value "Artisan AI Platform" to every new record. If attribution_value is not specified, it defaults to "Artisan AI".

Important: The custom field must already exist in your Salesforce org before requesting this configuration. Provide the Salesforce API name (e.g., artisanai__data_source_c__c), not the field label. Custom fields created via managed packages will have a namespace prefix.

Updating Existing Records (Overwrite Fields)

By default, if a Lead or Contact already exists in Salesforce, Artisan links to the existing record but does not modify it. You can request that Artisan updates specific fields on existing records by configuring an overwrite fields list.

Example — request this configuration:

{

"lead_source": "Partner Outbound",

"custom_attribution_property": "artisanai__data_source_c__c",

"attribution_value": "Artisan AI Platform",

"overwrite_fields": ["LeadSource", "artisanai__data_source_c__c"]

}

With this configuration:

• New records get all standard fields plus the custom attribution property

• Existing records get LeadSource and artisanai__data_source_c__c updated to the configured values

• Communications (emails and LinkedIn messages) are synced for both new and existing records

Note: Use the standard Salesforce API field names in the overwrite_fields list. Only the fields you specify will be updated — all other fields on the existing record remain untouched.

Custom Field Name Mapping

If your Salesforce org uses custom fields, you can map Artisan’s standard fields to your specific Salesforce API names.

Example Configuration:

{

"Status": "Custom_Status__c",

"Website": "Company_Website__c",

"Company": "Account_Name__c"

}

This maps:

• Artisan’s Status field → your custom Custom_Status__c field

• Artisan’s Website field → your custom Company_Website__c field

• Artisan’s Company field → your custom Account_Name__c field

Tip: Use the Salesforce API name (ending in __c for custom fields), not the field label.

Full Configuration Example

{

"lead_source": "Partner Outbound",

"field_name_mappings": {

"Status": "Custom_Status__c",

"Website": "Company_Website__c"

},

"lead_status": {

"not_engaged": "Open - Not Contacted",

"engaged": "Working - Contacted",

"3": "Qualified",

"2": "Working - Contacted",

"1": "Unqualified"

},

"custom_attribution_property": "artisanai__data_source_c__c",

"attribution_value": "Artisan AI Platform",

"overwrite_fields": ["LeadSource", "artisanai__data_source_c__c", "Status"]

}

To get started, share your desired configuration with your Artisan account team and we'll apply it to your account.

Combining Field and Status Mapping

You can use both field name mapping and status value mapping together.

Do Not Contact (DNC) Settings

Artisan helps you avoid reaching out to leads that already exist in your CRM, protecting your customer relationships and preventing duplicate outreach.

How DNC Works

When you enable “Do Not Contact leads found in CRM” for a campaign:

1. Email-Based Matching:
   Artisan checks if the lead’s email address already exists as a Lead or Contact in your Salesforce

2. Automatic Exclusion:
   Matching leads are automatically excluded from outreach sequences

3. Real-Time Checking:
   This check happens before any outreach is initiated

Lead and Contact Checking

Artisan checks both the Lead and Contact objects when filtering:

• First, we check if the email exists in the Lead object

• If not found, we check if the email exists in the Contact object

• If found in either, the lead is excluded from outreach

CRM Blocklist Filters

For more granular control, you can set up CRM blocklist filters that check specific conditions in Salesforce before reaching out. This allows you to:

• Only block leads matching certain criteria (e.g., Status = “Customer”)

• Allow outreach to leads that exist but meet certain conditions

• Create complex rules based on Salesforce field values

Email Message Sync

Artisan syncs all communication history with your Salesforce records, providing complete visibility into the relationship.

Email Sync

Artisan creates EmailMessage records in Salesforce for each email:

Message Deduplication

Artisan tracks which messages have already been synced to prevent duplicates. Each message has a unique MessageIdentifier that Salesforce uses to identify existing records.

FAQs

Q: What happens if a Lead or Contact already exists in Salesforce?
A: Artisan will link your lead to the existing Salesforce record and sync any new messages. We check both the Lead and Contact objects. No duplicate records are created.

Q: How do I know which records came from Artisan?
A: All records created by Artisan have LeadSource set to "Artisan AI". You can create Salesforce reports or list views filtered by this value.

Q: Can I export to both Leads and Contacts?
A: Currently, you choose one object type at the account level. However, if a Contact already exists for an email, we’ll link to that Contact even if you have Lead mapping configured.

Q: What permissions does Artisan need in Salesforce?
A: Artisan requires permissions to:

• Create and read Leads

• Create and read Contacts

• Create EmailMessage records

• Execute SOQL queries

We use OAuth 2.0 for secure authentication.

Q: How often does Artisan sync with Salesforce?
A: Leads are synced based on your export configuration:

• Export All Leads: Syncs all leads from your campaigns

• Export Engaged Leads: Only syncs leads that have replied

Q: Can I use custom Lead Status values?
A: Yes! Configure the lead_status mapping to use your picklist values. Make sure the values match exactly what’s defined in your Salesforce Status picklist.

Q: What if I disconnect and reconnect my Salesforce account?
A: Artisan maintains the mapping between your leads and Salesforce records. When you reconnect, syncing will resume normally using the existing mappings.

Connecting Your Salesforce Account

Standard Connection Flow

For most users, connecting Salesforce is straightforward:

1. Navigate to Settings → Integrations → Salesforce

2. Click Connect Salesforce

3. Enter your Salesforce username and password

4. Authorize Artisan to access your org

Once authorized, you're connected and ready to configure your export preferences.

Troubleshooting: "App must be installed into org" Error

Some users may encounter this error when trying to connect:

invalid_client: app must be installed into org

Why this happens:
Salesforce recently started blocking OAuth logins for "uninstalled" Connected Apps.
[Official Link]

Our integration uses a Connected App that must be explicitly installed/approved in your org before users can authorize it.

Fix Option 1: Install via Connected Apps OAuth Usage (Recommended)

Requires Salesforce Admin access (~1 minute)

1. Go to Salesforce Setup

2. Search for "Connected Apps OAuth Usage"

3. Find "Artisan Salesforce Integration 2" in the list

4. If it shows Install, click it to approve the app

5. Once installed, return to Artisan and retry the Salesforce connection

Fix Option 2: Install via Package URL

If you're seeing the invalid_client: app must be installed into org error and the Artisan app isn't appearing under Setup → Connected Apps OAuth Usage, you'll need to install our Connected App via package URL first.

Requires Salesforce System Admin access

Package Installation URL:
https://login.salesforce.com/packaging/installPackage.apexp?p0=04tgL0000009OHh

Steps:

1. Log into Salesforce as a System Admin in the org you want to connect

2. Open the install URL above in the same browser

3. Click Install

4. After the installation completes, go back to Artisan and retry the Salesforce connection

Note: Installing this package pre-installs and approves our Connected App in your org. This is now required by Salesforce before users can authorize third-party integrations. No additional keys or configuration are needed on your side.

Need Assistance?
Contact our Support team if you have any questions or issues!