Core - End User
The base url for the APIs in this page is at:
/api/admin
A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.
Get end user (Id)
Returns the end user fields corresponding to the id provided:
- GET /v1/end-users/{id}
Return the User fields if [id] is valid and is an END_USER OR an error if not
- Parameters
id (integer) – User id
- Status Codes
200 OK – Success
- DELETE /v1/end-users/{id}
Delete the suggested User
- Parameters
id (integer) – User id
- Status Codes
200 OK – Success
If the request is successful, it will return a positive Json response and the data of the user:
{
Name: "John", // String
Surname: "Doe", // String
FullName: "John Doe", // String
Roles: ["EndUser","..."], // String Array
UserName: "username", // String
Email: "user@email.com", // String
MobilePhoneNumber: "12313321", // String
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
ID: 1234, // Int
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsBlocked: false, // Boolean
IsDisabled: false, // Boolean
IsDisabledByAdmin: false, // Boolean
IsDisabledBySystem: false, // Boolean
OverriddenSystemDisableStatus: false, // Boolean
SystemDisabledReason: "PAYMENT", // String (nullable)
ForcedEnabledBy: "Administrator", // String (nullable)
ForcedEnabledById: "db601954-7d61-472d-b799-e38289d50297", // Guid (nullable)
IsConfirmed: true, // Boolean
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
Language: "en-GB", // String
Communities: ["List","of","community","Guids"] // String Array
ForcedPasswordChangeRequestDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastPasswordChangeTimestamp, "2001-01-01T01:01:01Z", // DateTime (nullable)
Agreements: {
TermsAndConditionsAgreement: true, // Boolean
TermsAndConditionsDateAgreement: "2021-01-01T00:00:00Z", // Datetime (nullable)
IsTandCEditable: false, // Boolean
PrivacyDataAgreement: true, // Boolean
PrivacyDataAgreementDate: "2021-01-01T00:00:00Z" // Datetime (nullable)
PrivacyDataAgreementAttachment: null // Guid (nullable)
}
}
and if not, it will return a plain negative Json response.
Get end user (Guid)
Returns the end user fields corresponding to the Guid provided:
- GET /v1/end-users/{guid}
Return the User fields if [guid] is valid and is an END_USER OR an error if not
- Parameters
guid (string) – User Guid
- Status Codes
200 OK – Success
If the request is successful, it will return a positive Json response and the data of the user (Guid is a Guid type):
{
Name: "John", // String
Surname: "Doe", // String
FullName: "John Doe", // String
Roles: ["EndUser","..."], // String Array
UserName: "username", // String
Email: "user@email.com", // String
MobilePhoneNumber: "12313321", // String
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
ID: 1234, // Int
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
IsBlocked: false, // Guid
IsDisabled: false, // Boolean
IsDisabledByAdmin: false, // Boolean
IsDisabledBySystem: false, // Boolean
OverriddenSystemDisableStatus: false, // Boolean
SystemDisabledReason: "PAYMENT", // String (nullable)
ForcedEnabledBy: "Administrator", // String (nullable)
ForcedEnabledById: "db601954-7d61-472d-b799-e38289d50297", // Guid (nullable)
IsConfirmed: true, // Boolean
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
Language: "en-GB", // String
Communities: ["List","of","community","Guids"] // String Array
ForcedPasswordChangeRequestDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
LastPasswordChangeTimestamp, "2001-01-01T01:01:01Z", // DateTime (nullable)
Agreements: {
TermsAndConditionsAgreement: true, // Boolean
TermsAndConditionsDateAgreement: "2021-01-01T00:00:00Z", // Datetime (nullable)
IsTandCEditable: false, // Boolean
PrivacyDataAgreement: true, // Boolean
PrivacyDataAgreementDate: "2021-01-01T00:00:00Z" // Datetime (nullable)
PrivacyDataAgreementAttachment: null // Guid (nullable)
}
}
and if not, it will return a plain negative Json response.
Get filtered user list
Fetches an User List which correspond to the filters (it’s a Paged List APIs, as explained in the introduction):
These filters are in the URL query params:
community (is an integer; it’s the the ID of the community)
status (is an integer; 0 = no filter, 1 = blocked users, 2 = operative users, 3 = confirmed users)
from (is a date; from and to are filters on the creation date of the user)
to (is a date; from and to are filters on the creation date of the user)
the response will be a list of the users filtered according to the provided filters (if no filter is set, the API will return the full list of users):
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
UserName: "UserName", // String
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
AdditionalData:
[
{
ID: 1234, // Int
CreatedDate:"2001-01-01T01:01:01Z", // DateTime
LastUpdated: "2001-01-01T01:01:01Z", // DateTime
FieldName: "Custom Field name", // String
Type: 0, // Int (enum AdditionalValueType)
Value: "abc" // String
},
...
],
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
LCID: 1044, // Int
Language: "en-GB", // String
IsConfirmed: true, // Boolean
IsBlocked: false, // Boolean
IsDisabled: false, // Boolean
IsDisabledByAdmin: false, // Boolean
IsDisabledBySystem: false, // Boolean
OverriddenSystemDisableStatus: false, // Boolean
SystemDisabledReason: "PAYMENT", // String (nullable)
ForcedEnabledBy: "Administrator", // String (nullable)
ForcedEnabledById: "db601954-7d61-472d-b799-e38289d50297", // Guid (nullable)
ManualApprovalDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
Email: "user@email.com", // String
FullName: "John Doe", // String
MobilePhoneNumber: "12321321", // String
Communities: ["List","of","community","Guid"], // Guid Array
AdministeredCommunities: [], // Guid Array
Roles: ["EndUser","..."] // String Array
},
...
]
Search end user
Fetches a collection of the active end users records filtered by the name provided. A maximum of 20 elements can be returned:
- GET /v1/end-users/search
Fetches a collection of the active end users records filtered by [name] ** maximum 20 elements can be returned, otherwise an error will be returned**
- Query Parameters
name (string) – A string to look for in any field, even partial
- Status Codes
200 OK – Success
The API expects to receive the search string name in the query parameters.
The request will return the list of all the end user records found:
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
UserName: "UserName", // String
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
AdditionalData:
[
{
ID: 1234, // Int
CreatedDate:"2001-01-01T01:01:01Z", // DateTime
LastUpdated: "2001-01-01T01:01:01Z", // DateTime
FieldName: "Custom Field name", // String
Type: 0, // Int (enum AdditionalValueType)
Value: "abc" // String
},
...
],
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
LCID: 1044, // Int
Language: "en-GB", // String
IsConfirmed: true, // Boolean
IsBlocked: false, // Boolean
IsDisabled: false, // Boolean
IsDisabledByAdmin: false, // Boolean
IsDisabledBySystem: false, // Boolean
OverriddenSystemDisableStatus: false, // Boolean
SystemDisabledReason: "PAYMENT", // String (nullable)
ForcedEnabledBy: "Administrator", // String (nullable)
ForcedEnabledById: "db601954-7d61-472d-b799-e38289d50297", // Guid (nullable)
ManualApprovalDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
Email: "user@email.com", // String
Name: "John", // String
Surname: "Doe", // String
FullName: "John Doe", // String
MobilePhoneNumber: "12321321", // String
Communities: ["List","of","community","Guid"], // Guid Array
AdministeredCommunities: [], // Guid Array
Roles: ["EndUser","..."] // String Array
},
...
]
err_NoUserFoundNo active end user found
err_TooManyUsersFoundMore than 20 records were found
Add new or edit existing user
Persists edits about a new or existing user:
- POST /v1/end-users
Save or update (if a valid UserID is passed) a User record If an invalid User ID is passed, the function will return a Error If the User is new and the name field was not filled in, the function will return also a Error Similarly, there must also be at least one connected community and a valid Role
- Status Codes
200 OK – Success
The body of the request is:
{
ID: 1234, // Int (nullable)
UserName: "user@email.com", // String
Language: "en-GB", // String
Password: "zxcwqqy12", // String
Email: "user@email.com", // String
Name: "John", // String
Surname: "Doe", // String
IsBlocked: false, // Boolean (nullable)
IsDisabledByAdministrator: false, // Boolean (nullable)
IsConfirmed: false, // Boolean (nullable)
MobilePhoneNumber: "123123123", // String
CommunityId: 1234, // Int (nullable)
Roles: ["List","of","roles","names"], // String Array
PrivacyAgreement: true, // Boolean
TermsAndConditions: true, // Boolean
AdditionalUserData:
[
{
FieldName: "additional user data field name", // String
Value: "..." // String
},
...
]
}
If ID is valorized and corresponds to an existing user, the request will update the specified fields, otherwise it will add a new user.
The field UserName cannot be changed for existing users, and it’s a required field when adding new users.
The field IsConfirmed is ignored, and set by default to true, while creating a new user; while editing a new user, if no value or
a value of false is passed, it will be ignored.
If no value is passed in the fields IsBlocked or IsDisabled, it will be handled as a value of false.
When adding a new user, the AdditionalUserData field must be valorized with each required additional user data fields set for the system, if any.
The FieldName and Type must be the same of the required additional user data field, and the Value must be compliant with the specific field format.
See Additional User Data Fields for further informations.
The agreements fields (PrivacyAgreement and TermsAndConditions) are interpreted only while creating a new user.
Returns a positive Json response with no data if successful, or a negative one if one of the provided field has the property FieldName empty or missing.
Possible error messages are:
err_MissingRequiredFieldsSome of the AdditionaUserData values are missing
err_NoPrivacyAgreementNo PrivacyAgreement or TermsAndConditions data has ben provided, or they have been set to false
err_InvalidElementNo username, email, mobile phone number, role or community has been specified, or no user has been found for the provided ID during an update
err_DuplicateElementThe request is trying to add a record with the same UserName or same Email as an existing one.
Upload Agreement Attachment
Uploads a document to attach to the specified user’s agreement
- POST /v1/end-users/{guid}/agreements/upload
Uploads an attachment on the user’s agreements
- Parameters
guid (string) – The user guid
- Status Codes
200 OK – Success
The API accepts a request body in the following format:
{
Attachment: "...", // Base64String (nullable)
AttachmentName: "Name-of-the-attachment", // String (nullable)
AttachmentMimeType: "application/pdf", // String (nullable)
}
and will respond with a plain error response if some errors arose while storing the attachment, or with one of the following error codes:
err_NoAgreementsThe user related to the provided guid has no agreement data
err_AttachmentAlreadyPresentThe user’s agreement already has an attachment related to the privacy data
err_InvalidElementNo Attachment or AttachmentMimeType data has been provided
Delete User
Marks the user corresponding to the ID provided as deleted:
Returns a plain Json positive answer if successful, or the following error messages if not:
err_ElementDoesNotExistNo user corresponding to the provided ID
err_ElementAlreadyDeletedThe specified user is already marked as deleted
Get active session count
Returns the count of the currently active session for the specified user
- GET /v1/end-users/{guid}/active-sessions
Gets the number of active session for the specified user
- Parameters
guid (string) – User guid
- Status Codes
200 OK – Success
If the request is successfull, the API will return a response like this:
{
ActiveSessions: 5, // Int
MaxSessions: 6 // Int
}
where ActiveSessions is the count of the currently active session for the specified users, while
MaxSessions is the max number of allowed active session, as specified in the configuration variable AUTH_SESSION_LIMIT
configuration variable, or an error if the request is not successful.
Force logoff for a specified user
Logs off all the currently active session for the specified user
- POST /v1/end-users/force-logoff
Force the logoff of every active session for the specified user
- Status Codes
200 OK – Success
The API expects a body like this:
{
User: '1e4a8a87-9909-4cbb-8452-a8d0872d92a4'
}
where the User field is the guid of the user that must be forcefully logged off.
The API will return a plain positive error if the request is successfull, a generic error if no User
field is provided, or one of the following errors:
err_NoUserFoundNo user has ben found for the specified guid
err_NotLoggedInThe specified user has no currently active session
Force user to change password during the next login
Requires a password update to be forced on the user at the next login
- POST /v1/end-users/force-password-reset
Force the password reset for the specified end user
- Status Codes
200 OK – Success
The API expects a body like this:
{
User: '1e4a8a87-9909-4cbb-8452-a8d0872d92a4'
}
Where the User field is the GUID of the user who must be forced to change the password.
The API will return a plain positive error if the request is successful, a generic error if no User
field is provided, or one of the following errors:
err_NoUserFoundNo user has ben found for the specified guid
err_PasswordChangeAlreadyRequestedThere are previous request to force password change.
Get User additional data
Returns the custom fields of the User corresponding to the provided id:
- GET /v1/end-users/{id}/additional-data
Return the custom fields of the [id] User presents in the [AdditionalUserData] table
- Parameters
id (integer) – User id
- Status Codes
200 OK – Success
- POST /v1/end-users/{id}/additional-data
Updates the data contained in the body of the message relating to the user [id]
- Parameters
id (integer) – User ID
- Status Codes
200 OK – Success
If the request is successful, it will return a positive Json response all the custom fields in the AdditionalUserData table
[
{
ID: 1234, // Int
CreatedDate:"2001-01-01T01:01:01Z", // DateTime
LastUpdated: "2001-01-01T01:01:01Z", // DateTime
FieldName: "Custom Field name", // String
Type: 0, // Int (enum AdditionalValueType)
Value: "abc" // String (nullable)
},
...
]
or a negative Json response if not.
Value types can be one of the AdditionalValueTypes enumeration.
Update end user additional data
Updates the additional data contained in the body of the message relating to the user id provided:
- GET /v1/end-users/{id}/additional-data
Return the custom fields of the [id] User presents in the [AdditionalUserData] table
- Parameters
id (integer) – User id
- Status Codes
200 OK – Success
- POST /v1/end-users/{id}/additional-data
Updates the data contained in the body of the message relating to the user [id]
- Parameters
id (integer) – User ID
- Status Codes
200 OK – Success
The format of the request is:
{
AdditionalUserData: [
{
FieldName: "Additional usera data field name", // String
Value: "abc" // String
},
...
]
}
Value types can be one of the AdditionalValueTypes enumeration.
A positive or negative plain Json response will return wether or not the request was successful, and wether all the fields
have the property FieldName filled, or empty or missing.
Possible error messages are:
err_MissingRequiredFieldsThere was an error in the values of the required fields
Override system disable status
This endpoint is used by a SuperAdministrator to set the user as enabled regardless of the IsDisabledBySystem property.
- POST /v1/end-users/override-system-disable-status
Set a vehicle to overryde system operativity flag
- Status Codes
200 OK – Success
The body of the request is:
{
UserID: 123 // Int
Status: true // Boolean
}
where UserID corresponds to the user.
The API will return a plain error response if no vehicle was found for the provided ID, or one of the following error messages:
err_DisableStatusAlreadyOverriddenThe user already is set to ignore system disable status
err_AlreadyEnabledBySystemThe user is not set as disabled by system
Get the Communities Tree
Returns the tree of communities:
The request will return a positive Json response and the tree of communities:
[
{
ID: 1234, // Int
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
Name: "Community Name", // String
Level: 0, // Int
Parent: null, // Guid (nullable)
Children: // Community Array
[
{
ID: 1235, // Int
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
Name: "Community Name", // String
Level: 1, // Int
Parent: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid (nullable)
Children: []
},
...
]
},
...
]
Get Roles
Returns an array of end-user roles:
The format of the object returns is the following:
[
{
Name: "EndUser", // String
Slug: "end-user" // String
},
...
]
Get users by group
Gets the list of all the users member of the group specified by the provided ID:
It returns a list with all the users belonging to the group id provided:
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
UserName: "UserName", // String
Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid
AdditionalData:
[
{
ID: 1234, // Int
CreatedDate:"2001-01-01T01:01:01Z", // DateTime
LastUpdated: "2001-01-01T01:01:01Z", // DateTime
FieldName: "Custom Field name", // String
Type: 0, // Int (enum AdditionalValueType)
Value: "abc" // String
},
...
],
LastLogonTimestamp: "2001-01-01T01:01:01Z", // DateTime (nullable)
LCID: 1044, // Int
Language: "en-GB", // String
IsConfirmed: true, // Boolean
IsBlocked: false, // Boolean
IsDisabled: false, // Boolean
IsDisabledByAdmin: false, // Boolean
IsDisabledBySystem: false, // Boolean
OverriddenSystemDisableStatus: false, // Boolean
SystemDisabledReason: "PAYMENT", // String (nullable)
ForcedEnabledBy: "Administrator", // String (nullable)
ForcedEnabledById: "db601954-7d61-472d-b799-e38289d50297", // Guid (nullable)
ManualApprovalDate: "2001-01-01T01:01:01Z", // DateTime (nullable)
Email: "user@email.com", // String
Name: "John", // String
Surname: "Doe", // String
FullName: "John Doe", // String
MobilePhoneNumber: "12321321", // String
Communities: ["List","of","community","Guid"], // Guid Array
AdministeredCommunities: [], // Guid Array
Roles: ["EndUser","..."] // String Array
},
...
]
Get group IDs by user
Retrieves all the groups the user related to the provided id is member of, and returns the array of their ids:
The request will return a positive Json response and a list of the group IDs:
{
[1,2,3,4,5,...]
}
Get groups by user
Returns the list of all the groups the user related to the provided id is member of:
It returns a list like this:
[
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
LastUpdated: "2001-01-01T01:01:01Z", // DateTime
Labels: "{\"en\":\"GroupName\",\"it\":\"\"}" // String
},
...
]
Save Groups
Updates the group membership of the user related to the provided ID:
With a request body like this:
{
ID: 1234, // Int
Groups: [1,2,3,4] // Int Array
}
where ID is the user ID and Groups is an array of ID of the groups he is member of.
If the request is successful, it will return a positive Json response with no additional data.
Possible error messages:
err_InvalidElementNo user corresponds to the
IDprovided in the request