Entities

This article documents how to perform actions via the API relating to entities. Ensure that the appropriate authentication headers are configured when sending these requests.

Service location

The endpoint you need to use is based on which environment is hosting your PACE system. You can find this out by checking your normal login link. Make your selection below and all examples will be tailored to your environment.

Schema

Entity records will be returned in the following format

{
    "EntityGuid": Guid,
    "EntityStatus": string,                  // Active | Archived | Suspended | Long term absent
    "Identifier": string,
    "Name": string,
    "Organisation": string,
    "ParentOrganisation": string,
    "CreatedDate": DateTime,                // yyyy-MM-ddTHH:mm:ss.SSS e.g. "2022-03-24T09:15:42.753"
    "EntityType": string                    // Activity | Environment | Equipment | Process | Solution
}

Retrieve all entities

get api/entities

This action will return all entity instances within your PACE Administration system. This action also supports the Pagination of records functionality.

Example request

Send a GET request to https://online.cardinus.com/api/Entities. This will produce a result object containing a summary of the data and a collection of entity instances from the database.

Example response

{
    "PageNumber": 1,
    "PageSize": 100,
    "FirstPage": "https://localhost:7004/Assessments?pageNumber=1&pageSize=2",
    "LastPage": "https://localhost:7004/Assessments?pageNumber=2322&pageSize=2",
    "TotalPages": 47,
    "TotalRecords": 4644,
    "NextPage": "https://localhost:7004/Assessments?pageNumber=2&pageSize=2",
    "PreviousPage": null,
    "ItemsCount": 100,
    "Items": [
      {
        "PageNumber": 1,
        "PageSize": 100,
        "FirstPage": "https://localhost:7004/Entities?pageNumber=1&pageSize=100",
        "LastPage": "https://localhost:7004/Entities?pageNumber=1&pageSize=100",
        "TotalPages": 1,
        "TotalRecords": 59,
        "NextPage": null,
        "PreviousPage": null,
        "ItemsCount": 59,
        "Items": [        
            {
                "EntityGuid": "0326456a-de7e-43a0-9981-b85c4b020009",
                "EntityStatus": "Active",
                "Identifier": "testSolution1",
                "Name": "testSolution1",
                "Organisation": "Organisation",
                "ParentOrganisation": "N/A",
                "CreatedDate": "2024-07-08T13:32:26.8",
                "EntityType": "Solution"
            },
            {
                "EntityGuid": "5d6713ba-8f89-4eba-91c1-4f333a5da652",
                "EntityStatus": "Active",
                "Identifier": "testActivity1",
                "Name": "testActivity1",
                "Organisation": "Organisation",
                "ParentOrganisation": "N/A",
                "CreatedDate": "2024-07-08T13:33:33.683",
                "EntityType": "Activity"
            },   
            {
                "EntityGuid": "b855beda-bb48-4230-be9a-f0b7bfa8c38d",
                "EntityStatus": "Active",
                "Identifier": "testActivity2",
                "Name": "testActivity2",
                "Organisation": "Organisation",
                "ParentOrganisation": "N/A",
                "CreatedDate": "2024-07-08T14:06:37.267",
                "EntityType": "Activity"
            },
            {
                "EntityGuid": "cf6c5bbb-7353-455e-8072-7d371e27b55e",
                "EntityStatus": "Active",
                "Identifier": "testActivity3",
                "Name": "testActivity3",
                "Organisation": "Organisation",
                "ParentOrganisation": "N/A",
                "CreatedDate": "2024-07-09T09:46:49.337",
                "EntityType": "Activity"
            },   
            etc...
    ],
"Succeeded": true,
"Errors": null,
"Message": null
}

Create a new entity

post api/entities

This action will create a new entity in the PACE Administration system. The data included in the request body is used to create the entity record, and the unique GUID identifier for the record is returned in the response.

Parameter	Description	Location
entity details	The details required to create an entity	Request body

Important

The content-type header must be included and set to application\json.

Example request

Send a POST request to https://online.cardinus.com/api/Entities. Include the below payload and set the content-type header. This will create the entity in the PACE Administration system.

Body JSON structure. All properties except Description are required. The Entity payload must contain valid EntityType of one of the following: Activity | Environment | Equipment | Process | Solution. AdditionalDetails are required for each additional field you want to create for the entity. i.e. "Field Name" : "Property Value" etc...

{
  "EntityType": "string",
  "Identifier": "string",
  "EntityName": "string",
  "Description": "string",
  "AdditionalDetails": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

A bare minmum to create an entity as follows (no description and no additional details):

{
  "EntityType": "string",
  "Identifier": "string",
  "EntityName": "string",
  "AdditionalDetails": {  
  }
}

Example response

Upon successful completion/creation (HTTP 200 OK) the response will return the newly created unique entity identifier in the JSON response body. For example:

{
     "EntityGuid": "4e774a36-4124-4bc7-b788-6b444c04fe66"
}

Filter entities

post api/entities/filter

This action will retrieve all entities depending on the parameters passed in the body. The body is in JSON format and providing no parameters will default to all assessments.

Parameter	Description	Location
entity details	The filtering query options to restrict the result set	Request body

Example request

Send a POST request to https://online.cardinus.com/api/Entities/Filter with search criteria in the body as specified below. The response will contain filtered results. Each property is applied using the AND logical operator.

The JSON example included all the properties that can be used to filter data.

{
  "EntityType": "string",
  "FullName": "string",
  "Identifier": "string",
  "OrganisationName": "string",
  "ParentOrganisation": "string",
  "EntitiesCreatedYesterday": true,
  "OnOrBeforeDate": "2025-01-13T10:19:38.644Z",
  "OnOrAfterDate": "2025-01-13T10:19:38.644Z"
}

For example, to retrieve only entities of the type 'activity' you can use this filter:

{
  "EntityType": "Activity"
}

Example response

{
  "PageNumber": 1,
  "PageSize": 100,
  "FirstPage": "https://localhost:7004/Entities/Filter?pageNumber=1&pageSize=100",
  "LastPage": "https://localhost:7004/Entities/Filter?pageNumber=1&pageSize=100",
  "TotalPages": 1,
  "TotalRecords": 28,
  "NextPage": null,
  "PreviousPage": null,
  "ItemsCount": 28,
  "Items": [
    {
      "EntityGuid": "5d6713ba-8f89-4eba-91c1-4f333a5da652",
      "EntityStatus": "Active",
      "Identifier": "testActivity1",
      "Name": "testActivity1",
      "Organisation": "Organisation",
      "ParentOrganisation": null,
      "CreatedDate": "2024-07-08T13:33:33.683",
      "EntityType": "Activity"
    },
    {
      "EntityGuid": "b855beda-bb48-4230-be9a-f0b7bfa8c38d",
      "EntityStatus": "Active",
      "Identifier": "testActivity2",
      "Name": "testActivity2",
      "Organisation": "Organisation",
      "ParentOrganisation": null,
      "CreatedDate": "2024-07-08T14:06:37.267",
      "EntityType": "Activity"
    },
    ...
    ],
"Succeeded": true,
"Errors": null,
"Message": null
}

Update the entity with the given ID

patch api/entities/{id}

This action will update an existing entity in the PACE Administration system. Include the unique entity identifier as the parameter to the URL, and specify in the JSON body the data fields to update and their values.

Parameter	Description	Location
id	Unique user ID in a GUID format	URL
user details	The properties of an entity that should be updated	Request body

Important

The content-type header must be included and set to application/json.

Example request

Send a PATCH request to https://online.cardinus.com/api/Entities/{id}. Add the properties you wish to update in the JSON payload. Exclude properties you don't want to update.

JSON payload schema:

{
  "Identifier": "string",
  "EntityName": "string",
  "Description": "string",
  "AdditionalDetails": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Example response

Upon successful completion/update (HTTP 200 OK) the response body will be empty.

Retrieve entity with the given ID

get api/entities/{id}

This action will return an entity and relevant data created in the PACE Administration system. The ID required on the request is the unique GUID identifier assigned to the entity.

Parameter	Description	Location
id	Unique entity ID in a GUID format	URL

Example request

Send a GET request to https://online.cardinus.com/api/Entities/{id}. This will produce a result object containing a the single entity record with the given ID.

Example response

{
  "EntityGuid": "2f4ddef5-7ae9-e211-a494-00155d145c00",
  "EntityStatus": "Active",
  "Identifier": "globaladmin",
  "Name": "globaladmin",
  "Organisation": "Organisation",
  "ParentOrganisation": null,
  "CreatedDate": "2013-07-10T17:08:30.57",
  "EntityType": "User"
}

Retrieve entity with the given identifier

get api/entities/{identifier}

This action will return an entity and relevant data created in the PACE Administration system. The identifier required on the request is the unique string identifier assigned to the entity.

Parameter	Description	Location
id	Unique entity identifier in a string format	URL

Example request

Send a GET request to https://online.cardinus.com/api/Entities/{identifier}. This will produce a result object containing the single entity record with the given identifier.

Example response

{
  "EntityGuid": "ba4633ea-0a5c-4b21-ad09-14f025f58770",
  "EntityStatus": "Active",
  "Identifier": "testEquipment1",
  "Name": "testEquipment1",
  "Organisation": "Organisation",
  "ParentOrganisation": null,
  "CreatedDate": "2024-07-09T10:22:40.43",
  "EntityType": "Equipment"
}

Retrieve an overview of all entities

get api/entities/overview

This action will give an overview of relevant data for all entities in the PACE Administration system.

Example request

Send a GET request to https://online.cardinus.com/api/entities/overview with no parameters to get the overview of entities data in your PACE system.

Example response

{  
    "Count": 60
}