Import from Pipedrive
Follow Import and export for the import method. This page covers Pipedrive's data and field maps.
Get the data
Use the Pipedrive API with access the user provides, or ask for export files. Both paths return only data visible to that Pipedrive user. Pipedrive's MCP server has no tools for archived deals or leads. If you read through it, get archived items from an export.
For files, a global admin opens Tools and apps > Export data and exports Organizations, People, Deals, Leads, Activities and Notes as Excel or CSV. Select all archive states for deals and leads. Export activities and notes separately, even when they link to deals or contacts. For line items, check that the files hold each deal's products, not only the product catalog.
Check that each file has an ID column for its own items and each linked item. Read the files as Spreadsheets and CSV files describes.
For API reads, use v2 where available. These endpoints provide the records and the data needed to map them:
| Data | Read endpoint |
|---|---|
| Organizations and people | GET /api/v2/organizations, GET /api/v2/persons |
| Deals | GET /api/v2/deals and GET /api/v2/deals/archived |
| Leads | GET /api/v1/leads and GET /api/v1/leads/archived |
| Activities | GET /api/v2/activities?include_fields=attendees |
| Notes | GET /api/v1/notes |
| Pipelines and stages | GET /api/v2/pipelines, GET /api/v2/stages |
| Users | GET /api/v1/users |
| Field definitions | GET /api/v2/organizationFields, GET /api/v2/personFields, GET /api/v2/dealFields, GET /api/v2/activityFields |
| Lead labels and activity types | GET /api/v1/leadLabels, GET /api/v1/activityTypes |
| Products on deals | GET /api/v2/deals/products?deal_ids= with up to 100 comma-separated deal IDs |
| Email messages linked to records | GET /api/v1/persons/{id}/mailMessages, GET /api/v1/deals/{id}/mailMessages |
The regular deal and lead lists exclude archived items. Read both lists before applying the import scope. Leave out deals with status: "deleted". Archive state is separate from a deal's open, won or lost status.
Follow Pipedrive's pagination: v2 lists return additional_data.next_cursor for the next cursor. Stop at null. Offset-based lists return additional_data.pagination.next_start for the next start while more_items_in_collection is true. Use limit=500 for paged reads. All integrations of a Pipedrive company share its daily API token budget. When it is spent, requests get 429 until the budget resets at midnight in the server's time zone, not necessarily the user's. Estimate the request count and token cost before a large read.
Read email messages through the API. For a body missing from a list result, use GET /api/v1/mailbox/mailMessages/{id}?include_body=1. Check a message's fields for its send time, sender and recipients. The same message can link to several records, so combine those links under one message ID.
How the objects link
Read users, pipelines, stages and field definitions before mapping record values. The field names below follow the v2 migration guide, except for notes and leads, which use v1.
| Link | Pipedrive fields |
|---|---|
| Deal to stage and pipeline | Deal stage_id and pipeline_id. Each stage also has pipeline_id. |
| Lead to contacts | person_id, organization_id, or both |
| Owner to user | owner_id. Resolve it through the users list, including users with active_flag: false, then use the email for the member map. |
A deal without org_id may have a company through its contact's org_id. Check that this is the company for the deal. If neither link gives a company, include the deal in the import questions.
A lead points to contacts that also appear in the person and organization lists. Apply its lead fields to those contacts, not to a second copy. Use the person when present, or the organization for an organization-only lead. For notes and activities linked only to a lead, resolve the lead's contact links.
Map is_archived to the lead state and resolve label_ids through the lead labels. Other lead values include title, source_name, expected_close_date and value (an amount and currency). Map these to custom fields where needed. If several leads share a contact, ask how to keep their different values.
Map to Sofatofu
Use Fields and matching for Sofatofu's value formats and Source IDs for each record's identity. Use Data with no field of its own for source creation dates, labels, extra contact values and other fields outside these maps.
Company
| Pipedrive organization | Sofatofu field |
|---|---|
name |
name |
| Website value, if present | domain. Check whether it is website or a custom field, then extract the host. |
address |
Custom text field from formatted_address, or value when no formatted address exists |
owner_id |
Custom field with the source user's name, not a member owner link |
Person
| Pipedrive person | Sofatofu field |
|---|---|
name |
name |
emails |
email from the non-empty entry with primary: true, or the first non-empty entry. Use the shared map for other addresses. |
phones |
phone from the first non-empty entry. Use the shared map for other numbers. |
job_title, if present |
job_title. Otherwise check for a custom field with that meaning. |
org_id |
company through the organization map |
If emails or phones has no non-empty value, omit the corresponding Sofatofu field.
Deal
| Pipedrive deal | Sofatofu field |
|---|---|
title |
name |
org_id |
company, with the missing-organization check above |
status, pipeline_id, stage_id |
stage. Read status first: won and lost deals can keep an earlier pipeline stage. Map each open deal by its pipeline and stage together, not by stage name alone. |
value, currency |
value only in the workspace currency. Include other currencies in the import questions. |
owner_id |
owner through the user-to-member map |
expected_close_date |
expected_close_date |
pipeline_id |
Custom select field with the pipeline name when several pipelines share the workspace's stage list |
| Deal product rows | A deal line-item note linked through deal, per Data with no field of its own. List each item's name, quantity, item_price, discount, sum and currency. The deal's creation time is add_time. |
Activity
| Pipedrive data | Sofatofu field |
|---|---|
Activity type |
kind: call, meeting and email map directly. lunch maps to meeting. Completed task and deadline items map to note. Resolve custom types through the activity types list. |
Activity due_date, due_time |
occurred_at for a call, meeting or email with done: true. Check the time zone before joining these values. For completed tasks and deadlines, use marked_as_done_time. |
Activity subject |
subject |
Activity note, public_description |
body from note. Append public_description to the body after the label Description:. Check for HTML and convert it to text. |
Activity participants, attendees |
people. person_id names only the primary participant. Combine participants[].person_id and attendees[].person_id. An attendee can have an email but no person ID, so check for a matching imported person. |
Activity org_id, deal_id |
company, deal |
Note content |
body with kind: "note". Convert the HTML to text before applying the shared long-body rule. |
Note add_time |
occurred_at. Convert the UTC value from YYYY-MM-DD HH:MM:SS to YYYY-MM-DDTHH:MM:SSZ. |
Note person_id, org_id, deal_id |
people, company, deal |
| Email message | kind: "email", with its subject, body, send time and linked contacts or deal. Verify the returned field names. |
An overdue activity with done: false does not prove that the event happened. Ask whether past calls, meetings and emails in that state happened before mapping their event times. Include missing dates, times, unresolved custom types and items linked only to a project in the import questions.
Custom fields
In v2, values are in custom_fields under field codes. Field definitions give each code's field_name, field_type and options. Leads inherit deal custom fields, but use the v1 response shape. Inspect that shape rather than applying the v2 parser to it.
Pipedrive field_type |
Sofatofu custom field |
|---|---|
varchar, varchar_auto, phone, text |
text. Check large text values against the Sofatofu text limit. |
double |
number |
monetary |
currency. The v2 value contains both value and currency, so group by currency before mapping. |
enum |
select, with the option label |
set |
multi_select, with the option labels |
date |
date |
daterange |
Two date fields from value and until |
time, timerange |
text with the time or range and its timezone_name, when present |
address |
text from formatted_address or value |
user, org, people |
text with the linked item's name, not a record link |
For organizations, people and deals, include_option_labels=true resolves custom option IDs. include_labels=true adds label names next to label_ids. Otherwise resolve IDs through the field definitions. A Pipedrive custom currency is not necessarily an ISO 4217 code. Check it before mapping to a currency field.
Source IDs
Apply the shared Source IDs rules with pipedrive as the source. Organizations, people, deals, activities, notes and mail messages each have a numeric id. A lead has a UUID id.
- Activities, notes and mail messages all become Sofatofu activities. Pipedrive does not document that their IDs differ, so treat them as objects that can give the same ID.
- A deal line-item note is a record you build from its deal, not a Pipedrive note.
- A contact that receives lead fields keeps its person or organization identity. The lead UUID does not replace the contact's ID.
- Check that each ID column holds Pipedrive IDs. If a file has none, read the API or ask for a new export. Without IDs, follow Source IDs for rows with no stable ID.
What does not come in
Apply When data doesn't fit to these Pipedrive items:
| Pipedrive data | Limit |
|---|---|
| Email messages, when you read only export files | These exports do not contain the messages. Read them through the API, or list the loss in the import questions. |
Future activities and activities with done: false that the user does not confirm |
Planned work, not completed activity |
| Activity counts, weighted value and rotten time | Pipedrive computes these values. Sofatofu does not. |
Deal flow, field changelogs and stage history |
These do not become Sofatofu changes. |
| Product catalog, Projects, Campaigns, subscriptions, installments and goals | These have no matching record type. |
| Files, Google Drive files and call recordings | These do not become attachments in Sofatofu. |
Deal person_id, deal participants, organization parent and related relationships |
These have no matching record link. |
| Filters, Insights reports, dashboards, automations and web forms | These do not become workspace configuration. |