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

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.

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

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