Config V3 schema reference

ConnectorConfigV3 is the source of truth for a Plugsync connector’s configuration. This reference documents every field, the validators that will reject your config, and the workflow that promotes a draft to the running connector.

If you are a partner, plugin developer, or self-service customer authoring a connector config from the outside, this reference plus the three examples in examples.md is meant to be everything you need.

Top-level shape


{
  "version": "3.0",
  "entities": [],
  "flows": [],
  "sources": [],
  "settings": {}
}

sources is required (an empty list means “no sources”) and holds the definition of each of the connector’s event sources - {"name", "type", "config"} per entry - so a flow and the channel it reads from are reviewed, published and rolled back together. See EventSources for what goes in a config per type, and for the half of a source that is deliberately NOT in here (its enabled flag, its secret and its runtime state).

Where to read next

Page	What’s there
connector.md	Top-level fields (`version`, `entities`, `flows`, `sources`, `settings`, `conflicts`, `pipelines`, `ingress_profile`).
entities.md	`EntityV3`, `EntitySchemaSpec`, `IdentityConfig`, `FieldMapping`.
flows.md	`FlowV3` + the dispatch model.
step-actions.md	The step DSL: all 25 actions.
config-surface.md	The same catalog (actions, transforms, sources, JSON Schema), machine-readable via an endpoint.
simple-vs-federated.md	The two entity modes and when to pick which.
draft-publish.md	The draft->publish workflow with dashboard screenshots.
examples.md	Three narrated walkthroughs of complete configs, JSON inlined.
`_examples/`	The same three configs as standalone JSON files in the docs source tree. Their full text is inlined in examples.md above, which is the copy to use.

Prerequisites

Before any of this is useful:

You have a Plugsync org and an authenticated user.
You’ve completed the HubSpot OAuth flow once (so a HubSpot credential exists in your org).
You’ve created a connector via the dashboard or POST /api/connectors.

The connector starts with an empty draft. You author the config you want, review the diff, and publish.

First config in 30 seconds

Copy the acme-light config from examples.md into acme-light.json and send it to the draft. The config declares its own webhook source, acme_inbound, in sources, so nothing else has to exist first (rename it if you like: the flow and the source entry must keep the same name):


curl -X PATCH https://app.plugsync.com/api/connectors/<id>/draft \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @acme-light.json

Then open the connector workspace in the dashboard, click “Review changes”, and click “Publish v1” (or POST /api/connectors/<id>/publish). Your connector is now live, and the publish response carries the webhook’s signing secret once, in created_sources: keep it, it is what your sender signs each delivery with. See event sources.

Out of scope

This reference deliberately does not cover:

Event flow manifest authoring deep-dive. See event-flow-manifests/.
Plugin authoring (TypeScript). See the Plugin runtime guide.
v2 schema and v2->v3 migration. v2 is deprecated.