Overview

Dynamic Planner APIs follow a common pattern for retrieving collections of data, using pagination to ensure responses remain efficient and predictable, and filtering to narrow datasets based on precise criteria. This behaviour is consistent across services.

Pagination Model

Endpoints that return collections use a simple, predictable pagination scheme built around two query parameters:

• pageSize — Maximum number of items to return in a single page.
• pageNumber — The page index to retrieve (starting from 1).

This pattern is used across multiple APIs, including:

• Questionnaire Results — /clients/{clientIds}/results (Profiling API)

Example Request

GET /clients/{clientId}/results?pageSize=50&pageNumber=2
            

Responses always include:

• x-dt-traceid — Client-supplied correlation ID.
• x-dt-requestid — Server-generated request identifier.

Filtering

Collection endpoints frequently support filter parameters to reduce datasets before pagination is applied. These are typically comma-separated values, allowing multiple filters to be combined in a single request.

Common Filter Patterns

• questionnaireId — Restrict results to a specific questionnaire (Profiling).
• fields — Include additional fields such as factors (Profiling).
• includes — Expand related data such as questionnaire metadata.
• unions — In Finances API, specify ownership rules (includes, exact, only).

Example: Filtering Questionnaire Results

GET /clients/{clientId}/results?questionnaireId={qid}&fields=factors
            

Example: Filtering Finances for Specific Ownership

GET /clients/{clientIds}/finances?unions=includes&fields=cashflows,latestHistoricalValuation
            

Filters are always applied before pagination to ensure page numbering aligns with the filtered dataset.

Array Parameters

Many array-style parameters such as fields, includes, unions, and collections of IDs are passed as comma-separated lists. These follow the OpenAPI definition style style=form with explode=false.

Example:

GET /questionnaires?ids=11111111-2222-3333-4444-555555555555,99999999-aaaa-bbbb-cccc-111111111111

Although endpoints accept multiple IDs, the current implementation processes only the first ID in the list. Additional IDs are ignored at this time. Support for true multi-ID processing may be introduced in a future release.

When providing GUIDs, ensure each value in the list is unique.

Best Practices

• Always specify pageSize and pageNumber for predictable iteration.
• Use filters to reduce data before pagination for optimal performance.
• Log x-dt-traceid and x-dt-requestid for diagnostics.
• Expect empty arrays for out-of-range pages.
• Use comma-separated ID lists (e.g., ids, clientIds) to batch-fetch efficiently.