OS1 Services
...
User API
Retrieve Users
10 min
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 true false 296false unhandled content type false unhandled content type false unhandled content type false unhandled content type 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 true false 240false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type retrieve email you can retrieve the email for one or multiple users by specifying their userids in the getuseremail request query parameters true falsefalse unhandled content type false unhandled content type false unhandled content type false unhandled content type 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 true falsefalse unhandled content type false unhandled content type false unhandled content type false unhandled content type 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