Documentation version: 2026-11-16.2
Canonical: https://docs.creator.gg/guides/data-ingestion.md

# Import and sync people, companies and memberships

Use this guide when feeding new data, new users, contacts or companies into Creator Platform. It covers initial import/backfill and ongoing sync for every customer. Product users usually become CRM contacts, not staff logins. CRM companies are customer organizations, not your account's business-profile settings. Saving business intelligence is not importing CRM records.

## 1. Choose an existing supported route
Call workspace_status and confirm the business. Reuse its working connection. Discover the actual tool schemas, then select the smallest route that fits:

| Need | Supported route | Authentication and limits |
| --- | --- | --- |
| Initial contact CSV import/backfill | Native Contacts import, opened by contacts_import_export | Normal account sign-in. Review field mapping, deduplication and automation settings in the import UI. The tool returns a link, not an import job. |
| Contact writes from an agent or existing app/backend | contacts_fields_list/create, contacts_upsert, contacts_update and contacts_get | Existing Creator connection for the agent; a separately named Creator app OAuth connection for software calling Creator tools (not a requirement for a generated inbound webhook). See [App integrations](https://docs.creator.gg/guides/app-integrations.md). |
| Ongoing inbound contact events without a custom worker | Native Automation workflow: Inbound Webhook, Find Contact, found update / not-found create | Account-generated secret webhook URL, enabled native workflow and premium-trigger availability/usage. See [Creator Platform integration setup](https://docs.creator.gg/guides/native-data-ingestion.md). This is not a static REST endpoint at mcp.creator.gg. |
| Company creation, company fields and custom contact-company memberships | Native Companies/Custom Fields/Associations screens, or enabled Creator Platform workflow actions | Company reads exist in Creator tools. Company writes and relation writes are not exposed as working MCP mutations today. Use the Creator Platform setup guide below for supported controls and precise execution limits. Absence from MCP is not absence from the product. |

Read [Creator Platform integration setup](https://docs.creator.gg/guides/native-data-ingestion.md) before configuring an integration. It explains route-specific authentication, human private integration setup where needed and account controls. Do not assume a custom worker is required before checking the native webhook/actions. Do not assume native webhook availability from an MCP workflow error either. If the actual account lacks a required native control, report that specific feature/permission and use an available supported route, without changing the working Creator grant.

## 2. Define identity and field mapping before backfill
Choose the owner's identity policy. Ongoing EMAIL matching is valid, including for a forward-only new-user feed. External-ID matching and source-to-contactId mappings are recommendations or alternatives, not prerequisites. No external-ID field, backfill or historical import is required for forward-only ingestion. Create only missing fields actually needed by the selected mapping. Honor explicit owner-selected integration scopes, including ALL available scopes; default limited-scope advice does not override that choice.

When stable source identity is useful, retain source system + external user ID to contactId, and organization ID to company ID mappings. Email, phone, name and website can change or be shared; explain the consequence of the selected match policy rather than silently replacing it. Custom fields do not automatically become uniqueness constraints.

Prepare definitions once per account, then write record values. contacts_fields_list discovers live IDs, fieldKey and types; contacts_fields_create creates a definition, not a value. Example call envelopes below show tool plus arguments. MCP tools/call uses name plus arguments; the runtime uses client.call(tool, arguments). Replace all example IDs with returned account-owned IDs.

```json
{"tool":"contacts_fields_create","arguments":{"name":"External product user ID","dataType":"TEXT","requestId":"schema-external-user-001"}}
```

Read the returned definition and contacts_fields_list, then save its ID in the integration's private mapping. Do not recreate it per user or copy a field ID from another account. See [Typed contact fields](https://docs.creator.gg/guides/contact-fields.md) for settings/value encodings. Company fields use a different native contract, not contacts_fields_create.

## 3. Initial people import and reconciliation
Fully paginate source people and destination contacts. Reconcile existing records first, using known source-to-contact mappings and the account's deduplication rules; ambiguous matches need record-level resolution, not guessed merges. For an explicitly requested native CSV import, map the selected columns and retain the import results/errors. Inspect enabled workflows before a backfill that could trigger them. Importing a person is not marketing consent.

For an initial person with email/phone and no established CRM ID, contacts_upsert follows account email/phone deduplication. It is not an external-ID upsert. Example:

```json
{"tool":"contacts_upsert","arguments":{"email":"person@example.com","firstName":"Example","customFields":[{"id":"field_external_user_example","fieldValue":"user_1042"}],"requestId":"person-user1042-rev1"}}
```

Retain the returned contactId separately from operationId. A retained retry receipt may return data.references rather than the original record; resolve the contact reference and call contacts_get. Save the source ID to contactId mapping only after resolving the record. Inspect per-record outcomes rather than declaring the whole batch imported from an accepted request. A source user with neither email nor phone cannot be inserted through contacts_upsert; use an applicable native creation/import path instead of inventing an email address.

## 4. Ongoing sync and email changes
Under ongoing email matching, use the incoming email with contacts_upsert and account deduplication. No external-ID field or initial import is required. When the selected design retains a contactId mapping, update that known person by contactId, including when their email changes. Repeated upserts by a new email can create a second person. Do not combine the stable-ID match with an old email that would make the native Find Contact AND criteria fail.

```json
{"tool":"contacts_update","arguments":{"contactId":"contact_example","email":"new-address@example.com","customFields":[{"id":"field_external_user_example","fieldValue":"user_1042"}],"requestId":"person-user1042-rev2"}}
```

Only send fields this integration owns. Preserve unrelated fields, tags, do-not-contact, opt-outs and subscription preferences. Omitted fields and explicit null/empty values are different intentions. Use dedicated contacts_tags_add/remove rather than replacing every tag. Read contacts_get after changed values; contact creation does not subscribe the person, send email or authorize a workflow.

For a continuous feed, process changes in source revision/time order per entity; deduplicate events and retain a source checkpoint only after each covered page/batch is reconciled. Reconcile late/out-of-order events rather than letting an old value overwrite a newer one. A webhook normally covers new events, not historic records. A forward-only feed does not need a backfill. Run one only if separately requested, reconciling overlap with ongoing events. Do not delete CRM records because they are absent from one partial export. Rate-limit bounded batches; record saved, skipped, rejected and unresolved outcomes. Source-specific schedules belong in the customer's existing software or native automation, not a new hosted Creator agent.

## 5. Companies, fields and many-to-many membership
One contact can belong to multiple companies, and one company can have multiple contacts. Use custom contact-company associations for many-to-many memberships; keep the separate Primary Company relationship intact. Do not duplicate the person per company or replace membership with a comma-separated companyName. An organization billing/plan field belongs to the company; a contact-level summary is a derived summary, not the authoritative membership table.

Create/reconcile companies first, then contacts, then membership edges using their actual returned IDs and the chosen association definition/order. Native Companies supports create/edit and company custom fields. Use actual enabled Creator Platform actions and screens for company writes. See [Company setup and matching](https://docs.creator.gg/guides/native-data-ingestion.md). Creator crm_companies_list/get return bounded references, not full company custom-field values or company write tools.

Maintain a set of desired source-owned edges (person ID, company ID, association ID). Add missing links and remove only obsolete source-owned links, never another integration's edges, Primary Company, a whole association definition or either record. Preserve roles/labels and inspect workflow effects. Native Associations can add/remove and show linked records. Missing metadata is not a prohibition on many-to-many links. Creator's current crm_relations_* tools are validated Creator Platform handoffs, not executed membership writes. Use the returned Platform screen and verify the exact relationship outcome rather than claiming success or blindly replaying it. For simple company matching, paginate crm_companies_list, use a unique source organization-name match where possible, and report unmatched/ambiguous companies plainly without blocking contact ingestion.

## 6. Retry and outcome handling
Creator MCP mutations require a stable 8-128-character requestId per intended effect. Retain exact arguments and reuse only for an identical retry. Changed arguments need a new intended operation, not reuse of the old ID. A timeout is not failure. Retained receipts may contain references only; read the record and reconcile processing/unknown before continuing. See [Recovery](https://docs.creator.gg/guides/recovery.md).

Platform webhooks and native editing do not inherit Creator MCP requestId receipts or an exactly-once guarantee. Persist source event IDs/checkpoints in the sender where available, inspect native execution history and destination state, and reconcile uncertain creates before retrying. A webhook HTTP acknowledgement is not proof that every workflow action completed. Use the selected route’s actual account controls and error handling.

Report initial import, ongoing activation, fields created, values saved and memberships verified separately. A guide publication or successful mock is not a customer migration. Verify only the authorized changed records; no production imports, campaigns or new credentials are necessary merely to discover these instructions.
