Browse the api reference

Report an External Sync

post/v1/graphs/{graph_id}/connections/{connection_id}/sync-report

Part of Connections.

For an external connection: the integration reports a run it just finished. The platform runs no sync for an external source, so this is how the connection's last_sync moves. A 'succeeded' report sets it to now; a 'failed' one records the outcome and leaves it. For an external ledger that keeps an entity's books, a period close reads last_sync to tell whether the books it mirrors are current. Refused (400) for a connection the platform syncs itself.

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

NameTypeDescription
graph_idrequiredstringGraph Id
connection_idrequiredstringUnique connection identifier

Request body

Required, application/json.

FieldTypeDescription
statusrequiredstring

'succeeded' moves last_sync to now. 'failed' records the outcome and leaves last_sync where it was.

One of: succeeded, failed

countsoptionalobject

What the run did, as the integration counts it (for example entries_sent, entries_replaced, entries_withdrawn). Shown with the connection; nothing reads the names.

messageoptionalstring

A line about the run: the window it covered, or why it failed.

Constraints: at most 500 characters

Example request

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

Responses

200 Successful Response

FieldTypeDescription
connection_idrequiredstring

Unique connection identifier

providerrequiredstring

Connection provider type

entity_idoptionalstring

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), the entity an external ledger source was registered for, and none for any other external source, whose events name their own.

keeps_booksoptionalboolean

Whether this connection is the ledger of record for entity_id: its books are kept in the connected system, and write_policy says whether entries are written back to it or only mirrored. False for a bank feed or an external source that is not a ledger.

Default: false

statusrequiredstring

Connection status

created_atrequiredstring (date-time) | string

Creation timestamp

updated_atoptionalstring (date-time) | string

Last update timestamp

last_syncoptionalstring (date-time) | string

Last sync timestamp

write_policyoptionalstring

Outbound write policy: 'qb_authoritative' (QuickBooks is the book of record and RoboSystems-originated entries publish to it at close), 'shadow' (the connected ledger is the book of record, nothing is written to it and the close posts nothing locally; the only policy an external ledger source can hold), or 'native' (no external ledger; what severing leaves). It governs the books of entity_id, and only on the connection that keeps them. Set via the write-policy endpoint.

source_nameoptionalstring

External-provider registered source slug — the value the integration stamps on the events it emits. Null for platform providers.

metadatarequiredobject

Provider-specific metadata

StatusMeaning
400Invalid request
401Authentication required
403Access denied
404Resource not found
422Validation Error
429Rate limit exceeded
500Internal server error