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
    "UserId": string,
    "FirstName": string,
    "LastName": string,
    "PreferredName": string,
    "TelephoneNumber": string,
    "EmailAddress": string
}

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",
            "UserId": "tinafreshwater",
            "FirstName": "Tina",
            "LastName": "Freshwater",
            "PreferredName": null,
            "TelephoneNumber": null,
            "EmailAddress": "[email protected]"
        },
        {
            "UserGuid": "56165cd0-944c-4586-a77f-d8d4a630f5de",
            "IsLocked": true,
            "UserStatus": "Active",
            "UserId": "jwhalberg",
            "FirstName": "Janet",
            "LastName": "Whalberg",
            "Preferred Name": "Jan",
            "Telephone Number": "01234567890",
            "EmailAddress": "[email protected]"
        },
        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",
    "UserId": "Nicholson",
    "FirstName": "Bevan",
    "LastName": "Nicholson",
    "PreferredName": null,
    "TelephoneNumber": null,
    "EmailAddress": "[email protected]"
}

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 and TelephoneNumber are required.

{
    "UserId": string,
    "FirstName": string,
    "LastName": string,
    "PreferredName": string,
    "TelephoneNumber": string,
    "EmailAddress": string
}

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.

JSON payload schema:

{  
    "UserId": string,
    "FirstName": string,
    "LastName": string,
    "PreferredName": string,
    "TelephoneNumber": string,
    "EmailAddress": string
}

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
}

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",
            "UserId": "jwhalberg",
            "FirstName": "Janet",
            "LastName": "Whalberg",
            "PreferredName": "Jan",
            "TelephoneNumber": "01234567890",
            "EmailAddress": "[email protected]"
        },
        etc...
    ],
    "Succeeded": true,
    "Errors": null,
    "Message": null
}

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
}