Skip to main content

Create a New Legal Entity

One of the main functional features of the Fenergo SaaS platform is to create Legal Entity's. A Legal entity is a data record of a client or an associate of a client which will be managed on the Fenergo SaaS Platform. Journeys are used to managed the Client Lifecycle processes such as Onboarding or Maintenance, but before any of that can be done, the first step is to create a Legal Entity. The APIs opposite are used in this document.

APIs Referenced
Entity Data Command (v2)
Entity Data Query
  As an API consumer:

      GIVEN I have Legal Entity Data available from a downstream system

      AND I want to use that data to create a new Legal Entity on the Fenergo SaaS Platform

      WHEN I have all the creation data ready to save

  THEN I want to create an instance a new Legal Entity on Fenergo by calling an API

Create Legal Entity Request & Response​

The properties passed into the API call to create a Legal Entity are aligned to the Policy which has been created for the Legal Entity Type. To create the Legal Entity, send a POST to: {{baseURL}}/entitydatacommand/api/v2/entity

{
    "data": {
        "type": "Company",
        "policyJurisdictions": [
           "Global"
        ],
        "properties": {
            "legalEntityName": {
                "type": "Single",
                "value": "Acme Finance Group"
            },
            "companyType": {
                "type": "Single",
                "value": "Bank"
            },
            "category": {
                "type": "Single",
                "value": "Corporation"
            },
            "countryOfIncorporation": {
                "type": "Single",
                "value": "Ireland"
            },
            "dateOfIncorporation": {
                "type": "Single",
                "value": "2021-12-31"
            }
        },
        "accessLayers": {
            "businessRelated": [
                "Enterprise"
            ],
            "geographic": [
                "Global"
            ]
        }
    }
}

Provided the request is valid, the return type will be an identifier for the Entity which has just been created. This can then be used to retrieve back the record which has been created. Using this API call writes the created entity into what we call the Verified Store. A Verified Record is just a status on the underlying JSON document set by the system.

  • The "type" is where the Legal Entity Type is Specified.
  • The "properties" are the available properties such as "legalEntityName" and "countryOfIncorporation" etc...
{
    "data": {
        "id": "2ed9f965-342a-4dc8-afb8-58b8de41cd5f"
    },
    "messages": null
}

The "id": "2ed9f965-342a-4dc8-afb8-58b8de41cd5f" in the response is the Fenergo Legal Entity Id for the entity just created.

Fields and Jurisdictions

When the provided jurisdictions does not contain a field that is included in the properties object, the entity will still be created, but that field will not saved and the response will look similar to the below:

    {
        "data": {
            "id": "a0999895-5bb7-4459-aebc-a3f99ed1066a"
        },
        "messages": [
        "message": "Some sent properties were out of scope and not updated: field",
        "type": "Warning"
        ]
    }

Read Back Legal Entity Request & Response​

Once created, you can then retrieve back the record using the GUID returned in the previous response. Whatever data is available will be returned, send a GET request to the opposite URL replacing the "id" with the Entity Id:.

    Format:
    {{baseURL}}/entitydataquery/api/entity/{id}

    Example:
    {{baseURL}}/entitydataquery/api/entity/
    2ed9f965-342a-4dc8-afb8-58b8de41cd5f
JSON Structure

The structure of the JSON returned in this request contains the same data which was sent to "create" method. Standard properties which can be seen as "null". The more data you pass in the create call the more data is saved. The initial record is saved to the verified store and subsequent updates need to to be first applied to a draft record and then committed to the verified store.

{
    "data": {
        "id": "2ed9f965-342a-4dc8-afb8-58b8de41cd5f",
        "type": "Company",
        "properties": {
            "legalEntityName": {
                "value": "Acme Finance Group",
                "type": "Single",
                "discriminator": "Single"
            },
            "country": {
                "value": "Ireland",
                "type": "Single",
                "discriminator": "Single"
            },
            "dateOfIncorporation": {
                "value": "2021-12-31",
                "type": "Single",
                "discriminator": "Single"
            },
            "category": {
                "value": "Corporation",
                "type": "Single",
                "discriminator": "Single"
            },
            "companyType": {
                "value": "Bank",
                "type": "Single",
                "discriminator": "Single"
            }
        },
        "risk": {
            "riskCategory": null,
            "riskLevel": null
        },
        "role": {
            "name": null
        },
        "status": 0,
        "userId": null,
        "created": "2022-07-16T10:44:18.482+00:00",
        "alternateId": null,
        "journeys": [
        ],
        "accessLayers": {
            "geographic": [
                "Global"
            ],
            "businessRelated": [
                "Enterprise"
            ]
        },
        "inScopeJurisdictions": [
            {
                "jurisdiction": "Global",
                "versionId": "bfe6acb0-3087-4da7-a6cb-33f05d52193b"
            }
        ],
        "offboardedJurisdictions": [],
        "version": 0
    },
    "messages": null
}