> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/crm/capsule-crm/best-practices.md). # Best Practices ## Recommended setup


Join Opportunities with Stages and Pipelines	These three entities are most useful together. A standalone Opportunities export gives you deal data but not stage names or pipeline labels — join them to make your reports readable without extra lookups.
Add Lost reasons as a second source	The Opportunities entity only stores a lost reason ID. Pull in the Lost reasons entity and use a Join transformation to replace IDs with meaningful labels before sending data to your destination.
Use a start date that matches your analysis window	Set the start date to the earliest record you actually need. Pulling all historical data every sync adds time and volume — scope it to the period relevant to your reports using the date picker.
Export Custom fields separately, then join	Custom fields live in their own entity. Add them as a second source in your data flow and join them to Parties or Opportunities by record ID to enrich your main contact or deal table.

## Data refresh and scheduling


Run a successful manual sync before scheduling	Coupler.io requires a completed manual run before you can activate a schedule. Verify the data looks correct in your destination first — then set up your refresh cadence.
Match refresh frequency to your sales cycle	If your team updates deals daily, a daily refresh is sufficient. Syncing more frequently than your team actually updates records doesn't add value and burns through API quota faster.

## Performance optimization


Split large entity syncs into separate data flows	If you're pulling Parties (which can be large) alongside multiple smaller entities, put Parties in its own data flow. This prevents one slow entity from blocking others and makes troubleshooting easier.
Use Aggregate for summary reporting	Instead of exporting all raw opportunity rows to a spreadsheet and summing there, use Coupler.io's Aggregate transformation to group by owner, stage, or pipeline before the data lands — your destination stays lean and fast.

## Common pitfalls {% hint style="danger" %} Don't rely on opportunity value totals if your account uses multiple currencies. Capsule CRM does not convert values — summing across currencies will produce misleading totals. Always filter or group by currency before aggregating deal values. {% endhint %} {% columns %} {% column %} **Do** * Join Opportunities, Stages, and Pipelines for readable pipeline reports * Use the `type` field to separate Person and Organization parties * Check the `lostReasonId` field and join to Lost reasons for meaningful analysis * Keep your start date scoped to your actual reporting window {% endcolumn %} {% column %} **Don't** * Assume Custom fields will appear automatically in Party or Opportunity exports * Sum opportunity values across multiple currencies without filtering first * Run all 16 entities in a single data flow if you don't need all of them * Ignore duplicate party records — match on email to deduplicate before analysis {% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coupler.io/sources/category/crm/capsule-crm/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.