Import from Salesforce

Follow Import and export for the import method. This page covers Salesforce objects, exports and field maps.

Get the data

• API: use access to the Salesforce org that the user approved. Check that the org allows API access and the signed-in user has API Enabled. Read each object's describe for its available fields and types. Record and field permissions limit what you can read. For REST queries, follow nextRecordsUrl until done is true. Use Bulk API 2.0 query jobs for large objects.
• Data Export: in Setup, search for Data Export, select Export Now, choose the file encoding and the objects, then select Start Export. Ask the user to download every ZIP within 48 hours of the email. A new export removes the files. The ZIPs contain CSV files. Export availability depends on the edition and the time since the last export. See Salesforce's export guide.
• Data Loader: use Export All for each object, with Write all CSVs with UTF-8 encoding in its settings. This includes archived activities and deleted records. Exclude rows with IsDeleted = true from the import.

Read the CSV files as Spreadsheets and CSV files describes.

Get Account, Contact, Lead, Opportunity, Task, Event, Note, ContentNote and ContentDocumentLink. Get User, OpportunityStage and RecordType for owner and stage maps. Include the relation objects below when those links matter, plus EmailMessage for email bodies and OpportunityLineItem for deal products. Check which objects and fields each export contains. A report export contains only the report's selected data and may lack the IDs and links you need.

How the objects link

Salesforce object	Link fields
Contact	AccountId links to its account.
Opportunity	AccountId links to its account. OwnerId links to User. RecordTypeId links to RecordType.
OpportunityContactRole	OpportunityId and ContactId, with Role and IsPrimary.
OpportunityLineItem	OpportunityId links each product row to its opportunity.
Lead	Company and Website are text, not account links. A converted lead has ConvertedContactId, ConvertedAccountId and, when applicable, ConvertedOpportunityId.
Task, Event	WhoId names a contact or lead. WhatId can name an account, opportunity or another object. AccountId is the account Salesforce derives from those links.
TaskWhoRelation, EventWhoRelation	TaskId or EventId, with RelationId, gives the people linked through Shared Activities.
EventRelation	EventId and RelationId, with IsInvitee, identify invitees. These can include Salesforce users.
EmailMessage	ActivityId links the email to its task. Do not import both as separate copies of one email.
Note	ParentId links a classic note to its record.
ContentDocumentLink	ContentDocumentId identifies the document or enhanced note. LinkedEntityId identifies a record, user or other sharing target. One note can have several links.

Use the object's keyPrefix from its describe to identify the type of a linked ID. Do not assume every WhatId names an opportunity.

A person account has IsPersonAccount = true and a related contact in PersonContactId. Treat the account and that contact as one person, not two people or a business company. Map both IDs to that person for activity and note links. An opportunity on a person account has no direct company mapping. Include it in the import questions, together with opportunities that lack AccountId.

Map to Sofatofu

Use Data with no field of its own for the common mappings. Salesforce custom fields end in __c. Read their types from the describe, not their names. A picklist maps to select, and a multi-select picklist maps to multi_select. Query address parts such as BillingStreet and BillingCity, not the compound BillingAddress, for Bulk API exports.

Company

Salesforce value	Sofatofu field or use
Business Account.Name	name
Account.Website	domain, using only the host
Industry, Type, NumberOfEmployees, AnnualRevenue, AccountSource, Rating, Phone, billing address parts	Custom fields
OwnerId	Resolve through User for a custom field. A company has no built-in owner.
Description	Custom text, or a note activity when it does not fit

Person

Salesforce value	Sofatofu field or use
Contact.Name or Lead.Name	name
Email, Phone, Title	email, phone, job_title
Contact.AccountId	company, when it names a business account
Lead.Company, Lead.Website	Data for a company linked to the person. Group by website host, then compare names where no website exists. Match groups to imported business accounts by domain.
Lead.Status	Custom select field for the lead state
Person account Name, PersonEmail, Phone, PersonTitle	name, email, phone, job_title
MobilePhone, HomePhone, OtherPhone, PersonMobilePhone, Department, LeadSource, mailing address parts	Custom fields

Check IsConverted. When it is true, import the contact in ConvertedContactId, not the lead. Link the lead's activities and notes to that person. If an earlier run imported the lead as a person, update that person's source_id to use the contact's ID under Source IDs. Sending both people fails when they share an email. Map both Salesforce IDs to the same person and follow Run the import again.

Deal

Salesforce value	Sofatofu field or use
Opportunity.Name	name
AccountId	company
StageName	stage, using OpportunityStage to identify its meaning
Amount	value, only when the record's currency matches the workspace currency
CloseDate	For open opportunities (IsClosed = false), expected_close_date. For closed ones, a custom date field for the close date.
OwnerId	owner: look up the User by Id and match its Email to a member. The Salesforce user can be inactive.
Probability, Type, LeadSource, ForecastCategoryName, record type name	Custom fields
OpportunityLineItem	Product rows for the deal's note: Name, Quantity, UnitPrice, TotalPrice. Do not add their total to Amount.
Description	Custom text, or a note activity

