Screendragon API Integration Use Cases - Users

Modified on Tue, 30 Sep at 10:56 AM

List Users
Fetch User Details(By ID)
Fetch User Details(By Username)
Create a New User
Update a User
Update Users in Bulk
Delete/Deactivate a User
Delete/Deactivate Users in Bulk

List Users

Endpoint

GET /api/users

Description

This endpoint retrieves a list of users filtered by status, name, email, group membership, and custom metadata fields. Supports advanced filtering, metadata enrichment, and group inclusion.

Query Parameters

Name	Type	Required	Description
`emailFilter`	`String`	❌	Filter users by email substring.
`nameFilter`	`String`	❌	Filter users by full name substring.
`groupID`	`Int32`	❌	Filter users by group ID (admin only).
`filterText`	`String`	❌	Value to match in metadata filtering.
`filterBy`	`String`	❌	GUIDs of the metadata field to filter by.
`customFields`	`String`	❌	JSON string of custom metadata fields to include.
`active`	`Boolean`	❌	Include only active users.
`activeAndInactive`	`Boolean`	❌	Include both active and inactive users.
`includeCreateData`	`Boolean`	❌	Include user creation date.
`includeGroups`	`Boolean`	❌	Include group details in response.
`filterExact`	`Boolean`	❌	Use exact match for metadata filtering.

Error Handling

Status Code	Message
400	" {filterBy} and {filterText} must both be specified"
400	"Invalid {customFields} specified'"
400	"No data"

Notes

Admin privileges are required to filter by groupID.
If customFields are specified by label, the system will resolve them to GUIDs.
Temporary SQL tables are used internally to optimize filtering and grouping.
The endpoint uses internal user credentials extracted from the request context.

Sample Request

GET /api/users?emailFilter=john
&active=true&includeGroups=true

Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "userID": 123,
    "UserName": "john.doe",
    "FirstName": "John",
    "LastName": "Doe",
    "email": "john.doe@example.com",
    "status": "active",
    "CreateDate": "2023-01-15T10:00:00Z",
    "customFields": [
      {
        "guid": "abc123",
        "label": { "en": "Department" },
        "type": "text",
        "dataType": "string",
        "values": ["Engineering"]
      }
    ],
    "groups": [
      {
        "name": "Admins",
        "id": 1
      }
    ]
  }
]

Sample Response (Error)

{
  "error": "'filterBy' and 'filterText' 
                must both be specified."
}

Fetch User Details(By ID)

Endpoint

GET /api/users/{id}

Description

This endpoint retrieves detailed information about a specific user by their unique user ID. If the user exists, their full profile is returned; otherwise, an error is returned.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	The unique identifier of the user.

Error Handling

Status Code	Message
400	"No data"

Notes

The endpoint uses internal logic (GetUserDetails(id)) to fetch user data.
If the user ID does not exist or an exception occurs, a 400 Bad Request is returned.
The response structure matches the ViewUserDTO format used across the system.

Sample Request

GET /api/users/123

Authorization: Bearer <token>

Sample Response (Success)

{
  "userID": 123,
  "UserName": "john.doe",
  "FirstName": "John",
  "LastName": "Doe",
  "email": "john.doe@example.com",
  "status": "active",
  "CreateDate": "2023-01-15T10:00:00Z",
  "customFields": [...],
  "groups": [...]
}

Sample Response (Error)

{
  "error": "No data"
}

Fetch User Details(By Username)

Endpoint

GET /api/users/UserDetails

Description

This endpoint fetches detailed information about a user using their unique username. If the user exists, their full profile is returned; otherwise, an error is returned.

Path Parameters

Name	Type	Required	Description
`username`	`String`	✅	The unique username of the user.

Error Handling

Status Code	Message
400	"No data."

Notes

Internally uses GetUserDetailsByUsername(username) to retrieve user data.
If the username does not exist or an exception occurs, a 400 Bad Request is returned.
The response structure matches the ViewUserDTO format used across the system.

Sample Request

GET /api/users/UserDetails/John.Doe

Authorization: Bearer <token>

Sample Response (Success)

{
  "userID": 123,
  "UserName": "john.doe",
  "FirstName": "John",
  "LastName": "Doe",
  "email": "john.doe@example.com",
  "status": "active",
  "CreateDate": "2023-01-15T10:00:00Z",
  "customFields": [...],
  "groups": [...]
}

Sample Response (Error)

{
  "error": "No data"
}

Create a New User

Endpoint

POST /api/users

Description

This endpoint creates a new user in the system. This endpoint validates the input, checks for existing usernames, validates group tags, and inserts the user into both SQL and optionally MongoDB. Only administrators are allowed to perform this action.

Body Parameters

Name	Type	Required	Description
`userName`	`String`	✅	Unique username for the new user.
`firstName`	`String`	✅	First name of the user.
`lastName`	`String`	✅	Last name of the user.
`email`	`String`	✅	Email address of the user.
`password`	String	✅	Password for the user account.
`encryptPassword`	`Boolean`	❌	Whether to encrypt the password before storing.
`groupTags`	`String[]`	❌	Tags representing groups to assign the user to.
`isTsIngestUser`	`Int32`	❌	Indicates if the user is a TS ingest user (0 or 1).
`ssoUser`	`Int32`	❌	Indicates if the user is an SSO user (0 or 1).

Error Handling

