Best Practices

Recommended setup

Start with Agreements as your anchor entity

Agreements hold the most critical fields — status, dates, counterparty, tags, and folder IDs. Build your primary data flow around this entity, then join other entities to enrich it.

Use a dedicated API key for Coupler.io

Create a read-only API key specifically for your Coupler.io integration rather than reusing a personal key. This makes it easy to revoke access without disrupting other integrations.

Join Tags and Folders to Agreements

The Agreements entity stores tag and folder references as IDs. Add Tags and Folders as additional sources in the same data flow and use Join transformations to replace IDs with human-readable names before sending data to your destination.

Data refresh and scheduling

Set refresh frequency based on contract activity

If your team processes a high volume of agreements weekly, a daily refresh keeps your reports current. For quieter periods or archival reporting, a weekly sync is usually sufficient.

Sync Organization members separately

Member and permission data changes infrequently. Run it as a separate, lower-frequency data flow rather than including it in your main agreements sync — this reduces unnecessary API calls.

Performance optimization

Append data from multiple Concord orgs

If your team manages contracts across multiple Concord organizations, create one data flow per org using each org's API key, then use Coupler.io's Append transformation to merge them into a single unified dataset.

Use Aggregate for executive reporting

Rather than dumping raw agreement rows into a board-level dashboard, use Coupler.io's Aggregate transformation to pre-summarize counts by status, type, or counterparty. This keeps destination sheets clean and fast to load.

Common pitfalls

Don't rely on the Reports entity as your only source of agreement data. Concord's Reports are pre-built snapshots — they don't expose all agreement fields and can't be filtered or joined the same way as the raw Agreements entity.

Do

• Pull Tags and Folders as separate entities and join them to Agreements
• Use a dedicated, read-only API key
• Run a manual test before scheduling recurring syncs
• Use Append transformations when combining data from multiple Concord orgs

Don't

• Assume the Reports entity contains all your agreement fields
• Reuse a personal API key that could be rotated or revoked unexpectedly
• Try to reconstruct folder hierarchies without joining the Folders entity to itself using parent folder IDs
• Mix org-level data from different Concord accounts without labeling the source org in your destination