OS1 Services
...
User Management Service
User API

Retrieve Users

10min
overview developers can use the following endpoints in the user api to get detailed information about users, such as their id, email, and phone number getuser retrieves a single user by id or external ref listusers list all users within an organization getuseremail retrieves the email of a user or multiple users by id getusermobile retrieves the mobile number of a user or multiple users by id retrieve a user by id to get details about a user, including their id, name, work locations, etc , call getuser path parameters parameter description userid the unique id of the user you can also use the aaaid , usercode , or uniquecode with the "ref" prefix sample response if the call is successful, the api returns a 200 status code with the user's details see the example response below { "error" null, "data" { "id" "users 7d2f1c9e d454 4b3f 9f1a e8d8f1c6d8e70", "state" "onboarding\ completed", "participanttype" "users", "name" "john doe", "owner" "tenants\ abcdefghij", "uniquecode" "jd12345", "category" "employee", "subcategory" "full time", "templateid" "template\ qwertyuiop", "properties" { "worklocations" \[ "new york", "london" ], "teams" \[ "engineering", "product" ], "identification" { "idtype" "passport", "idnum" "abc123456" }, "fileid" "file\ zxcvbnm", "usertype" "admin", "department" "it", "aaaid" "aaa\ asdfghjkl", "aaagroups" \[ "group1", "group2" ], "designation" "senior software engineer", "employmenttype" "full time" }, "createdat" 1257894000, "createdby" { "id" "7", "name" "shivam" }, "updatedat" 1257894000, "updatedby" { "id" "7", "name" "shivam" } }, "request" { "uri" "/api/v1/users/users 7d2f1c9e d454 4b3f 9f1a e8d8f1c6d8e7", "requestid" "req 12345", "querystring" "includeproperties=true", "body" {}, "method" "get" } } the data field in the response contains the details of the retrieved user the id is the unique identifier of the user (user 7d2f1c9e d454 4b3f 9f1a e8d8f1c6d8e7) state represents the user's current state, which is onboarding\ completed in this example other fields such as participanttype , name , owner , uniquecode , category , subcategory , and templateid provide additional information about the user the properties field contains various user specific properties such as worklocations , teams , identification , fileid , usertype , department , aaaid , aaagroups , designation , and employmenttype createdat and updatedat fields represent the timestamp of when the user was created and last updated, respectively createdby and updatedby fields provide information about the user who created, and last updated the user record list users to get a list of all users in the organization, call listusers parameter description size number of items in a page page page number to return(starting from 1) select specifies a list of attributes to be included in the response (id is always included in the response) if not specified, all attributes are included in the response query query criteria refer following links for more details match https //www elastic co/guide/en/elasticsearch/reference/current/query dsl match query html multi match https //www elastic co/guide/en/elasticsearch/reference/current/query dsl multi match query html term https //www elastic co/guide/en/elasticsearch/reference/current/query dsl term query html terms https //www elastic co/guide/en/elasticsearch/reference/current/query dsl terms query html range https //www elastic co/guide/en/elasticsearch/reference/current/query dsl range query html regexp https //www elastic co/guide/en/elasticsearch/reference/current/query dsl regexp query html exists https //www elastic co/guide/en/elasticsearch/reference/current/query dsl exists query html fuzzy https //www elastic co/guide/en/elasticsearch/reference/current/query dsl fuzzy query html prefix https //www elastic co/guide/en/elasticsearch/reference/current/query dsl prefix query html wildcard https //www elastic co/guide/en/elasticsearch/reference/current/query dsl wildcard query html match phrase https //www elastic co/guide/en/elasticsearch/reference/current/query dsl match query phrase html match phrase prefix https //www elastic co/guide/en/elasticsearch/reference/current/query dsl match query phrase prefix html sortby fetching data in ascending(asc) or descending(desc) order available values desc, asc default value desc sortkey key to be used for sorting data additionalinfo key to toggle fetching of additionalinfo available values true, false retrieve email you can retrieve the email for one or multiple users by specifying their userids in the getuseremail request query parameters parameter description ids this query parameter can contain a list of user ids or unique codes separated by a comma invalid user ids are ignored you can include up to 10 ids in the request example response { "data" { "meta" { "totalelements" 2 }, "users" \[ { "userid" "3fa85f64 5717 4562 b3fc 2c963f66afa6", "email" "johndoe\@example com", "uniquecode" "jd12345" }, { "userid" "7d2f1c9e d454 4b3f 9f1a e8d8f1c6d8e7", "email" "janedoe\@example com", "uniquecode" "jd54321" } ] }, "request" { "uri" "/api/v1/users/emails", "requestid" "req 67890", "querystring" "page=1\&pagesize=10", "body" {}, "method" "get" }, "error" null } in this sample response, the data field contains the response data for the getuseremail api meta provides metadata about the response, such as the total number of elements ( totalelements ) matching the query in this example, two users were returned users is an array of user objects, where each object contains the following fields userid the unique identifier of the user email the email address associated with the user uniquecode a unique code assigned to the user retrieve mobile number you can retrieve the mobile phone number for one or multiple users by specifying their userids in the getusermobile request query parameters parameter description userid this query parameter can contain a list of user ids or unique codes separated by a comma invalid user ids are ignored you can include up to 10 ids in the request example response { "data" { "meta" { "totalelements" 2 }, "users" \[ { "userid" "9d2f1c9e d454 4b3f 9f1a e8d8f1c6d8e7", "primarymobile" { "countrycode" "91", "number" "9876543210" }, "secondarymobile" { "countrycode" "91", "number" "8765432109" }, "uniquecode" "jd12345" }, { "userid" "112f1c9e d454 4b3f 9f1a e8d8f1c6d8e7", "primarymobile" { "countrycode" "1", "number" "5551234567" }, "secondarymobile" null, "uniquecode" "jd54321" } ] }, "request" { "uri" "/api/v1/users/mobiles", "requestid" "req 23456", "querystring" "page=1\&pagesize=10", "body" {}, "method" "get" }, "error" null } in this sample response, the data field contains the response data for the getusermobile api meta provides metadata about the response, such as the total number of elements ( totalelements ) matching the query in this example, there are 2 users returned users is an array of user objects, where each object contains the following fields userid the unique identifier of the user primarymobile an object representing the user's primary mobile number, with countrycode and number fields secondarymobile an object representing the user's secondary mobile number, with countrycode and number fields it can be null if the user doesn't have a secondary mobile number uniquecode a unique code assigned to the user