User records

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

User records will be returned in the following format

{
    "UserGuid": Guid,
    "IsLocked": boolean,
    "UserStatus": string,        // Active | Archived | Suspended | Long term absent
    "Organisation": string,
    "ParentOrganisation": string,
    "UserId": string,
    "FirstName": string,
    "LastName": string,
    "PreferredName": string,
    "TelephoneNumber": string,
    "EmailAddress": string,
    "AdditionalDetails" :       // Object containing the custom fields from PACE
    {
        "Additional field 1 name" : "Additional field 1 value", 
        "Additional field 2 name" : "Additional field 2 value"
    }
}

Retrieve all users

get api/users

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

Example response

The below is a snippet of the type of data to expect in the response.

{    
    "PageNumber": 1,
    "PageSize": 100,
    "FirstPage": "https://online.cardinus.com/api/Users?pageNumber=1&pageSize=100",
    "LastPage": "https://online.cardinus.com/api/Users?pageNumber=54&pageSize=100",
    "TotalPages": 54,
    "TotalRecords": 5368,
    "NextPage": "https://online.cardinus.com/api/Users?pageNumber=2&pageSize=100",
    "PreviousPage": null,
    "ItemsCount": 100,
    "Items": [
        {
            "UserGuid": "ecfddef5-7ae9-e211-a494-00155d145c00",
            "IsLocked": false,
            "UserStatus": "Active",
            "Organisation": "Organisation level 1",
            "ParentOrganisation": "Organisation",
            "UserId": "tinafreshwater",
            "FirstName": "Tina",
            "LastName": "Freshwater",
            "PreferredName": null,
            "TelephoneNumber": null,
            "EmailAddress": "[email protected]",
            "AdditionalDetails": {
                "Height of the employee": "",
                "Previous known medical issues": "",
                "US Version": "False",
                "Pregnant": "False"
            }
        },
        {
            "UserGuid": "56165cd0-944c-4586-a77f-d8d4a630f5de",
            "IsLocked": true,
            "UserStatus": "Active",
            "Organisation": "Organisation level 1",
            "ParentOrganisation": "Organisation",
            "UserId": "jwhalberg",
            "FirstName": "Janet",
            "LastName": "Whalberg",
            "Preferred Name": "Jan",
            "Telephone Number": "01234567890",
            "EmailAddress": "[email protected]",
            "AdditionalDetails": {
                "Height of the employee": "",
                "Previous known medical issues": "",
                "US Version": "False",
                "Pregnant": "False"
            }
        },
        etc...
    ],
    "Succeeded": true,
    "Errors": null,
    "Message": null
}

Retrieve user with the given ID

get api/users/{id}

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

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

Example request

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

Example response

{
    "UserGuid": "370ede06-d5ac-4c41-a7e7-fbf20740a201",
    "IsLocked": false,
    "UserStatus": "Active",
    "Organisation": "Organisation",
    "ParentOrganisation": null,
    "UserId": "Nicholson",
    "FirstName": "Bevan",
    "LastName": "Nicholson",
    "PreferredName": null,
    "TelephoneNumber": null,
    "EmailAddress": "[email protected]",
    "AdditionalDetails": {
        "Height of the employee": "",
        "Previous known medical issues": "",
        "US Version": "False",
        "Pregnant": "False"
    }
}

Create a new user

post api/users

This action will create a new user in the PACE Administration system. The data included in the request body is used to create the user record, and the unique GUID identifier for the record is returned in the response. When a user is created it will be placed at the top level of the organisation structure in PACE.

Parameter	Description	Location
user details	The details required to create a user	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/Users. Include the below payload and set the content-type header. This will create the user in the PACE Administration system.

Body JSON structure. All properties except PreferredName, TelephoneNumber, and AdditionalDetails are required.

{
    "UserId": string,
    "FirstName": string,
    "LastName": string,
    "PreferredName": string,
    "TelephoneNumber": string,
    "EmailAddress": string,
    "UserStatus": string,            // Active | Archived | Suspended | Long term absent,
    "AdditionalDetails" :
    {
        "Additional field name" : "Desired value"
    }
}

Example response

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

{
    "UserGuid" : "6d41c56d-cee2-4d77-8091-f4d7ccf2ec8e" 
}

Update the user with the given ID

patch api/users/{id}

This action will update an existing user in the PACE Administration system. Include the unique user 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 a user 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/Users/{id}. Add the properties you wish to update in the JSON payload. Exclude properties you don't want to update.

The property EntityStatus if included has to be one of the following terms: Active, Archived, Suspended, LongTermAbsent

JSON payload schema:

{  
    "UserId": string,
    "FirstName": string,
    "LastName": string,
    "PreferredName": string,
    "TelephoneNumber": string,
    "EmailAddress": string,
    "UserStatus": string,                    // Active | Archived | Suspended | Long term absent         
    "AdditionalDetails" : {
        "Additional field name" : "Desired value"
    }
}

Example response

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

Filter users using search parameters

post api/users/filter

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

Parameter	Description	Location
user 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/Users/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 with all the properties that can be used to filter data.

{  
    "UserId": string,
    "IsLocked": boolean,
    "UserStatus": string,
    "FirstName": string,
    "LastName": string,
    "FullName": string,
    "PreferredName": string,
    "EmailAddress": string,
    "Organisation": string,
    "ParentOrganisation": string
}

This example will return only users who have locked accounts.

{
    "IsLocked": true 
}

Example response

{    
    "PageNumber": 1,
    "PageSize": 100,
    "FirstPage": "https://online.cardinus.com/api/Users?pageNumber=1&pageSize=100",
    "LastPage": "https://online.cardinus.com/api/Users?pageNumber=54&pageSize=100",
    "TotalPages": 54,
    "TotalRecords": 5368,
    "NextPage": "https://online.cardinus.com/api/Users?pageNumber=2&pageSize=100",
    "PreviousPage": null,
    "ItemsCount": 100,
    "Items": [
        {
            "UserGuid": "56165cd0-944c-4586-a77f-d8d4a630f5de",
            "IsLocked": true,
            "UserStatus": "Active",
            "Organisation": "Organisation",
            "ParentOrganisation": null,
            "UserId": "jwhalberg",
            "FirstName": "Janet",
            "LastName": "Whalberg",
            "PreferredName": "Jan",
            "TelephoneNumber": "01234567890",
            "EmailAddress": "[email protected]",
            "AdditionalDetails": {
                "Height of the employee": "",
                "Previous known medical issues": "",
                "US Version": "False",
                "Pregnant": "False"
            }
        },
        etc...
    ],
    "Succeeded": true,
    "Errors": null,
    "Message": null
}

To filter users who are at the top level of the organisation only, put N/A as the value for the ParentOrganisation property.

{
    "ParentOrganisation": "N/A"
}

Retrieve an overview of all users

get api/users/overview

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

Example request

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

Example response

{  
    "Count": 5369,
    "Active": 5369,
    "Locked": 2
}