Find Users

Find users in the identity store. The command uses the PV_USERS public view to find data. Any filters passed should apply to this public view.

GET https://instance.securid.com/aveksa/command.submit?cmd=findUsers

Request

Parameters

command	findUsers
format	`properties` - (Default) Returns the response as `key=value` pairs. When multiple objects are returned, values are comma-delimited: `key=value1,value2,value3`. `json` - Returns the response as JSON. `csv` - Returns the response as comma-separated values. `tsv` - Returns the response as tab-separated values. `xml` - Returns the response as XML.
delimiter	The delimiter to use between values for `csv` and `properties` formats
returnColumns	The names of the columns to return. `returnColumns` may be a CSV list of multiple column names. The parameter may also be listed multiple times (ie `returnColumns=col1,col2&returnColumns=col3,col4`) Refer to Columns table below.
returnMaxRows	The maximum number of objects to return
distinct	`true, false` Returns only distinct values, equivalent to the distinct keyword in SQL.
sortByColumns	The results will be sorted based on the columns listed using comma as the delimiter if multiple columns are specified. Refer to Columns table below.
sortDirection	Determines sorting order. `asc` for ascending, `desc` for descending. If not specified, the natural order returned by the database is used.
includeHeaderRow	`true, false` Include column headers when the return format is `csv` or `tsv`. (Default) `true`
ignoreCase	`true, false` Returns case-insensitive search results for specified filter parameters. (Default) `false`

Filter Parameters

Any column listed in the Columns table can be passed as a filter parameter to narrow results. Filters are matched against the PV_USERS public view.

Query logic

Scenario	Behavior
Two different parameters: `last_name=Doe&department=Finance`	AND. Returns users with last name Doe who belong to the Finance department.
Same parameter repeated: `last_name=Doe&last_name=Smith`	OR within that field. Returns users with last name Doe or Smith.
Mixed: `department=Finance&last_name=Doe&last_name=Smith`	(department is Finance) AND (last_name is Doe or Smith)

OR logic across different parameters is not supported

A single API call cannot return users where last_name=Doe OR department=Finance. OR logic between different filter parameters is not supported.

Workaround: Make separate requests for each filter condition. Merge and deduplicate the results client-side.

Columns

id	[Primary Key] Unique user identifier
idc_id	[Foreign Key referencing IDENTITY_COLLECTOR.ID] Identity collector that loaded this user
add_state	Pending add workflow state. `0` = no pending add, `30` = pending CR creation, `50` = pending approval, `60` = pending delayed fulfillment, `70` = pending fulfillment, `80` = pending verification
remove_state	Pending remove workflow state. `0` = no pending remove, `30` = pending CR creation, `50` = pending approval, `60` = pending delayed fulfillment, `70` = pending fulfillment, `80` = pending verification
user_id	User's external identifier (login name)
unique_id	User's external unique identifier (UUID)
first_name	User's first name
last_name	User's last name
title	User's job title
department	User's department name
email_address	User's email address
employee_id	User's employee ID from the identity source
company	User's company name
user_type	User type classification
job_status	User's current job status
jml_status	Joiner, mover, or leaver status used internally for lifecycle workflows
is_terminated	`True, False` Indicates whether the user has been terminated. Stored with a capital first letter.
hire_date	User's hire date (formatted)
hire_date__raw_	User's hire date (raw value from the identity source)
termination_date	User's termination date (formatted)
termination_date__raw_	User's termination date (raw value from the identity source)
supervisor_id	[Foreign Key referencing USERS.ID] User ID of the direct supervisor
supervisor_id_name	Display name of the direct supervisor
backup_supervisor	[Foreign Key referencing USERS.ID] User ID of the backup supervisor
backup_supervisor_name	Display name of the backup supervisor
business_unit_id	[Foreign Key referencing BUSINESS_UNIT.ID] Business unit the user belongs to
availability_status	Out of Office status for the user
is_masked	`Y, N` Whether this user record is masked for privacy
masking_run_id	ID of the masking run that anonymized this record
creation_date	Date and time the user record was created
deletion_date	Date and time the user record was removed
exception_count	Number of open exceptions for this user
violation_count	Number of open SoD violations for this user
cau1 … cauN	Custom user-type attribute values. Reference names are configured per instance.
cad1 … cadN	Custom date-type attribute values. Reference names are configured per instance.
cas1 … casN	Custom string-type attribute values. Reference names are configured per instance.

