> 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/circa/best-practices.md). # Best Practices ## Recommended setup


Start with your anchor entity	Events is the core of Circa's data model. Build your first data flow around Events, then use Join to bring in Event contacts and Contacts for a complete picture.
Pull field definitions separately	Add Event fields, Contact fields, or Company fields as a separate source in your data flow. This lets you reference custom field metadata without cluttering your main entity output.
Use Join for relationship data	Company contacts and Event contacts only contain IDs. Always pair them with a Join transformation against the Contacts entity so your output includes actual names and contact details.

## Data refresh and scheduling


Set your start date thoughtfully	A start date that's too far back will pull years of event history on every refresh. Set it to match the reporting window you actually need — for example, the start of the current quarter or fiscal year.
Run a manual sync first	Before scheduling, complete a successful manual run and verify the row counts match what you'd expect in Circa. This catches configuration issues before they silently affect your scheduled reports.

## Performance optimization


Split large data flows	If you're pulling many entities — Events, Contacts, Companies, and their relationship tables all at once — consider splitting them across two data flows to stay within Circa's API rate limits.
Use Append for multi-account reporting	If your organization has more than one Circa account, use Coupler.io's Append transformation to combine data from all accounts into a single destination without manual merging.

## Common pitfalls {% hint style="danger" %} Don't use relationship entities (Event contacts, Company contacts) as your primary reporting table — they only contain IDs and will produce unreadable reports without a Join against Contacts. {% endhint %} {% columns %} {% column %} **Do** * Join Event contacts with Contacts to get full attendee details * Pull custom field definition entities separately from value entities * Verify row counts with a manual run before scheduling * Use Aggregate to count contacts per event or company {% endcolumn %} {% column %} **Don't** * Rely on relationship entities alone without joining to Contacts * Set a start date at the beginning of time — pull only what you need * Put every Circa entity into a single data flow if you're hitting rate limits * Ignore the updated\_at field — it's your best signal for detecting changed records {% 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/circa/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.