Basic Operations

This section describes how common operations are performed when working with the PQFORCE API. It introduces fundamental interaction patterns and illustrates them with practical examples. The intent is to explain how objects are typically read, created, modified, and removed, rather than to provide a complete endpoint reference.

Loading Objects

Provided the calling user has the necessary permissions, it is generally possible to load the most recent versions of almost all PQFORCE objects via the API. Corresponding GET endpoints either return a single resource representing one object (for example, GET /API/V2/PM/Project/{projectId}) or a collection of resources representing multiple objects (for example, GET /API/V2/PM/Projects).

Depending on the object type, the API may support one or both access patterns. If both are available, batch calls should generally be preferred, as they are more efficient than issuing multiple single-object requests—unless only one or very few objects need to be retrieved.

When loading a single object, it must usually be identified by its UUID and, in some cases, by its object type. For batch calls, the API often allows pre-filtering of results, for example by lifecycle state, date ranges, or other object-specific criteria. In certain contexts, objects can also be retrieved based on their relations to other objects, such as all projects belonging to a given portfolio or all phases associated with a specific scenario.

A fundamental principle of PQFORCE’s data model is historization. Every change to an object—whether it is created, modified, or deleted—is logged, and all previous states of the object are retained. Each historized state is identified by a versionId. Some API endpoints explicitly allow specifying a versionId, enabling the retrieval of historical (non-current) object states. The historization itself cannot be modified via the API. If an endpoint does not support specifying a versionId, the returned resource always represents the current state of the object.

Creating New Objects

In most parts of the system, new objects can be created by explicitly defining the full object representation in the body of an API request. A common pattern is a PUT call where the object ID is part of the URL and must match the ID provided in the JSON payload, for example:

PUT /API/V2/PM/Project/{projectId}

In other cases, the API provides add endpoints that create new objects with a reduced payload. In these scenarios, the system automatically generates the object ID, and only the essential attributes need to be provided. A typical example is:

POST /API/V2/PM/ProjectPortfolio/{portfolioId}/Projects/Add

Although explicit creation via PUT is supported - and in some cases required - we generally recommend using add endpoints wherever available. These endpoints reduce the risk of ID conflicts, simplify request payloads, and better align with PQFORCE’s internal object lifecycle management.

Updating Existing Objects

Existing objects are updated by sending their modified representation to the corresponding PUT API endpoint. Updates always create a new historized version of the object, preserving all previous states.

When updating objects, clients should ensure that:

• the object ID in the URL matches the ID in the payload,
• only supported attributes are modified,
• and the calling user has sufficient permissions.

Partial updates may be supported in some areas of the API, but unless explicitly documented, clients should assume that a full object representation is required.

Deleting Objects

Objects can be removed using dedicated DELETE endpoints, provided the calling user has the required permissions and the object is not protected by business rules or existing dependencies. As described earlier, deleting an object in PQFORCE typically does not physically remove it from the database. Instead, the deletion is recorded as an additional historization entry that marks the object as deleted.

One particularly useful consequence of this approach is that previously deleted objects can be restored. This is achieved by “creating” a new object using the same object ID. Because the ID is already known to the system, the newly created object is interpreted as another historized version of the previously deleted object rather than as an entirely new entity. In effect, this operation restores the object while preserving its complete change history.