Core concepts and patters
To build a high-performance integration with Commusoft, it is important to understand the architectural patterns we use across all our endpoints.Side-Loading (The include Pattern)#
To reduce network "chattiness" and improve frontend performance, we allow you to "side-load" related data into a single request using boolean query parameters.Example: Pipelines & StagesInstead of making two calls—one for a pipeline and one for its stages—you can request them together:
GET /v2/settings/opportunityPipelines?includeStages=trueKey Rule for Side-LoadingOpt-in Only: By default, related objects are not returned. You must explicitly set the include parameter to true.Consistency: If an endpoint supports side-loading, it will always use the include{ResourceName}=true naming convention.Standard page/offset pagination often results in skipped or duplicated records when data is added or removed during traversal. We use Numeric Cursors to solve this.How it works:
A cursor is simply the numeric id of a record.after: Returns records with an ID greater than the cursor.before: Returns records with an ID less than the cursor.The Pagination Object
Every collection response includes a pagination object. Use the nextCursor and prevCursor provided here to navigate; do not attempt to calculate these manually.Actions vs. Updates#
The Commusoft API distinguishes between updating a resource's attributes and triggering a business process.Updates (PATCH): Use these for simple changes, like updating a property's address or a customer's name.Actions (POST): Use these for state transitions or complex workflows, such as "Putting a Job on Hold." Actions handle all background validations and side effects (like sending notifications) automatically.Stability & Tie-Breaking#
To ensure your data remains in the correct order across multiple pages, the API applies a Deterministic Tie-breaker. Even if you sort by a non-unique field (like lastUpdatedDateTime), the server will always append a secondary sort by id to ensure the order never drifts between requests. Modified at 2026-03-02 11:24:35