Headers

Authorization	Bearer `token`
Accept	application/json
Content-Type	application/json

Response

Parameters

The API returns the requested columns specified by returnColumns as output. If returnColumns is unspecified then all columns listed will be returned.

Examples

All columns

Omit returnColumns to return every field for each user.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=2" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "json",
    "returnMaxRows": "2"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "json",
        returnMaxRows: "2"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

{
  "findUsers": [
    {
      "id": "1",
      "idc_id": "3",
      "add_state": "0",
      "remove_state": "0",
      "backup_supervisor_name": "",
      "supervisor_id_name": "",
      "is_masked": "N",
      "masking_run_id": "",
      "supervisor_id": "",
      "availability_status": "",
      "backup_supervisor": "",
      "business_unit_id": "",
      "creation_date": "2024-03-15 06:03:46.0",
      "deletion_date": "",
      "department": "",
      "email_address": "John.Smith@example.com",
      "exception_count": "",
      "first_name": "John",
      "is_terminated": "False",
      "jml_status": "",
      "job_status": "",
      "last_name": "Smith",
      "termination_date": "",
      "title": "",
      "unique_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": "jsmith",
      "violation_count": "",
      "employee_id": "",
      "company": "",
      "hire_date": "",
      "hire_date__raw_": "",
      "termination_date__raw_": "",
      "user_type": ""
    },
    {
      "id": "2",
      "idc_id": "3",
      "add_state": "0",
      "remove_state": "0",
      "backup_supervisor_name": "",
      "supervisor_id_name": "",
      "is_masked": "N",
      "masking_run_id": "",
      "supervisor_id": "",
      "availability_status": "",
      "backup_supervisor": "",
      "business_unit_id": "",
      "creation_date": "2024-03-15 06:03:46.0",
      "deletion_date": "",
      "department": "",
      "email_address": "Jane.Doe@example.com",
      "exception_count": "",
      "first_name": "Jane",
      "is_terminated": "False",
      "jml_status": "",
      "job_status": "",
      "last_name": "Doe",
      "termination_date": "",
      "title": "",
      "unique_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "user_id": "jdoe",
      "violation_count": "",
      "employee_id": "",
      "company": "",
      "hire_date": "",
      "hire_date__raw_": "",
      "termination_date__raw_": "",
      "user_type": ""
    }
  ]
}

Specific columns

Use returnColumns to limit the response to the fields you need. This keeps the payload small and the mapping work simple. The example returns six columns covering the most common user reporting needs.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=3&returnColumns=id,user_id,first_name,last_name,email_address,is_terminated" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "json",
    "returnMaxRows": "3",
    "returnColumns": "id,user_id,first_name,last_name,email_address,is_terminated"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "json",
        returnMaxRows: "3",
        returnColumns: "id,user_id,first_name,last_name,email_address,is_terminated"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

200
412 Invalid column

{
  "findUsers": [
    {
      "id": "1",
      "user_id": "jsmith",
      "first_name": "John",
      "last_name": "Smith",
      "email_address": "John.Smith@example.com",
      "is_terminated": "False"
    },
    {
      "id": "2",
      "user_id": "jdoe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email_address": "Jane.Doe@example.com",
      "is_terminated": "False"
    },
    {
      "id": "3",
      "user_id": "abrown",
      "first_name": "Alex",
      "last_name": "Brown",
      "email_address": "Alex.Brown@example.com",
      "is_terminated": "False"
    }
  ]
}

<html>
  <head><title>Error</title></head>
  <body>The parameter returncolumns contains an invalid column - `invalid_col`.
Query String=cmd=findUsers&amp;format=json&amp;returnMaxRows=2&amp;returnColumns=id,invalid_col</body>
</html>

Filter by a single value

