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

# Creator Platform integration setup and ongoing ingestion

This guide complements [Import and sync data](https://docs.creator.gg/guides/data-ingestion.md). Use Creator tools, the Creator runtime or Creator Platform's own automation and settings. A connected agent has the operations actually exposed by its Creator tool catalogue and current account permissions, not arbitrary account administration or undocumented APIs.

## Choose authentication for the selected route

- **Connected agent:** reuse its existing Creator workspace connection. Call workspace_status and inspect the relevant tool schema. Do not reconnect just to read docs or use an already-authorized operation.
- **App/backend using Creator tools:** create a separately named Creator app connection using the supported helper and client in [App integrations](https://docs.creator.gg/guides/app-integrations.md). This route uses Creator OAuth and durable rotating-token storage; routine execution needs no agent or model. Do not export the agent's existing token store.
- **Creator Platform inbound workflow:** use its generated secret webhook URL. A plain HTTP sender posts to that URL; it needs neither a separate Creator app OAuth connection nor a private integration key for this webhook route.
- **An integration explicitly requiring a private integration credential:** an authorized human can create or reuse a named integration in the correct Creator Platform account, Settings → Private Integrations, where available. Human creation is a supported setup step. There is no documented Creator tool that automatically mints this credential. Do not invent an endpoint or retrieve an internal service grant. This key is not a Creator MCP/OAuth credential and cannot be substituted in the Creator runtime.

For private integration setup, select the permissions required by the intended integration and supported by the account. Limited scopes are a default recommendation only when the owner has not selected a policy. **Honor explicit owner-selected scopes, including ALL available scopes.** Do not narrow an authorized all-scopes integration or ask again merely because a default suggests fewer scopes. Account roles, available permissions and actual operation authorization still apply; no choice grants another account's access. If a required setting or permission is absent, report that exact control, not that the entire Creator connection cannot work.

Reuse a suitable named integration before creating another. Transfer its credential directly into the authorized destination's private secret field or server-side secret store through the supported protected credential flow. Keep keys, webhook URLs and rotating credentials out of chat, logs, browser bundles and source. Never export Creator's internal service credentials. Bind destination configuration to the intended account in trusted server code; do not accept caller-selected account IDs from public forms. A saved secret alone does not establish authorization or activation: verify the selected integration's own account access before enabling delivery.

## Ongoing contacts through a Creator Platform workflow

In the intended account, open Automation → Workflows. Select Inbound Webhook and retain its generated URL privately. Capture one representative source request, choose its mapping reference and map the incoming fields into the account's actions. The URL comes from that workflow, not a fixed public endpoint. Possession of the URL can trigger it. Do not claim signature or Bearer verification unless that control actually exists in the selected route; use the sender's supported integration or its existing backend verifier when signed verification is required.

Example sender JSON, a fictional source schema rather than a Creator tool contract:

```json
{"event_id":"evt_example_1","email":"person@example.com","first_name":"Example","company_name":"Example Company"}
```

1. **Choose the owner's identity policy. Ongoing EMAIL matching is valid.** For that policy, Find Contact uses the incoming email; Contact Found updates source-owned fields, Contact Not Found creates the contact. Do not treat a failed or ambiguous search as not-found. Multiple conditions can combine with AND; do not add an external-ID condition that excludes the intended email match.
2. An external user ID and saved contactId mapping are optional alternatives/recommendations where stable source identity is useful. They are not mandatory. For a forward-only new-user feed, **no external-ID field creation, backfill or historical import is a prerequisite**. Create only missing fields actually needed by the selected mapping. Historical import remains a separate owner decision.
3. Email can change or be shared. Under email matching, a new email may create another contact; report this identity-policy consequence rather than silently switching to a mandatory external-ID design. With an established contactId mapping, contacts_update can update the same contact across an email change.
4. Configure repeat entry and event ordering/deduplication for the source. Save/publish only the requested sync, then dispatch one authorized user and inspect workflow history plus contacts_get/current contact values. Keep ingestion-only actions separate from messages or other external effects. A repeated webhook may repeat actions; this is not an exactly-once service.

Inbound Webhook may require an enabled account feature and incur usage. Its presence in documentation does not prove activation. An unavailable MCP workflow-definition tool does not prove the Platform editor or its actions are unavailable. Conversely, do not claim that a documented action is enabled in every account. Keep the working connection and state the exact observed capability.

## Contact tools and required fields

The supported Creator app runtime calls the same named tools as an agent: contacts_fields_list/create for definitions, contacts_upsert for email/phone deduplication, contacts_update for an existing contactId, and contacts_get for verification. For an email-authoritative feed, supply email without an unrelated phone identity; account deduplication settings still govern upsert. A custom field is not automatically a unique upsert key.

Create required missing definitions once, retain returned field IDs and send customFields with fieldValue for values. Do not create an external-ID field merely because an example mentions one. Preserve unrelated fields, tags, DND, opt-outs and subscription choices. Contact ingestion is not marketing consent. See [Contact fields](https://docs.creator.gg/guides/contact-fields.md) and [App integrations](https://docs.creator.gg/guides/app-integrations.md).

## Match companies where possible

Use crm_companies_list and crm_companies_get to inspect existing companies in the connected account. Follow pagination and deduplicate IDs before deciding a company does not exist. Match a usable source organization name, with website or a known CRM ID where available. Names and domains are not guaranteed unique; a personal email address alone does not establish a company. Resolve only a unique supported match and report unmatched or ambiguous organizations without blocking unrelated contact ingestion.

Primary Company and custom many-to-many memberships are different relationships. Preserve existing assignments and unrelated links. Creator Platform's Contacts/Companies/Associations screens support native assignment and custom membership editing. Current Creator crm_relations_* tools return explicit handoffs rather than executed relationship writes; follow the returned Creator screen link and verify the exact pair. Do not describe a handoff as a completed association, duplicate a contact per company, or infer that many-to-many membership is unsupported. Company custom fields use the Platform's company field controls, not contact-field definitions. Use actual enabled workflow actions where available. No raw provider API, provider tool catalogue or internal grant is needed as a customer-facing setup instruction.

## Retry and acceptance

Creator tool mutations require a stable 8-128-character requestId for each intended effect. Retain exact arguments and reuse the ID only for the identical retry. A timeout is not a failed write. Reconcile processing/unknown outcomes and referenced records before another request. See [Recovery](https://docs.creator.gg/guides/recovery.md).

Webhook delivery and Platform editing do not inherit Creator MCP receipts or an exactly-once guarantee. Retain sender event identities/checkpoints, inspect execution history and destination state, and reconcile uncertain writes before retrying. An HTTP acknowledgement is not proof all actions completed. Do not use a new request identity to evade uncertainty.

Report documentation/setup, credential authorization, saved destination config, activation, test dispatch, actual contact values and company association separately. For a forward-only request, test only the authorized one user and process future events; do not add billing sync or a bulk import. Never claim an automatic credential mint, full arbitrary API access or a verified membership from a docs read.