OpportunityStage gives IsActive, IsClosed, IsWon and SortOrder. More than one stage can mean won or closed. Use these flags rather than guesses from stage names. RecordType.BusinessProcessId identifies the sales process, which restricts the available stages. Picklist API values can differ from displayed labels.

In a multi-currency org, read each record's CurrencyIsoCode. Otherwise, confirm the org currency with the user. Map AnnualRevenue and other money values to custom currency fields only when each value's currency matches the field's currency. Include unresolved stage, owner and currency mappings in Before you import.

Activity

Salesforce value	Sofatofu field or use
Closed Task, with IsClosed = true	kind: Call in TaskSubtype means call, and Email or ListEmail means email. Check other subtypes and Type before choosing note.
Task.CompletedDateTime	occurred_at. ActivityDate is the due date, not proof of when the task finished.
Past Event	kind: usually meeting. Check Type for calls or other events. Use StartDateTime for occurred_at.
Note, ContentNote	kind: note, with the note's CreatedDate for occurred_at
Subject, note Title	subject
Task.Description, Event.Description, Note.Body	body
EmailMessage.TextBody	The linked email task's body
ContentNote.Content	Full note body in HTML, which can be base64-encoded. Decode when needed and convert to text. TextPreview is not the full note.
WhoId, shared activity relations, event invitees	people, using the imported contacts and leads. A Salesforce User ID is not a CRM person ID.
AccountId, account WhatId	company for a business account, or a person in people for a person account
Opportunity WhatId	deal
Note.ParentId, enhanced note LinkedEntityId	Resolve each target to its company, person or deal.

If WhatId names an excluded object, such as a Case, link the activity through usable WhoId and AccountId values. An activity with no usable link cannot come in as it is. Check missing completion times and all-day events separately. They do not establish an exact event time. A note linked to several business accounts or opportunities cannot keep all those links in one activity. Handle these cases through When data doesn't fit.

Source IDs

Apply Source IDs with salesforce as the source.

Use the 18-character ID with its original case. Sofatofu treats the 15- and 18-character forms of one ID as different values. Mixing them makes duplicates or breaks links. Convert record IDs and link IDs to 18 characters before matching. Never lowercase an ID.

The API, Data Loader and Data Export return 18-character IDs. Reports can give 15 characters. Salesforce provides CASESAFEID for conversion. See Salesforce ID types and ID conversion.

Source record	Stable ID
Business account	Account.Id
Contact or unconverted lead	Contact.Id or Lead.Id
Person account	PersonContactId, which identifies its contact
Opportunity	Opportunity.Id
Task, event or classic note	The object's Id
Enhanced note	Its ContentDocumentId, not a link row's ID or a version ID

Salesforce IDs are unique within an org, across these objects. A sandbox or another org can repeat IDs. An org is an account under rule 2 of Source IDs.

A new company built from one lead comes from that lead under the derived-record rule in Source IDs. A new company that several leads describe has no single source record, so omit source_id, as Source IDs for spreadsheets describes.

A description note comes from its account or opportunity. A line-item note comes from its opportunity. Give each a source ID under the derived-record rule in Source IDs.

Data without a direct mapping

Use When data doesn't fit for these Salesforce cases.

Salesforce data	What a direct copy would lose or change
Formula fields (calculated), roll-up summaries, ExpectedRevenue, scores	A copied result no longer recalculates. Data Export excludes formula and roll-up summary fields.
AccountHistory, ContactHistory, OpportunityFieldHistory, OpportunityHistory	Source history is not Sofatofu change history.
Open tasks, future events, reminders, NextStep	Planned work is not a completed activity.
Case, Campaign, Product2, price books, quotes, contracts, assets, custom objects	No matching record type
Attachment, non-note ContentVersion, email attachments, recordings	No file storage. An enhanced note's text is separate from these files.
Indirect AccountContactRelation, Account.ParentId, Contact.ReportsToId, OpportunityContactRole, opportunity teams	No matching relationship. A contact role does not become an activity participant by itself.
Reports, dashboards, list views, flows, assignment rules, Sales Engagement cadences	Source configuration, not CRM records
Multiple sales processes	One stage list cannot keep separate processes. The record type name can remain in a custom field.

Traps

• Archived activities: ordinary queries leave them out. Use queryAll for Task and Event, and exclude IsDeleted = true. Check that exported relation rows also cover the archived activities you need.
• Child events: IsChild = true can mark an invitee's copy of a recurring event. Exclude child copies so one meeting does not become several activities.
• Enhanced notes: query ContentDocumentLink for the imported LinkedEntityId values. ContentNote.FileType is SNOTE. Do not treat every linked file as a note. Check that an export contains both note bodies and their link rows. Missing links do not mean a note was unrelated to a record.
• Visibility: check access to private notes and files. An empty result does not prove that none exist. Do not change source sharing settings to get them.
• Dates: compare exported date-times with known records in Salesforce before choosing a time zone. A date-only field has no time zone.
• Repeated keys: Salesforce can contain contacts and leads with the same email, or accounts with the same website. Check these groups under Before you import.
• Merged records: deleted account, contact or lead rows can hold MasterRecordId, which identifies the survivor. Use these links to resolve old source IDs. Do not recreate the deleted records.