Pass any column name as a query parameter to filter results. Only users that match the value are returned. The example returns users where last_name is Doe.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=5&returnColumns=id,user_id,first_name,last_name,department&last_name=Doe" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "json",
    "returnMaxRows": "5",
    "returnColumns": "id,user_id,first_name,last_name,department",
    "last_name": "Doe"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "json",
        returnMaxRows: "5",
        returnColumns: "id,user_id,first_name,last_name,department",
        last_name: "Doe"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

{
  "findUsers": [
    {
      "id": "2",
      "user_id": "jdoe",
      "first_name": "Jane",
      "last_name": "Doe",
      "department": ""
    },
    {
      "id": "10001",
      "user_id": "USR-0001",
      "first_name": "Jane",
      "last_name": "Doe",
      "department": "PS Delivery"
    }
  ]
}

Filter with OR logic

Repeat the same parameter with different values to match any of them. The example returns users where last_name is Doe or Smith.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=5&returnColumns=id,user_id,first_name,last_name&last_name=Doe&last_name=Smith" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = [
    ("cmd", "findUsers"),
    ("format", "json"),
    ("returnMaxRows", "5"),
    ("returnColumns", "id,user_id,first_name,last_name"),
    ("last_name", "Doe"),
    ("last_name", "Smith")
]
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

const params = new URLSearchParams();
params.append('cmd', 'findUsers');
params.append('format', 'json');
params.append('returnMaxRows', '5');
params.append('returnColumns', 'id,user_id,first_name,last_name');
params.append('last_name', 'Doe');
params.append('last_name', 'Smith');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params,
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

{
  "findUsers": [
    {
      "id": "1",
      "user_id": "jsmith",
      "first_name": "John",
      "last_name": "Smith"
    },
    {
      "id": "2",
      "user_id": "jdoe",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    {
      "id": "10001",
      "user_id": "USR-0001",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  ]
}

Case-insensitive filter

Filters are case-sensitive by default. Set ignoreCase=true to match regardless of case. The is_terminated field stores values as True or False with a capital first letter. The example passes is_terminated=false in lowercase and still returns matching records.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=3&returnColumns=id,user_id,first_name,last_name,is_terminated&is_terminated=false&ignoreCase=true" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "json",
    "returnMaxRows": "3",
    "returnColumns": "id,user_id,first_name,last_name,is_terminated",
    "is_terminated": "false",
    "ignoreCase": "true"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "json",
        returnMaxRows: "3",
        returnColumns: "id,user_id,first_name,last_name,is_terminated",
        is_terminated: "false",
        ignoreCase: "true"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

{
  "findUsers": [
    {
      "id": "1",
      "user_id": "jsmith",
      "first_name": "John",
      "last_name": "Smith",
      "is_terminated": "False"
    },
    {
      "id": "2",
      "user_id": "jdoe",
      "first_name": "Jane",
      "last_name": "Doe",
      "is_terminated": "False"
    },
    {
      "id": "3",
      "user_id": "abrown",
      "first_name": "Alex",
      "last_name": "Brown",
      "is_terminated": "False"
    }
  ]
}

Sort ascending

Use sortByColumns with a column name and sortDirection=asc to sort results from lowest to highest. The example sorts by id.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=3&returnColumns=id,user_id,first_name,last_name&sortByColumns=id&sortDirection=asc" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "json",
    "returnMaxRows": "3",
    "returnColumns": "id,user_id,first_name,last_name",
    "sortByColumns": "id",
    "sortDirection": "asc"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "json",
        returnMaxRows: "3",
        returnColumns: "id,user_id,first_name,last_name",
        sortByColumns: "id",
        sortDirection: "asc"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

{
  "findUsers": [
    {
      "id": "-3",
      "user_id": "GLDevOps-00000000-0000-0000-0000-000000000001",
      "first_name": " ",
      "last_name": "GLDevOps"
    },
    {
      "id": "0",
      "user_id": "AveksaAdmin",
      "first_name": " ",
      "last_name": "AveksaAdmin"
    },
    {
      "id": "1",
      "user_id": "jsmith",
      "first_name": "John",
      "last_name": "Smith"
    }
  ]
}

Sort descending

Set sortDirection=desc to reverse the order.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=json&returnMaxRows=3&returnColumns=id,user_id,first_name,last_name&sortByColumns=id&sortDirection=desc" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "json",
    "returnMaxRows": "3",
    "returnColumns": "id,user_id,first_name,last_name",
    "sortByColumns": "id",
    "sortDirection": "desc"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.json())

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "json",
        returnMaxRows: "3",
        returnColumns: "id,user_id,first_name,last_name",
        sortByColumns: "id",
        sortDirection: "desc"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

{
  "findUsers": [
    {
      "id": "51337",
      "user_id": "mwilson",
      "first_name": "Michael",
      "last_name": "Wilson"
    },
    {
      "id": "51336",
      "user_id": "lwang",
      "first_name": "Li",
      "last_name": "Wang"
    },
    {
      "id": "51230",
      "user_id": "rgarcia",
      "first_name": "Robert",
      "last_name": "Garcia"
    }
  ]
}

CSV with custom delimiter

Set format=csv for a comma-separated response. Use delimiter to change the separator character.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=csv&returnMaxRows=3&returnColumns=id,user_id,first_name,last_name,email_address&delimiter=~" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "csv",
    "returnMaxRows": "3",
    "returnColumns": "id,user_id,first_name,last_name,email_address",
    "delimiter": "~"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.text)

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "csv",
        returnMaxRows: "3",
        returnColumns: "id,user_id,first_name,last_name,email_address",
        delimiter: "~"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

