Assessments

This article documents how to perform actions via the API relating to assessments. 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

Assessment records will be returned in the following format

{
    "FullName": string,
    "UserId": string,
    "UserGuid": Guid,
    "IsLocked": boolean,
    "UserStatus":  string,                  // Active | Archived | Suspended | Long term absent
    "AssessmentName": string,
    "AssessmentStatus": string,             // Active | Archived
    "ParentOrganisation": string,
    "Organisation": string,
    "ProgrammeName": string,
    "CompletedDate": nullable DateTime,     // yyyy-MM-ddTHH:mm:ss.SSS e.g. "2022-03-24T09:15:42.753"
    "CreatedDate": DateTime,                // yyyy-MM-ddTHH:mm:ss.SSS e.g. "2022-03-24T09:15:42.753"
    "Progress": string,
    "Risk": nullable decimal,
    "ProgressionStatus": string
}

Retrieve all assessments

get api/assessments

This action will return all assessment 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/Assessments. This will produce a result object containing a summary of the data and a collection of user instances from the database.

Example response

{
    "PageNumber": 1,
    "PageSize": 100,
    "FirstPage": "https://online.cardinus.com/api/Assessments?pageNumber=1&pageSize=2",
    "LastPage": "https://online.cardinus.com/api/Assessments?pageNumber=2322&pageSize=2",
    "TotalPages": 47,
    "TotalRecords": 4644,
    "NextPage": "https://online.cardinus.com/api/Assessments?pageNumber=2&pageSize=2",
    "PreviousPage": null,
    "ItemsCount": 100,
    "Items": [
        {
            "FullName": "Brad Storch",
            "UserId": "bstorch",
            "UserGuid": "65467435-7ae9-e211-a494-00155d145c00",
            "IsLocked": false,
            "UserStatus": "Active",
            "AssessmentName": "Healthy Working Plus - Profile",
            "AssessmentStatus": "Archived",
            "ParentOrganisation": "N/A",
            "Organisation": "Example Organisation",
            "ProgrammeName": "Healthy Working Plus",
            "CompletedDate": "2022-03-24T09:15:42.753",
            "CreatedDate": "2022-03-24T09:15:42.753",
            "Progress": "Finished",
            "Risk": 0,
            "ProgressionStatus": null
        },
        {
            "FullName": "Brad Storch",
            "UserId": "bstorch",
            "UserGuid": "65467435-7ae9-e211-a494-00155d145c00",
            "IsLocked": false,
            "UserStatus": "Active",
            "AssessmentName": "Healthy Working Plus",
            "AssessmentStatus": "Archived",
            "ParentOrganisation": "N/A",
            "Organisation": "Example Organisation",
            "ProgrammeName": "Healthy Working Plus",
            "CompletedDate": "2022-03-24T09:21:19.78",
            "CreatedDate": "2022-03-24T09:21:19.78",
            "Progress": "Finished",
            "Risk": 10,
            "ProgressionStatus": null
        },
        etc...
    ],
    "Succeeded": true,
    "Errors": null,
    "Message": null
}

Retrieve assessments by user

get api/assessments/{userid}

This action will return assessments created for a specific user via the parameter passed in on the request. The parameter is the user's unique identifier in a GUID format.

Parameter	Description	Location
`userid`	User ID in a GUID format	URL

Example request

Send a GET request to https://online.cardinus.com/api/Assessments/{userid}. The resulting data will be a collection of assessments restricted to the given user.

Example response

{
    "Count": 6,
    "Items": [
        {
            "FullName": "Brad Storch",
            "UserId": "bstorch",
            "UserGuid": "65467435-7ae9-e211-a494-00155d145c00",
            "IsLocked": false,
            "UserStatus": "Active",
            "AssessmentName": "Healthy Working Plus - Profile",
            "AssessmentStatus": "Archived",
            "ParentOrganisation": "N/A",
            "Organisation": "Example Organisation",
            "ProgrammeName": "Healthy Working Plus",
            "CompletedDate": "2022-03-24T09:15:42.753",
            "CreatedDate": "2022-03-24T09:15:42.753",
            "Progress": "Finished",
            "Risk": 0,
            "ProgressionStatus": null
        },
        {
            "FullName": "Brad Storch",
            "UserId": "bstorch",
            "UserGuid": "65467435-7ae9-e211-a494-00155d145c00",
            "IsLocked": false,
            "UserStatus": "Active",
            "AssessmentName": "Healthy Working Plus",
            "AssessmentStatus": "Archived",
            "ParentOrganisation": "N/A",
            "Organisation": "Example Organisation",
            "ProgrammeName": "Healthy Working Plus",
            "CompletedDate": "2022-03-24T09:21:19.78",
            "CreatedDate": "2022-03-24T09:21:19.78",
            "Progress": "Finished",
            "Risk": 10,
            "ProgressionStatus": null
        },
        etc...
    ]
}

Filter assessments

post api/assessments/filter

This action will retrieve all assessments 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
assessment details	The filtering query options to restrict the result set	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/Assessments/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 schema including all the properties that can be used to filter data:

{
    "UserId": string,    
    "Islocked": boolean,
    "UserStatus": string,
    "AssessmentName": string,
    "AssessmentStatus": string,
    "AssessmentsCompletedYesterday": boolean,
    "OnOrBeforeDate": DateTime,  // yyyy-MM-dd e.g. "2024-01-01"
    "OnOrAfterDate": DateTime,  // yyyy-MM-dd e.g. "2024-01-01"
    "ParentOrganisation": string,
    "Organisation": string,
    "ProgrammeName": string
}

