Before writing any code, decide which integration pattern fits your use case. The right pattern determines which API approach, authentication flow, and sync strategy to use.
| Use case | Recommended approach |
|---|---|
| Validate or retrieve one record while a user is waiting | Direct app-specific API endpoint |
| Pull all records for a dataset, such as event registrations | Saved query or Query API |
| Pull records modified since the last sync | Query API with sys_last_modified_at criteria |
| Populate a mobile app, vendor database, or external cache | Scheduled Query API syncs |
| Pull data across multiple Rhythm apps or modules | Query API |
| Let customer admins adjust fields or filters without code changes | Saved Rhythm query |
| Browser login, WordPress login, or SSO | Applicable SSO guide |
Use direct app endpoints for real-time, record-specific workflows. Use the Query API for scheduled syncs, reporting-style extracts, cross-app datasets, and incremental jobs.
| Integration scenario | Recommended flow |
|---|---|
| Scheduled script, backend sync, batch job, or server-to-server process with no user present | Client Credentials / M2M |
| Server-rendered website where a real user logs in | Authorization Code |
| Mobile app or single-page application where a real user logs in | Authorization Code with PKCE |
| Browser login, SSO, WordPress, or redirect issues | Applicable SSO guide |
If a real user is involved, do not use Machine-to-Machine authentication. M2M tokens are not user-specific and count against the customer's monthly token limit. See the authentication guide for caching requirements.
For integrations that only need changed records, filter your query on the sys_last_modified_at field using a rolling lookback window rather than an exact timestamp. A rolling window protects against missed runs, time zone edge cases, and replication lag.
Recommended pattern:
- Build or save a query in Rhythm
- Filter to the specific business context (e.g.,
event_idorcontext_id) - Include
sys_last_modified_atas an output field - Set criteria to records modified within the last 24–48 hours
- Run the query on a schedule
- Upsert records in the external system using the Rhythm record ID
- De-duplicate records that appear in overlapping sync windows
Handling status changes
Do not filter out cancelled or inactive records in incremental syncs unless the downstream system has another way to deactivate them. Include status changes so the external system can update or remove records accordingly.
ID correlation
Rhythm uses different IDs for different purposes — do not assume one ID serves every need. For event registration integrations, store all three:
| ID | Represents |
|---|---|
contact_id | The person / contact record |
id | The specific registration record |
event_id / context_id | The event or program that this record exists under |
A single contact may have multiple registrations (for example, if they cancel and repurchase), so storing only the contact ID is not sufficient to identify a specific registration.
| Static query | Saved query | |
|---|---|---|
| Query definition lives in | Your code | Rhythm (referenced by ID) |
| Use when | Field list should be version-controlled; filters should not change without a release | Customer admins may need to adjust fields; Support needs to help refine filters |
See the Query Guide for how to build and execute both types.