id~user_id~first_name~last_name~email_address
1~jsmith~John~Smith~John.Smith@example.com
2~jdoe~Paul~Doe~Jane.Doe@example.com
3~abrown~Alex~Brown~Alex.Brown@example.com

CSV without header row

Set includeHeaderRow=false when your downstream system expects raw data rows without a header.

Request

Curl
Python
Node.js

curl -K -X GET \
"https://instance.securid.com/aveksa/command.submit?cmd=findUsers&format=csv&returnMaxRows=3&returnColumns=id,user_id,first_name,last_name,email_address&includeHeaderRow=false" \
-H "Authorization: Bearer <token>"

import requests

url = "https://instance.securid.com/aveksa/command.submit"
params = {
    "cmd": "findUsers",
    "format": "csv",
    "returnMaxRows": "3",
    "returnColumns": "id,user_id,first_name,last_name,email_address",
    "includeHeaderRow": "false"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, params=params, headers=headers)
print(response.text)

const axios = require('axios');

axios.get("https://instance.securid.com/aveksa/command.submit", {
    params: {
        cmd: "findUsers",
        format: "csv",
        returnMaxRows: "3",
        returnColumns: "id,user_id,first_name,last_name,email_address",
        includeHeaderRow: "false"
    },
    headers: { Authorization: "Bearer <token>" }
}).then(r => console.log(r.data));

Response

1,jsmith,John,Smith,John.Smith@example.com
2,jdoe,Paul,Doe,Jane.Doe@example.com
3,abrown,Alex,Brown,Alex.Brown@example.com

Error responses

A 401 is returned when the token is missing, invalid, or expired. A 412 is returned when returnColumns includes a column name that does not exist in the PV_USERS public view.

401 Invalid token
412 Invalid column

<html>
  <head><title>Error</title></head>
  <body>The token is not valid for the command 'findUsers'. Token is invalid or expired</body>
</html>

<html>
  <head><title>Error</title></head>
  <body>The parameter returncolumns contains an invalid column - `invalid_col`.
Query String=cmd=findUsers&amp;format=json&amp;returnMaxRows=2&amp;returnColumns=id,invalid_col</body>
</html>

Verified with RSA Governance & Lifecycle version 8.0.0.188886 P10_HF01.

Request​

Parameters​

Filter Parameters​

Columns​

Headers​

Response​

Parameters​

Examples​

All columns​

Specific columns​

Filter by a single value​

Filter with OR logic​

Case-insensitive filter​

Sort ascending​

Sort descending​

CSV with custom delimiter​

CSV without header row​

Error responses​

Request

Parameters

Filter Parameters

Columns

Headers

Response

Parameters

Examples

All columns

Specific columns

Filter by a single value

Filter with OR logic

Case-insensitive filter

Sort ascending

Sort descending

CSV with custom delimiter

CSV without header row

Error responses