Skip to main content

Synchronization best practices

This guide answers the most common questions we get when a customer connects their IT system to Stonal and starts keeping assets, data, and documents in sync. It complements the ingestion and search guides with practical recommendations drawn from real integrations.

How often should I synchronize?​

There is no hard rule — the right cadence depends on how quickly your source data changes and how fresh it needs to be on Stonal.

  • A once-a-day synchronization is a good default and is enough for most use cases (asset structure, properties, contracts).
  • Increase the frequency for data that changes often or that downstream users expect to see quickly.
tip

Pick the lowest frequency that meets your freshness requirement. A nightly batch is simpler to operate and easier to monitor than a near-real-time stream, and it is sufficient for the vast majority of integrations.

Should I send everything every time, or only what changed?​

Send only what changed. A full reload on every run is wasteful and slower as your dataset grows.

  1. Initial load — import your full dataset once (see Ingesting data).
  2. Incremental sync — on each subsequent run, fetch only the assets that changed since your last run with the search API's differential update filter (updatedAtAfter), then upsert them back.
🔎 fetch only assets updated since the last sync
"search": {
    "updatedAtAfter": "2025-09-12T00:00:00"
}

To also catch assets that were deleted since your last run, add includeDeleted:

🔎 include deletions in the differential sync
"search": {
    "updatedAtAfter": "2025-09-12T00:00:00",
    "includeDeleted": true
}
tip

Store the timestamp of each successful sync and use it as the updatedAtAfter value for the next run.

Store and use the asset uid​

Every asset created in Stonal has a stable, Stonal-generated unique identifier: its uid. This is distinct from the external IDs you provide, which link the asset to your own systems.

  • Keep storing your own external IDs — they are how you recognize the asset on your side, and you can attach several of them per asset.
  • Also store the uid returned by the ingestion API alongside them. The uid is the most reliable way to refer to an asset for updates, and it is required for some operations — for example, deleting an asset and changing an external ID can only be done by uid.
info

Most write operations let you reference an asset by either its uid or one of its external IDs. Prefer the uid when you have it.

Lessons learned from other integrations​

  • Tune your batch size. The ingestion API accepts several assets per request. We recommend keeping batches to no more than ~500 items and running a few tests to find the size that performs best for your payload — the optimal value depends on what you send (assets, properties/data, relations) and how heavy each item is. Start smaller and increase gradually.
  • Ask us for example queries. If you are unsure how to express a particular import or search, contact API support — we are happy to provide a ready-made request for your use case.
  • Tell us when the documentation is unclear. Feedback on these guides helps us improve them for you and for the next integrator.
tip

Need a hand getting started? Reach out to API support by email or Slack — see Getting started for how to get an account and credentials.