Introduction
Welcome to the Fenergo SaaS Platform's API Documents Section. Here you will find links to REDOC versions of all the APIs we offer on the platform which also contain links to download the Open API Specifications. You can use this section of our document portal to explore the APIs, the methods offered and samples of request and responses for each call.
Navigating our APIs
Within the menu on the left hand side you will see multiple subfolders which correspond to the different domains within the Fenergo SaaS platform. Each of these domains contains Command and Query APIs (where supported) and are grouped by version. All of the API Specifications are labeled as API-XXXX such as API - Entity Data Command. Clicking on each will load the API spec in REDOC so it can be easily read and explored as illustrated below.
Navigating the Documentation Structure
We have grouped the most commonly used APIs together as these tend to address the most common use cases that clients are looking to solve. Then in the next section called Other CLM APIs there are further domain specific links to the API documents.
Getting Started with Fenergo APIs
Before you can start calling any of the Fenergo APIs, you must fist Authenticate and generate an Access Token. We have a page describing how to Authenticate. Every call to a Fenergo Command or Query API must include an API Access Token.
Before you can Authenticate you will need to request a Client Credential from Fenergo for your tenant. The Client Credential Flow is how access tokens are issued
Working with the Fenergo APIs
HTTP Methods
The Fenergo SaaS APIs follow best practice conventions for interacting with APIs. The standard HTTP Verb conventions are followed to perform the standard CRUD operations as below.
| HTTP VERB | CRUD | DESCRIPTION |
|---|---|---|
| POST | Create | Post Requests are used to create new Resources in the Fenergo Platform. They are typically NOT Idempotent and can result in the creation of duplicates if not handled carefully |
| GET | Read | Get Requests are used to Read Resources from the Fenergo Platform. They ARE Idempotent and can be called multiples of times without causing any updates to data. They may or may not have an accompanying BODY, each spec will detail what is required for GET calls. |
| PUT | Update | Put Requests are used to update existing Resources in the Fenergo Platform. They ARE typically Idempotent and multiple calls to a Put method will usually just update the same resource. Only exception on Fenergo is where the version number of a record might increment |
| DELETE | Delete | Delete Requests are used to remove Resources in the Fenergo Platform. They are typically NOT Idempotent and can only result in the removal of data one time. Once removed, the same request will not succeed again. |
API Clients can make that same call over and over and get the same result, so multiple identical requests will result in the same impact on the underlying data. Idempotent operations cause the same result but the response might differ as an underlying resource's state may change between requests.
Delete Operations and Idempotence The first call to a DELETE method should return a HTTP 200 or 202 response and subsequent identical requests would return a 404 (as the resource cannot be found). The net effect is the same event though the response is different.
HTTP Headers
There are standard headers required in the Fenergo API for each call. All requests other than the call to authenticate and create an access token must include:
x-tenant-id specifies the tenant Id
authorization contains the access token used to gain access to the APIs.
This is a Bearer token which means (provided the token is valid and not expired) it will be accepted by fenergo from whichever client presents it.
x-tenant-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
authorization: Bearer xxxxXXXxxxXXXxxxxXXXxxxXXXxxxxXXXxxxXXXxxx
The HTTP Body Response
The majority of the Fenergo APIs where a HTTP Body is returned will contain a JSON object similar to the example below. Depending on the API being called, the response will be structured within a data object at the root of the response. Within that object may be other sub-elements (as per below which contains a businessCategory node).
{
"data": {
"policyTarget": "Client",
"policyRequirementType": "Data",
"categoryOrdering": false,
"dataGroupCategoryOrdering": false,
"businessCategory": [
"Basic Details",
"Individual Details"
],
"id": "b96d698c-0aee-43c4-bfe0-798363b9e021",
"schemaTaskId": "22e9a7ef-485d-420c-92f9-4dc7d88a359f",
"started": "2024-02-29T14:56:23.4086351Z",
"completed": "2024-03-06T11:33:16.7947823Z",
"descoped": null,
"cancelled": null,
"completedBy": "9e70d877-f8fc-47d2-b7c2-9db999a2b1a3",
"isConditional": false,
"isInProgressOrPaused": false,
"autocomplete": false
},
"messages": null
}
The HTTP Error Response
When an error occurs, the data object will typically be null and a messages item included in the response. Where an error has a logical explanation available, it will be included in the response. This is for informational purposes only. The Standard HTTP response of HTTP 400 - Bad Request should be enough for any dependant application to recognize that something incorrect has occurred and then act accordingly.
{
"data": null,
"messages": [
{
"message": "Cannot find Task with ID: b98d698c-0aee-43c4-bfe0-798363b9e021 in journey: 8075825d-3674-454a-ab8a-5a99ede55088",
"type": "Error",
"errorCode": ""
}
]
}
Eventual Consistency
The Fenergo SaaS application is an Event Sourced CQRS platform. The APIs are divided across Command (Update Data) and Query (Read Data) APIs. One endpoint is used to update and another to read data back. Consider the following use case which might need to accommodate for Eventual Consistency.
AS: an API Consumer:
GIVEN: I have just created a Legal Entity and received an Legal Entity Id in the Response.
AND: I want to immediately read back the data I have just saved.
WHEN: I send Entity Query Command to retrieve the Entity using the new Id.
THEN: I want a response containing all the data for the Legal Entity which has just been created.
There is a very rare chance that when this use case executes and the Entity Query API call is made, the system might initially return a HTTP 404 not found. Assuming the Legal Entity Id sent into the Query is correct, this issue could be a result of Eventual Consistency. The sequence of events which causes this anomaly, is the result of a trade off made to favor performance over Strong Consistency.
Just as the API endpoints of Command Query APIs are different, so too is the code execution path. A Command to create a new LE is responded to before the data is committed to the database. Getting this response back to the API consumer quicker is seen as preferable to making the user wait for the full execution of the code through to the Data Store. Using non-conflicting GUIDs for identifiers, means we do not need primary keys from a database, instead the GUID is used as the primary key when the record is sent to the Data Store. Event Sourcing gives us an immutable point in time record of data commits, so there is no risk of the record NOT being saved, we are just not waiting for the Data Store to reply.
If a peak of resource requests were to occur at the same time as a Command API call is made, getting the data to the Data Store could take slightly longer to complete than usual. If that happens, a consumer may request a resource based on its GUID, but the data has not been written to the Data Store yet. The data will eventually get written down but just was not present at the exact time it was requested. Given this outside possibility, clients should factor in eventual consistency when developing their integrations.
- Do you have a use case which reads data immediately after it has been created?
- Catering for HTTP 404 responses is best practice, but clients could factor in a retry for such scenarios.
- Clients could also use an artificially generated delay of perhaps 2-5 seconds before attempting the retry.
The vast majority of clients will never experience any eventual consistency issues, but being aware of of it as a by-product of Event Sourcing is recommended, particularly where the above use case is applicable. There is also an even smaller potential that a webhook event is issued and a similar HTTP 404 is returned. The likelihood is miniscule because of how the application has been architected but under heavy load, an extreme outside possibility does exist.