For example, to retrieve only assessments associated with archived users you can use this filter:

{
  "UserStatus": "archived"
}

Example response

{
    "PageNumber": 1,
    "PageSize": 100,
    "FirstPage": "https://online.cardinus.com/api/Assessments/Filter?pageNumber=1&pageSize=100",
    "LastPage": "https://online.cardinus.com/api/Assessments/Filter?pageNumber=6&pageSize=100",
    "TotalPages": 6,
    "TotalRecords": 516,
    "NextPage": "https://online.cardinus.com/api/Assessments/Filter?pageNumber=2&pageSize=100",
    "PreviousPage": null,
    "ItemsCount": 100,
    "Items": [
        {
            "FullName": "Brad Storch",
            "UserId": "bstorch",
            "UserGuid": "73464643-a85d-ec11-811a-005056b147ee",
            "IsLocked": false,
            "UserStatus": "Archived",
            "AssessmentName": "Healthy Working Plus - Profile",
            "AssessmentStatus": "Active",
            "ParentOrganisation": "Scotland",
            "Organisation": "Scotland Services",
            "ProgrammeName": "Healthy Working Plus",
            "CompletedDate": "2022-09-30T08:39:50.067",
            "CreatedDate": "2022-09-30T08:39:50.067",
            "Progress": "Finished",
            "Risk": 0,
            "ProgressionStatus": "Healthy Working Plus - Profile"
        },
        {
            "FullName": "Betty Symington",
            "UserId": "bsymington",
            "UserGuid": "85475745-a85d-ec11-811a-005056b147ee",
            "IsLocked": false,
            "UserStatus": "Archived",
            "AssessmentName": "Healthy Working Plus",
            "AssessmentStatus": "Active",
            "ParentOrganisation": "Northern Ireland",
            "Organisation": "Management (NI)",
            "ProgrammeName": "Healthy Working Plus",
            "CompletedDate": "2022-09-30T09:26:41.457",
            "CreatedDate": "2022-09-30T09:26:41.457",
            "Progress": "Finished",
            "Risk": 0,
            "ProgressionStatus": "Completed / No Risk"
        },
        ...
    ],
    "Succeeded": true,
    "Errors": null,
    "Message": null
}

Retrieve an overview of all assessments

get api/assessments/overview

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

Example request

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

Example response

{  
    "Count": 2920
}

Creates an assessment

post api/assessments

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

Parameter	Description	Location
assessment details	The details required to create an assessment	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/assessments

Body JSON example, required fields are identifier (GUID of the entity the assessment is for) and assessment ID (GUID of the assessment), these are both GUID items. As well as IsComplete which is a boolean value, this will mark the assessment as either completed or incomplete. AssessmentRisk is a decimal value and is optional.

When supplying answers the 'Assessment Questions' array is required, and Question is also required (GUID of the question). The Answer or Question Option is then required, Answer is a free text value where as Question Option is the GUID of the selected option for the question. It will always be either free text answer or GUID of the question option. Risk is a decimal value and is optional.

{
  "Identifier": "6874C525-30AC-4795-BFE1-B855D872F210",
  "Assessment ID": "F8D6EC73-E4E6-4E23-9EF3-16C9AE0133AB",
  "AssessmentRisk": 0,
  "IsComplete": true,
  "Assessment Questions": [
    {
      "Question": "4923374B-0961-4245-912F-2330300AC7D4",
      "Answer": "7"
    }
  ]
}

{
  "Identifier": "6874C525-30AC-4795-BFE1-B855D872F210",
  "Assessment ID": "F8D6EC73-E4E6-4E23-9EF3-16C9AE0133AB",
  "AssessmentRisk": 3,
  "IsComplete": false,
  "Assessment Questions": [
    {
      "Question": "264B514F-2C39-4F2D-8A01-C9D17126CEC2",
      "Question Option": "A5F69F67-0357-4830-91CD-6EE718CF11A7",
      "Risk": 2
    }
  ]
}

Successful response

58B9D82F-DC10-4166-AF46-9D6C34AC397E

A new GUID of the assessment created will be returned upon sucessful creation.

Update an existing assessment

patch api/assessments/{id}

This action will update an existing assessment in the PACE Administration system. Include the unique assessment 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 assessment ID in a GUID format	URL
assessment details	The properties of an assessment 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/assessments

Body JSON example

Optional fields to update are AssessmentRisk this is a decimal value and/or IsComplete this is a boolean value. When supplying answers the 'Assessment Questions' array is required, and Question is also required (GUID of the question). The Answer or Question Option is then required, Answer is a free text value where as Question Option is the GUID of the selected option for the question. It will always be either free text answer or GUID of the question option. Risk is a decimal value and is optional.

{
  "IsComplete": false,
  "AssessmentRisk": 1,
  "Assessment Questions": [
    {
      "Question": "4923374B-0961-4245-912F-2330300AC7D4",
      "Answer": "7",
      "Risk": 3
    }
  ]
}

{
  "AssessmentRisk": 2.4,
  "Assessment Questions": [
    {
      "Question": "264B514F-2C39-4F2D-8A01-C9D17126CEC2",
      "Question Option": "A5F69F67-0357-4830-91CD-6EE718CF11A7"
    }
  ]
}