Create Connection

post/v1/graphs/{graph_id}/connections

QuickBooks and Mercury: returns a pending connection — complete the OAuth flow to activate (Mercury may instead connect at once with a personal API token where the deployment allows it). External: registers a source namespace for an integration that writes through the public API. One connection allowed per provider per graph, except 'external' which allows one per source_name and 'plaid' which allows one per bank login (a connection still waiting on Link is returned instead of a second). Plaid: returns a pending connection — POST /oauth/init returns a link_token for Plaid Link. A bank feed (Mercury, Plaid) names the entity its accounts book to (entity_id, the group parent when omitted) and is refused (409) when that entity has no chart of accounts or is the one QuickBooks keeps. QuickBooks keeps the group parent's books only: entity_id may be omitted, and naming a subsidiary is refused (409 PARENT_ONLY); it is refused (409) too when the group parent's books are already native. Every connection's entity_id is the entity whose books it keeps.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id

Request body

Required, application/json.

Field Type Description

providerrequired

string

Connection provider type

One of: quickbooks, external, mercury, plaid

entity_idoptional

string

QuickBooks: the entity whose books it keeps, which can only be the group parent; omit it. A bank feed names its entity on its own config.

Constraints: at least 1 character

quickbooks_configoptional

QuickBooksConnectionConfig

QuickBooks-specific connection configuration.

QuickBooksConnectionConfig fields

Field	Type	Description
`realm_id`optional	string	QuickBooks Realm ID
`refresh_token`optional	string	OAuth refresh token

external_configoptional

ExternalConnectionConfig

External-integration connection configuration. Registers a source namespace for an integration the platform does not run: the connection is registration + telemetry, not execution config. The platform holds no credentials for the external source — the integration authenticates to its own source and writes here through the public API, stamping source_name on everything it emits.

ExternalConnectionConfig fields

Field Type Description

source_namerequired

string

Source slug the integration stamps on the events it emits (lowercase letters, digits, '-', '_'; must start with a letter). Unique per graph among live connections.

Constraints: 2–64 characters; matches ^[a-z][a-z0-9_-]{1,63}$

display_nameoptional

string

Human-readable label for the connections UI.

Constraints: at most 128 characters

mercury_configoptional

MercuryConnectionConfig

Mercury bank-feed connection configuration. A bank feed is native accounting: the entity its accounts land on must already have a chart of accounts and must not be the one QuickBooks keeps (the group parent, while QuickBooks is connected). Over OAuth (the hosted default) the connection is created pending_oauth and activated by the callback. api_key — a personal **read-only** Mercury token — connects at once without a browser round-trip, but only on deployments that turn on MERCURY_API_KEY_CONNECTIONS_ENABLED (self-hosted and local); the hosted product refuses it.

MercuryConnectionConfig fields

Field	Type	Description
`since_date`optional	string (date)	First day of the backfill (ISO 8601). Defaults to two years back. Incremental syncs never look back before it, and lines dated in a closed period are never captured.
`include_treasury`optional	boolean	Capture treasury-account activity alongside checking/savings. Default: `true`
`api_key`optional	string	A personal read-only Mercury API token, for deployments that allow the api_key credential mode. Omit to connect over OAuth. Constraints: at least 8 characters
`entity_id`optional	string	The entity whose books the feed's accounts land on: a subsidiary's id, or omit for the group parent. Required when QuickBooks keeps the parent's books. Each account can be moved to another entity later with `link-bank-account`.

plaid_configoptional

PlaidConnectionConfig

Plaid bank-feed connection configuration. A bank feed is native accounting: the entity its accounts land on must already have a chart of accounts and must not be the one QuickBooks keeps (the group parent, while QuickBooks is connected). The connection is created pending_oauth; POST /oauth/init returns a link_token for Plaid Link, and the public_token Link hands back completes it through POST /oauth/callback/plaid (as code). One connection per institution login; a graph can hold several.

PlaidConnectionConfig fields

Field	Type	Description
`since_date`optional	string (date)	First day of the backfill (ISO 8601), and how much history Plaid is asked to pull for the new Item (at most two years). Defaults to as far back as Plaid goes. Lines dated in a closed period are never captured, whatever the window.
`entity_id`optional	string	The entity whose books the feed's accounts land on: a subsidiary's id, or omit for the group parent. Required when QuickBooks keeps the parent's books. Each account can be moved to another entity later with `link-bank-account`.

Example request

curl

curl -X POST "https://api.robosystems.ai/v1/graphs/{graph_id}/connections" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "quickbooks"
}'

Responses

201 Successful Response

Field	Type	Description
`connection_id`required	string	Unique connection identifier
`provider`required	string	Connection provider type
`entity_id`optional	string	The entity whose books the connection keeps: the group parent for QuickBooks, the entity a bank feed was connected for (each of its accounts can move to another entity later), none for an external source, whose events name their own.
`status`required	string	Connection status
`created_at`required	string (date-time) \| string	Creation timestamp
`updated_at`optional	string (date-time) \| string	Last update timestamp
`last_sync`optional	string (date-time) \| string	Last sync timestamp
`write_policy`optional	string	Source-of-truth write policy: 'native' (RoboSystems is authoritative; no outbound write-back) or 'qb_authoritative' (QuickBooks is authoritative; RoboSystems-originated entries publish to QB). Set via the write-policy endpoint.
`source_name`optional	string	External-provider registered source slug — the value the integration stamps on the events it emits. Null for platform providers.
`metadata`required	object	Provider-specific metadata

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Connection already exists for this provider
422	Validation Error
429	Rate limit exceeded
500	Internal server error