Choose the row you are counting
Count appointments as visits, assignments as member assignments, and distinctjob_id values as jobs. One appointment can have several technicians; one technician can have several appointments for the same job. Assignment presence and scheduled duration do not prove attendance or hours worked. Missing execution status is null. Missing confirmation/cancellation state means false, matching the application’s current visit state. Member business-unit assignments retain recorded calendar ranges with inclusive start_date and inclusive end_date; a null end has no recorded end. Do not replace a job’s recorded business unit with the member’s current business unit.
Customer relationships
Account/contact and account/location associations can be many-to-many.is_primary and relationship archived belong to a particular account association; a location has no global archive flag. Contact association IDs identify individual links. Replace complete embedded relationship sets when refreshing a parent, including links that changed primary/archive state. Lifecycle statuses likewise remains complete and follows configured order, with unsequenced statuses ordered by creation time and ID.
Job status and attribution
Jobs expose the current configured status name alongside its existingstage and special_status meaning. Work completion and lifecycle closure are separate: a canceled job can retain a completion timestamp, and reopening can clear closure. These values are not a status-transition history. Nullable outcomes remain unknown, rather than false. A job’s lead_sources are its explicitly recorded source links; account acquisition sources are separate and are never substituted for missing job attribution. created_by records creation activity; it does not identify the seller or dispatcher.
Member and archive state
Operational records retain inactive and archived state by default; archive filters are optional. Boolean filters accept onlytrue or false. A team member’s roles describe business responsibilities, never API permissions. Membership determines visibility: deactivated members remain readable, but users who no longer belong to this company are unavailable. Membership created_at means when the member was added. updated_at is explicitly null because no member-level edit timestamp is available; updated_since is unsupported for team members.
Date filters and edits
Assignments also returnupdated_at: null and reject updated_since: reassignment and rescheduling do not maintain that timestamp. Their separate status_updated_at describes only execution-status edits. All remaining timestamped operational collections support created_from, created_before, and inclusive parent updated_since. Locations may have a null update time, which does not match that filter. Child association, role, confirmation, cancellation, and execution-status changes can alter responses without advancing parent timestamps. Job classes have no timestamps. An account’s customer_since is its recorded customer-since instant, which may predate its technical created_at after an import; it is not inferred from the first job or payment.
Jobs additionally accept company-local date bounds completed_from/completed_before for work_completed_at, and closed_from/closed_before for lifecycle_closed_at. The start is inclusive and the end exclusive. A local day can span 23 or 25 hours across daylight-saving changes. Appointment and assignment starts_from/starts_before instead accept precise instants and filter the recorded start, not any overlap with a range. Use the company’s timezone when grouping returned timestamps into local reporting periods.