Status Code	Message
400	"Username already exists"
400	"Some of the specified groups don't exist: [group names]"
400	"The value added for 'isTsIngestUser' is out of bounds this can only be 0/1"
400	""The value added for 'ssoUser' is out of bounds this can only be 0/1.""
400	"No data"
403	"(empty) – Returned if the user is not an admin."
400	"Failed to add user"

Notes

Only users with admin privileges can create new users.
Group tags are validated against existing groups; invalid tags will cause the request to fail.
If ssoUser is set to 1, password reset is disabled and password is not stored.
If configured, user data is also inserted into MongoDB for extended metadata handling.

Sample Request

POST /api/users
Content-Type: application/json
Authorization: Bearer <token>

{
  "userName": "jane.doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "password": "securePass123",
  "encryptPassword": true,
  "groupTags": ["engineering", "admin"],
  "isTsIngestUser": 0,
  "ssoUser": 1
}

Sample Response (Success)

12345

Sample Response (Error)

{
  "error": "Username already exists"
}

Update a User

Endpoint

PUT /api/users/{id}

Description

This endpoint updates user details such as first name, last name, email, and optionally the username. Only administrators or the user themselves can perform this update. The system also syncs the updated user data to MongoDB if configured.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier for the new user.

Body Parameters

Name	Type	Required	Description
`firstName`	`String`	✅	User's first name.
`lastName`	`String`	✅	User's last name.
`email`	`String`	✅	User's email address.

Error Handling

Status Code	Message
400	"No Data"
400	"Unauthorized update attempt."

Notes

Only admins or the user themselves can update the user record.
The system logs errors and SQL queries for debugging.

Sample Request

PUT /api/users/42
Content-Type: application/json
Authorization: Bearer <token>

{
  "firstName": "Alice",
  "lastName": "Smith",
  "email": "alice.smith@example.com"
}

Sample Response (Success)

{
  "status": "success",
  "message": "User updated successfully."
}

Sample Response (Error)

{
  "error": "Unauthorized update attempt."
}

Update Users in Bulk

Endpoint

PUT /api/users/details

Description

This endpoint allows administrators to submit a batch update of user details. The update request is queued for asynchronous processing. Only users with administrative privileges can perform this action.

Body Parameters

The request body must be a JSON array of user objects with the above fields.

Name	Type	Required	Description
`UserId`	`Int32`	✅	Unique identifier of the user to update.
`FirstName`	`String`	❌	Updated first name of the user.
`LastName`	`String`	❌	Updated last name of the user.
`Email`	`String`	❌	Updated email address of the user.
`Role`	`String`	❌	Updated role or designation of the user.

Error Handling

Status Code	Message
400	"You must be an Admin to perform this action."
400	"No data."
500	"Internal server error."

Notes

Only admins or the user themselves can update the user record.
The system logs errors and SQL queries for debugging.

Sample Request

PUT /api/users/details
Content-Type: application/json
Authorization: Bearer <token>

[
  {
    "UserId": 42,
    "FirstName": "Jane",
    "LastName": "Doe",
    "Email": "jane.doe@example.com",
    "Role": "Manager"
  },
  {
    "UserId": 43,
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "john.smith@example.com",
    "Role": "Analyst"
  }
]

Sample Response (Success)

{
  "message": "Your User Updates request
 has been accepted for processing."
}

Sample Response (Error)

{
  "error": "You must be an Admin to
   perform this action."
}

Delete/Deactivate a User

Endpoint

DELETE /api/users/{id}

Description

This endpoint deactivates a user by ID, logs the action in the User Status Log, and optionally schedules the deletion or reassigns the user’s responsibilities. It also validates the current user's credentials and permissions before proceeding.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	ID of the user to be deleted.

Query Parameters

Name	Type	Required	Description
`scheduledDate`	`String`	❌	Optional date (ISO 8601 format) to schedule the deletion. Defaults to "".
`assignUserID`	`Int32`	❌	Optional ID of the user to reassign responsibilities to. Defaults to -1.

Error Handling

Status Code	Message
400	"No Data"
401	"Unauthorized update access."
403	"Insufficient permissions"
404	"User not found"
500	"Internal server error"

Notes

Only users with administrative privileges can invoke this endpoint successfully.
The update is queued and processed asynchronously; the response confirms acceptance, not completion.
Errors during processing are logged internally with user and session context.

Sample Request

DELETE /api/users/42
&scheduledDate=2025-08-01&assignUserID=101

Authorization: Bearer <token>

Sample Response (Success)

{
  "status": "User deactivated successfully"
}

Sample Response (Error)

{
  "error": "No data"
}

Delete/Deactivate Users in Bulk

Endpoint

DELETE /api/users

Description

This endpoint allows administrators to submit a batch deletion request for multiple users. The request is queued for asynchronous processing. Only users with administrative privileges can perform this action.

Body Parameters

The request body must be a JSON array of integers representing user IDs.

Name	Type	Required	Description
`userIds`	`List`	✅	A list of user IDs to be deleted.

Error Handling

Status Code	Message
400	"You must be an Admin to perform this action"
400	"No data."
500	"Internal server error"

Notes

Only users with administrative privileges can invoke this endpoint successfully.
The deletion is queued and processed asynchronously; the response confirms acceptance, not completion.
Errors during processing are logged internally with user and session context.

Sample Request

DELETE /api/users
Content-Type: application/json
Authorization: Bearer <token>

[42, 43, 44]

Sample Response (Success)

{
  "message": "Your user deletion request 
    has been accepted for processing."
}

Sample Response (Error)

{
  "error": "You must be an Admin
    to perform this action."
}