{ "info": { "title": "People API V1 Server", "description": "Presents developer entrypoints to the People API features", "version": "1.0.0" }, "paths": { "/people/api/v1/auth/login": { "get": { "summary": "Logs in a user and returns an authentication token.", "description": "Authenticates user credentials and provides an authentication token upon successful login. Note that API based login with credentials is not supported for OIDC-based authentication.\n If accessed via a browser, this endpoint will initiate the OIDC authentication flow (if configured) and then redirect back to the application landing page with the token.", "parameters": [ { "name": "userId", "type": "string", "required": false, "description": "The user ID.", "in": "query" }, { "name": "password", "type": "string", "required": false, "description": "The user password.", "in": "query" } ], "responses": { "200": { "description": "Login successful." }, "400": { "description": "Bad request. The request is missing required parameters or is invalid." } }, "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/auth/logout": { "get": { "summary": "Logs out the current user.", "description": "Terminates the current user session by invalidating the authentication token. \n This action logs the user out of the application but does not automatically log the user out of the OIDC provider.\n If accessed via a browser, this endpoint will initiate the OIDC logout flow, if configured, to log the user out of the OIDC provider as well. \n After completing the OIDC logout flow, the user is redirected back to the application login page.", "parameters": [], "responses": { "200": { "description": "Logout successful." }, "400": { "description": "Bad request. The request is missing required parameters or is invalid." } }, "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/auth/profile": { "get": { "summary": "Retrieves the authenticated user's profile.", "description": "Returns profile details for the authenticated user, optionally including permissions based on the query parameter.", "parameters": [ { "name": "withAcls", "type": "boolean", "required": false, "default": false, "description": "If true, returns user with available permissions.", "in": "query" } ], "responses": { "200": { "description": "User profile retrieval successful.", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } } }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "404": { "description": "User profile not found." } }, "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/auth/token": { "post": { "summary": "Authenticates the user and maps the token to the current session.", "description": "Takes a valid JWT token, authenticates the user based on this token, and maps the authentication token to the user's current session.\n This is typically used in scenarios where the session needs to be established or updated based on a new token.", "parameters": [ { "name": "data", "description": "request body", "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "in": "body" } ], "responses": { "200": { "description": "Token provided successfully." }, "400": { "description": "Bad request. The request is missing required parameters or is invalid." } }, "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/auth/refresh": { "get": { "summary": "Refreshes the current auth token.", "description": "Renews the authentication token to extend the session. Requires a valid, non-expired refresh token.", "parameters": [ { "name": "data", "description": "request body", "schema": { "type": "object", "required": [ "refreshToken" ], "properties": { "refreshToken": { "type": "string", "description": "The refresh token to be renewed." } } }, "in": "body" } ], "responses": { "200": { "description": "Token refreshed successfully." }, "400": { "description": "Bad request. The request is missing required parameters or is invalid." } }, "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/acl": { "get": { "summary": "Retrieves the Access Control List (ACL) for the requesting user.", "description": "The ACL service allows users to retrieve their ACL, which defines the permissions and access levels granted to them for various resources within the system.\n This endpoint provides a mechanism for users or clients to view their current access rights, helping them understand which resources they can access and what actions they can perform.", "parameters": [], "responses": { "200": { "description": "ACL retrieval successful.", "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "exampleAcl": [ "view_own_profile", "view_any_profile", "search_profiles", "edit_own_profile", "view_network_contact_info" ] } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "Authentication" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/people": { "get": { "summary": "Get a list of people", "description": "Retrieves a list of people with various scopes such as minified, essential, ui, or full.", "parameters": [ { "name": "criteria", "type": "string", "required": false, "description": "Advanced search criteria, e.g. { organization: 'company', city: 'mycity' }", "in": "query" }, { "name": "scope", "type": "string", "required": false, "description": "Defines the scope of data: minified, essential, ui, full", "in": "query" }, { "name": "p", "type": "integer", "required": false, "description": "Page number for results pagination", "default": 1, "in": "query" }, { "name": "ps", "type": "integer", "required": false, "description": "Page size for results pagination", "default": 20, "in": "query" } ], "responses": { "200": { "description": "People retrieved successfully.", "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } } }, "examples": { "peopleFullExample": [ { "id": 1, "guid": "admin", "email": "admin@test.com", "organization": "company", "displayName": "Admin User", "firstName": "Admin", "lastName": "User", "phone": "+1234567890", "streetAddress": "Downtown", "city": "New York", "state": "NY", "zipCode": "10001", "country": "USA", "timeZone": "America/New_York", "language": "English", "role": "Technical Admin", "userState": "active", "created": "2024-04-08T09:57:00.052Z", "modified": "2024-04-08T09:57:00.052Z", "professionalSummary": "I am a technical admin.", "profilePhoto": "https://example.com/profile.jpg", "customFields": {} } ], "peopleMinifiedExample": [ { "id": 1, "guid": "admin", "email": "admin@test.com", "displayName": "Admin User" } ] } }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "People / Profiles" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new user profile with the provided profile attributes.", "description": "This operation expects a complete user object containing all mandatory fields required for user creation.", "parameters": [ { "name": "data", "description": "request body", "schema": { "type": "object", "required": [ "guid", "email", "organization", "displayName", "country", "timeZone", "role" ], "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } }, "in": "body" } ], "responses": { "201": { "description": "User created successfully.", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } }, "examples": { "personExample": { "id": 1, "guid": "jdoe", "email": "john.doe@testdomain.com", "organization": "Acme Corporation", "displayName": "John Doe", "firstName": "John", "lastName": "Doe", "phone": "+1 626 902 8073", "streetAddress": "456 Fictional Lane", "city": "Sampleville", "state": "DemoState", "zipCode": "54321", "country": "America/New_York", "timeZone": "USA", "language": "English", "role": "Chief Example Officer", "userState": "active", "created": "2020-01-01T00:00:00.000Z", "modified": "2020-01-01T00:00:00.000Z", "professionalSummary": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "profilePhoto": "https://www.gravatar.com/a", "customFields": {} } } }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to create a new user profile." } }, "tags": [ "People / Profiles" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/people/{id}": { "get": { "summary": "Get details of a person by their ID", "description": "Retrieves details of a specific person by their ID. Supports different data scopes to retrieve minified, essential, ui, or full data.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the person to retrieve", "in": "path" }, { "name": "scope", "type": "string", "required": false, "description": "Defines the scope of data: minified, essential, ui, full", "in": "query" } ], "responses": { "200": { "description": "Person retrieved successfully.", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } }, "examples": { "personFullExample": { "id": 1, "guid": "jdoe", "email": "john.doe@testdomain.com", "organization": "Acme Corporation", "displayName": "John Doe", "firstName": "John", "lastName": "Doe", "phone": "+1 626 902 8073", "streetAddress": "456 Fictional Lane", "city": "Sampleville", "state": "DemoState", "zipCode": "54321", "country": "America/New_York", "timeZone": "USA", "language": "English", "role": "Chief Example Officer", "userState": "active", "created": "2020-01-01T00:00:00.000Z", "modified": "2020-01-01T00:00:00.000Z", "professionalSummary": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "profilePhoto": "https://www.gravatar.com/a", "customFields": {} }, "personMinifiedExample": { "id": 1, "guid": "jdoe", "email": "john.doe@testdomain.com", "displayName": "John Doe" } } }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "404": { "description": "Person not found." } }, "tags": [ "People / Profiles" ], "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Updates an existing user.", "description": "This operation expects a partial user object with the guid to identify the user and only the fields that need to be updated.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The unique identifier (GUID) of the user to update.", "in": "path" }, { "name": "data", "description": "request body", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } }, "in": "body" } ], "responses": { "200": { "description": "User updated successfully.", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } }, "examples": { "personExample": { "id": 1, "guid": "jdoe", "email": "john.doe@testdomain.com", "organization": "Acme Corporation", "displayName": "John Doe", "firstName": "John", "lastName": "Doe", "phone": "+1 626 902 8073", "streetAddress": "456 Fictional Lane", "city": "Sampleville", "state": "DemoState", "zipCode": "54321", "country": "America/New_York", "timeZone": "USA", "language": "English", "role": "Chief Example Officer", "userState": "active", "created": "2020-01-01T00:00:00.000Z", "modified": "2020-01-01T00:00:00.000Z", "professionalSummary": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "profilePhoto": "https://www.gravatar.com/a", "dataSource": "LDAP", "customFields": {} } } }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to update the user profile." }, "404": { "description": "User not found." } }, "tags": [ "People / Profiles" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Deletes an existing user.", "description": "Deletes a user identified by their unique identifier (GUID).", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The unique identifier (GUID) of the user to delete.", "in": "path" } ], "responses": { "204": { "description": "User deleted successfully." }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to create a new user profile." }, "404": { "description": "User not found." } }, "tags": [ "People / Profiles" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/people/{id}/state": { "put": { "summary": "Change the state of a user.", "description": "Changes the state of a user to either active or inactive.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The unique identifier (GUID) of the user to change the state.", "in": "path" }, { "name": "data", "description": "request body", "schema": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "description": "The new state of the user: active or inactive." } } }, "in": "body" } ], "responses": { "200": { "description": "User state changed successfully." }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to change the user state." }, "404": { "description": "User not found." } }, "tags": [ "People / Profiles" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/schema": { "get": { "summary": "Retrieves the schema for person profiles.", "description": "Provides extended information about the shape of user profiles and their attributes. \n This includes metadata such as attribute behavior, default values, whether attributes are required, read-only, searchable, should be hidden from the UI, the type of the value, and more. \n It can be used for dynamic form generation or validating user profile data client-side.", "parameters": [], "responses": { "200": { "description": "Schema retrieval successful.", "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "required": { "type": "boolean", "example": false }, "example": { "type": "string", "example": "exampleValue" }, "length": { "type": "number", "example": 256 }, "isReadOnly": { "type": "boolean", "example": false }, "writeable": { "type": "boolean", "example": true }, "allowEmpty": { "type": "boolean", "example": true }, "isHidden": { "type": "boolean", "example": false }, "isConstant": { "type": "boolean", "example": false }, "isGenerated": { "type": "boolean", "example": true } } } }, "examples": { "peopleSchemaExample": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "People / Schema" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/customFields/schema": { "get": { "summary": "Retrieves the schema for custom fields.", "description": "Provides the schema definition for custom fields, including metadata such as field type, default values, and validation rules.\n It can be used for dynamic form generation and client-side validation.", "parameters": [], "responses": { "200": { "description": "Custom fields schema retrieved successfully.", "schema": { "type": "object", "additionalProperties": { "type": "object", "required": [ "type", "required", "example" ], "properties": { "type": { "type": "string", "example": "string" }, "required": { "type": "boolean", "example": true }, "example": { "type": "any", "example": "companyId" } } } }, "examples": { "exampleCustomFieldsSchema": { "key": { "type": "string", "required": true, "example": "companyId" }, "type": { "type": "string", "required": true, "example": "string" }, "isRequired": { "type": "boolean", "example": true, "required": false }, "isReadOnly": { "type": "boolean", "example": false, "required": false }, "order": { "type": "number", "example": 10, "required": false }, "isHidden": { "type": "boolean", "example": false, "required": false }, "isSearchable": { "type": "boolean", "example": true, "required": false }, "defaultValue": { "type": "string", "example": 12345, "required": false }, "example": { "type": "string", "example": 12345, "required": false }, "length": { "type": "number", "example": 256, "required": false } } } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "People / Custom fields" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/customFields": { "get": { "summary": "Retrieves all custom fields configured in the system.", "description": "Fetches a list of all custom fields that extend the base user schema. These fields are configured by administrators and can be used for flexible form generation and validation.", "parameters": [], "responses": { "200": { "description": "Custom fields retrieved successfully.", "schema": { "type": "array", "items": { "key": { "type": "string", "required": true, "example": "companyId" }, "type": { "type": "string", "required": true, "example": "string" }, "isRequired": { "type": "boolean", "example": "true", "required": false }, "isReadOnly": { "type": "boolean", "example": "false", "required": false }, "order": { "type": "number", "example": 10, "required": false }, "isHidden": { "type": "boolean", "example": "false", "required": false }, "isSearchable": { "type": "boolean", "example": "true", "required": false }, "defaultValue": { "type": "string", "example": "12345", "required": false }, "example": { "type": "string", "example": "12345", "required": false }, "length": { "type": "number", "example": 256, "required": false } } }, "examples": { "exampleCustomFields": [ { "key": "companyId", "type": "string", "isRequired": false, "isReadOnly": false, "order": 0, "isHidden": false, "isSearchable": false, "defaultValue": "12345", "example": "12345", "created": "2024-04-09T07:36:51.772Z", "modified": "2024-04-09T07:36:51.772Z", "length": 256, "id": 1 } ] } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "People / Custom fields" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "Creates a new custom field.", "description": "Allows administrators to add a new custom field to the system, extending the base user schema with additional, configurable attributes.", "parameters": [ { "name": "data", "description": "request body", "schema": { "type": "object", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "example": "companyId" }, "type": { "type": "string", "example": "string" }, "isRequired": { "type": "boolean", "example": "true" }, "isReadOnly": { "type": "boolean", "example": "false" }, "order": { "type": "number", "example": 10 }, "isHidden": { "type": "boolean", "example": "false" }, "isSearchable": { "type": "boolean", "example": "true" }, "defaultValue": { "type": "string", "example": "12345" }, "example": { "type": "string", "example": "12345" }, "length": { "type": "number", "example": 256 } } }, "in": "body" } ], "responses": { "201": { "description": "Custom field created successfully.", "schema": { "type": "object", "properties": { "key": { "type": "string", "required": true, "example": "companyId" }, "type": { "type": "string", "required": true, "example": "string" }, "isRequired": { "type": "boolean", "example": "true", "required": false }, "isReadOnly": { "type": "boolean", "example": "false", "required": false }, "order": { "type": "number", "example": 10, "required": false }, "isHidden": { "type": "boolean", "example": "false", "required": false }, "isSearchable": { "type": "boolean", "example": "true", "required": false }, "defaultValue": { "type": "string", "example": "12345", "required": false }, "example": { "type": "string", "example": "12345", "required": false }, "length": { "type": "number", "example": 256, "required": false } } }, "examples": { "exampleCustomField": { "key": "companyId", "type": "string", "isRequired": false, "isReadOnly": false, "order": 0, "isHidden": false, "isSearchable": false, "defaultValue": "12345", "example": "12345", "created": "2024-04-09T07:36:51.772Z", "modified": "2024-04-09T07:36:51.772Z", "length": 256, "id": 1 } } }, "400": { "description": "Bad request. The request is missing required information or is invalid." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to create custom fields." }, "409": { "description": "Conflict. A custom field with the same key already exists." } }, "tags": [ "People / Custom fields" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/customFields/{key}": { "get": { "summary": "Retrieves a specific custom field by its key.", "description": "Fetches the details of a single custom field by its unique key. This endpoint is useful for retrieving the configuration and metadata for individual custom fields.", "parameters": [ { "name": "key", "type": "string", "required": true, "description": "The unique key of the custom field to retrieve.", "in": "path" } ], "responses": { "200": { "description": "Custom field retrieved successfully.", "schema": { "type": "object", "properties": { "key": { "type": "string", "required": true, "example": "companyId" }, "type": { "type": "string", "required": true, "example": "string" }, "isRequired": { "type": "boolean", "example": "true", "required": false }, "isReadOnly": { "type": "boolean", "example": "false", "required": false }, "order": { "type": "number", "example": 10, "required": false }, "isHidden": { "type": "boolean", "example": "false", "required": false }, "isSearchable": { "type": "boolean", "example": "true", "required": false }, "defaultValue": { "type": "string", "example": "12345", "required": false }, "example": { "type": "string", "example": "12345", "required": false }, "length": { "type": "number", "example": 256, "required": false } } }, "examples": { "exampleCustomField": { "key": "companyId", "type": "string", "isRequired": false, "isReadOnly": false, "order": 0, "isHidden": false, "isSearchable": false, "defaultValue": "12345", "example": "12345", "created": "2024-04-09T07:36:51.772Z", "modified": "2024-04-09T07:36:51.772Z", "length": 256, "id": 1 } } }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "404": { "description": "Custom field not found." } }, "tags": [ "People / Custom fields" ], "security": [ { "ApiKeyAuth": [] } ] }, "put": { "summary": "Updates an existing custom field.", "description": "Allows administrators to update the configuration and metadata of an existing custom field by its unique key.", "parameters": [ { "name": "key", "type": "string", "required": true, "description": "The unique key of the custom field to update.", "in": "path" }, { "name": "data", "description": "request body", "schema": { "type": "object", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "example": "companyId" }, "type": { "type": "string", "example": "string" }, "isRequired": { "type": "boolean", "example": "true" }, "isReadOnly": { "type": "boolean", "example": "false" }, "order": { "type": "number", "example": 10 }, "isHidden": { "type": "boolean", "example": "false" }, "isSearchable": { "type": "boolean", "example": "true" }, "defaultValue": { "type": "string", "example": "12345" }, "example": { "type": "string", "example": "12345" }, "length": { "type": "number", "example": 256 } } }, "in": "body" } ], "responses": { "200": { "description": "Custom field updated successfully.", "schema": { "type": "object", "properties": { "key": { "type": "string", "required": true, "example": "companyId" }, "type": { "type": "string", "required": true, "example": "string" }, "isRequired": { "type": "boolean", "example": "true", "required": false }, "isReadOnly": { "type": "boolean", "example": "false", "required": false }, "order": { "type": "number", "example": 10, "required": false }, "isHidden": { "type": "boolean", "example": "false", "required": false }, "isSearchable": { "type": "boolean", "example": "true", "required": false }, "defaultValue": { "type": "string", "example": "12345", "required": false }, "example": { "type": "string", "example": "12345", "required": false }, "length": { "type": "number", "example": 256, "required": false } } }, "examples": { "exampleCustomField": { "key": "companyId", "type": "string", "isRequired": false, "isReadOnly": false, "order": 0, "isHidden": false, "isSearchable": false, "defaultValue": "12345", "example": "12345", "created": "2024-04-09T07:36:51.772Z", "modified": "2024-04-09T07:36:51.772Z", "length": 256, "id": 1 } } }, "400": { "description": "Bad request. The request is missing required information or is invalid." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to update the custom field." }, "404": { "description": "Custom field not found." } }, "tags": [ "People / Custom fields" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Deletes a custom field.", "description": "Allows administrators to remove an existing custom field from the system by its unique key, effectively reducing the extensions made to the base user schema.", "parameters": [ { "name": "key", "type": "string", "required": true, "description": "The unique key of the custom field to delete.", "in": "path" } ], "responses": { "204": { "description": "Custom field deleted successfully." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to delete the custom field." }, "404": { "description": "Custom field not found." } }, "tags": [ "People / Custom fields" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/image/profile/{id}": { "get": { "summary": "Retrieves a person's profile image.", "description": "Fetches the profile image for a specified user. Requires user authentication.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The unique identifier of the user whose profile image is being requested.", "in": "path" } ], "responses": { "200": { "description": "Profile image retrieved successfully.", "content": { "image/png": { "schema": { "type": "string", "format": "binary", "description": "Binary data of the image." } }, "image/jpeg": { "schema": { "type": "string", "format": "binary", "description": "Binary data of the image." } }, "image/gif": { "schema": { "type": "string", "format": "binary", "description": "Binary data of the image." } } } }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "404": { "description": "Profile image not found." } }, "tags": [ "People / Images and media" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "Deletes a person's profile image.", "description": "Allows for the deletion of a specified user's profile image. Requires user authentication and permission to edit the profile.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The unique identifier of the user whose profile image is to be deleted.", "in": "path" } ], "responses": { "204": { "description": "Profile image deleted successfully." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to delete the profile image for this user." }, "404": { "description": "Profile image not found." } }, "tags": [ "People / Images and media" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/image/profile": { "post": { "consumes": [ "multipart/form-data" ], "summary": "Uploads a profile image for the authenticated user.", "description": "Allows an authenticated user to upload a new profile image. The image file size is limited, and the upload should be done as form data. Requires permission to edit the profile.", "parameters": [ { "name": "file", "type": "file", "required": "true", "description": "The profile image to upload.", "in": "formData" } ], "responses": { "201": { "description": "Profile image uploaded successfully." }, "400": { "description": "Invalid file format or size exceeds the limit." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "403": { "description": "Forbidden. The user does not have permission to upload a profile image for this user." } }, "tags": [ "People / Images and media" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/tags/profile/{id}": { "get": { "summary": "people tagging service - getPersonTags", "description": "people tagging service - getPersonTags", "parameters": [ { "name": "id", "type": "string", "required": true, "in": "path" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "people tagging service - createPersonTag", "description": "people tagging service - createPersonTag", "parameters": [ { "name": "id", "type": "string", "required": true, "in": "path" }, { "name": "data", "description": "request body", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true }, "name": { "type": "string", "example": "mytag" }, "category": { "type": "string", "example": "mycategory" } } }, "in": "body" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/tags/profile/{id}/{tagId}": { "delete": { "summary": "people tagging service - deletePersonTag", "description": "people tagging service - deletePersonTag", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "key", "in": "path" }, { "name": "tagId", "type": "number", "required": true, "description": "tagId", "in": "path" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/tags/profile/{id}/{tagId}/endorse": { "post": { "summary": "people tagging service - createPersonTagEndorsement", "description": "people tagging service - createPersonTagEndorsement", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "key", "in": "path" }, { "name": "tagId", "type": "number", "required": true, "description": "tagId", "in": "path" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "people tagging service - deletePersonTagEndorsement", "description": "people tagging service - deletePersonTagEndorsement", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "key", "in": "path" }, { "name": "tagId", "type": "number", "required": true, "description": "tagId", "in": "path" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/tags/typeahead/{search}": { "get": { "summary": "people tagging service - getTagsTypeahead", "description": "people tagging service - getTagsTypeahead", "parameters": [ { "name": "search", "type": "string", "required": true, "in": "path" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/tags/popular": { "get": { "summary": "people tagging service - get 15 most popular tags", "description": "people tagging service - get 15 most popular tags", "parameters": [], "responses": { "200": { "description": "success" } }, "tags": [ "People / Tags" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/search": { "get": { "summary": "Searches for people based on a query.", "description": "Performs a search across people profiles based on the provided query string. Supports pagination and case sensitivity options, allowing for flexible search configurations.", "parameters": [ { "name": "q", "type": "string", "required": false, "default": "", "description": "Search term. The query to match against people profiles.", "in": "query" }, { "name": "ps", "type": "integer", "required": false, "default": 20, "description": "Page size. The number of results to return per page.", "in": "query" }, { "name": "page", "type": "integer", "required": false, "default": 1, "description": "Page number. Specifies the page of results to return.", "in": "query" }, { "name": "cs", "type": "boolean", "required": false, "default": true, "description": "Case sensitivity flag. When true, the search is case-sensitive.", "in": "query" } ], "responses": { "200": { "description": "Search successful. Returns matched profiles." }, "400": { "description": "Invalid request parameters." }, "500": { "description": "Internal server error." } }, "tags": [ "People / Search" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/people/{id}/privacy/data": { "get": { "summary": "Get privacy data for a specific person.", "description": "Retrieves the privacy data for a specific person based on the provided person ID. This includes the PII data, authored content, relationships and other privacy-sensitive information.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the person to retrieve", "in": "path" }, { "name": "scope", "type": "string", "required": false, "description": "Defines the scope of data: profile, content, references, relationships, or full", "in": "query" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Privacy" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/people/{id}/privacy/anonymize": { "post": { "summary": "Anonymize a specific person.", "description": "Anonymizes a specific person based on the provided person ID. This includes the PII data, authored content, relationships and other privacy-sensitive information.", "parameters": [ { "name": "id", "type": "string", "required": true, "description": "The ID of the person to anonymize", "in": "path" } ], "responses": { "200": { "description": "success" } }, "tags": [ "People / Privacy" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/user-directories": { "get": { "summary": "Retrieves all available and configured user directories.", "description": "Fetches a list of all user directories configured in the system. Each directory is detailed with its type, operational status, and other relevant metadata.\n This endpoint is useful for administrative purposes, helping to understand and manage the integration of different user directory services.", "parameters": [], "responses": { "200": { "description": "Successfully retrieved the list of user directories.", "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the user directory." }, "name": { "type": "string", "description": "The name of the user directory." }, "status": { "type": "string", "description": "The operational status of the user directory." }, "description": { "type": "string", "description": "A brief description of the user directory." }, "url": { "type": "string", "description": "The connection URL to the user directory." }, "averageResponseTime": { "type": "number", "description": "The average response time of queries to the user directory, measured in milliseconds." } }, "example": { "type": "LDAP", "name": "LDAP", "status": "active", "description": "LDAP user directory", "url": "ldap://localhost:389", "averageResponseTime": 0 } } } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "Federation / User directories" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/user-directories/users": { "get": { "summary": "Retrieves users from all connected user directories.", "description": "Fetches all user profiles from configured user directories and consolidates the information to provide detailed profiles.\n This endpoint is useful for obtaining a unified view of users across different directory services, including LDAP and custom data sources.", "parameters": [], "responses": { "200": { "description": "Successfully retrieved and consolidated user profiles from all directories.", "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } } }, "examples": { "usersFromDirectoriesExample": [ { "id": 1, "guid": "admin", "email": "admin@test.com", "organization": "company", "displayName": "Admin User", "firstName": "Admin", "lastName": "User", "phone": "+1234567890", "streetAddress": "Downtown", "city": "New York", "state": "NY", "zipCode": "10001", "country": "USA", "timeZone": "America/New_York", "language": "English", "role": "Technical Admin", "userState": "active", "created": "2024-04-08T09:57:00.052Z", "modified": "2024-04-08T09:57:00.052Z", "professionalSummary": "I am a technical admin.", "profilePhoto": "https://example.com/profile.jpg", "customFields": {} } ] } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "Federation / User directories" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/user-directories/users/{guid}": { "get": { "summary": "Retrieves and consolidates the profile of a single user from all user directories.", "description": "Fetches detailed profile information for a specific user, identified by their GUID, from all configured user directories, including LDAP, Active Directory, and custom data sources.\n The consolidated profile provides a comprehensive view of the user's details as aggregated across these directories.", "parameters": [ { "name": "guid", "type": "string", "required": true, "in": "path" } ], "responses": { "200": { "description": "Successfully retrieved and consolidated the user profile from all directories.", "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "isHidden": true, "isGenerated": true, "isConstant": true, "required": false, "writeable": false, "isReadOnly": true, "allowEmpty": false }, "guid": { "type": "string", "required": true, "example": "jdoe", "isConstant": true, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false }, "email": { "type": "string", "required": true, "example": "john.doe@testdomain.com", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "organization": { "type": "string", "required": true, "example": "Acme Corporation", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "displayName": { "type": "string", "required": true, "example": "John Doe", "length": 256, "writeable": false, "isReadOnly": true, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "firstName": { "type": "string", "allowEmpty": true, "example": "John", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "lastName": { "type": "string", "allowEmpty": true, "example": "Doe", "length": 256, "required": false, "writeable": false, "isReadOnly": true, "isHidden": false, "isGenerated": false, "isConstant": false }, "phone": { "type": "string", "allowEmpty": true, "example": "+1 626 902 8073", "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "streetAddress": { "type": "string", "allowEmpty": true, "example": "456 Fictional Lane", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "city": { "type": "string", "allowEmpty": true, "example": "Sampleville", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "state": { "type": "string", "allowEmpty": true, "example": "DemoState", "length": 256, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "zipCode": { "type": "string", "allowEmpty": true, "example": "54321", "length": 12, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "country": { "type": "string", "required": true, "example": "America/New_York", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "timeZone": { "type": "string", "required": true, "example": "USA", "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "language": { "type": "string", "example": "English", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "role": { "type": "string", "required": true, "example": "Chief Example Officer", "length": 256, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "userState": { "type": "string", "example": "active", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "created": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "modified": { "type": "date", "example": "2020-01-01T00:00:00.000Z", "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isConstant": false }, "professionalSummary": { "type": "richtext", "example": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "profilePhoto": { "type": "string", "example": "https://www.gravatar.com/a", "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false }, "customFields": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "companyId": "12345" }, "allowEmpty": true, "required": false, "writeable": true, "isReadOnly": false, "isHidden": false, "isGenerated": false, "isConstant": false }, "dataSource": { "type": "string", "example": "LDAP", "isHidden": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isGenerated": false, "isConstant": false }, "isAnonymized": { "type": "boolean", "example": false, "isHidden": true, "isGenerated": true, "required": false, "writeable": true, "isReadOnly": false, "allowEmpty": false, "isConstant": false } } }, "examples": { "userFromDirectoriesExample": { "id": 1, "guid": "jdoe", "email": "john.doe@testdomain.com", "organization": "Acme Corporation", "displayName": "John Doe", "firstName": "John", "lastName": "Doe", "phone": "+1 626 902 8073", "streetAddress": "456 Fictional Lane", "city": "Sampleville", "state": "DemoState", "zipCode": "54321", "country": "America/New_York", "timeZone": "USA", "language": "English", "role": "Chief Example Officer", "userState": "active", "created": "2020-01-01T00:00:00.000Z", "modified": "2020-01-01T00:00:00.000Z", "professionalSummary": "A skilled professional known for pioneering innovative solutions in diverse scenarios.", "profilePhoto": "https://www.gravatar.com/a", "customFields": {} } } }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized. The request is missing a valid session." }, "404": { "description": "Person not found." } }, "tags": [ "Federation / User directories" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/user-directories/sync": { "post": { "summary": "Manually triggers synchronization of users from directories.", "description": "Initiates a manual synchronization process for all users across configured user directories, comparing them with locally stored versions and updating as necessary.\n This operation can create, update, or clean up user profiles based on the comparison and may relay updates to other services or systems.\n Note: This endpoint is intended for ad-hoc manual synchronization or testing purposes and executes on a scheduled configuration at the service level.\n Due to its intensive resource usage, it should be used with caution.", "parameters": [], "responses": { "200": { "description": "Synchronization process completed successfully.", "schema": { "type": "object", "properties": { "processed": { "type": "integer", "description": "Total number of user profiles processed during synchronization." }, "created": { "type": "integer", "description": "Number of user profiles created." }, "updated": { "type": "integer", "description": "Number of user profiles updated." }, "skipped": { "type": "integer", "description": "Number of user profiles skipped." }, "errors": { "type": "array", "items": { "type": "string" }, "description": "List of errors encountered during the synchronization process, if any." }, "startedAt": { "type": "string", "format": "date-time", "description": "Timestamp marking the start of the synchronization process." }, "finishedAt": { "type": "string", "format": "date-time", "description": "Timestamp marking the end of the synchronization process." }, "timeLapsed": { "type": "integer", "description": "Total time taken for the synchronization process, in milliseconds." } }, "example": { "processed": 542, "created": 32, "updated": 114, "skipped": 396, "errors": [], "startedAt": "2024-04-09T20:38:05.990Z", "finishedAt": "2024-04-09T20:38:06.625Z", "timeLapsed": 735 } } }, "401": { "description": "Unauthorized. The user is not authenticated or lacks admin privileges." }, "403": { "description": "Forbidden. The user does not have permission to create a new user profile." } }, "tags": [ "Federation / User directories" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/config": { "get": { "summary": "Retrieves application configuration settings.", "description": "Provides details on configuration properties from the backend relevant to the frontend, including integration modes and authentication mechanisms.", "parameters": [], "responses": { "200": { "description": "Configuration retrieval successful.", "schema": { "type": "object", "properties": { "key": { "type": "string" } } }, "examples": { "exampleConfig": { "key": "exampleValue" } } } }, "tags": [ "Utils" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/nls": { "get": { "summary": "Retrieves custom NLS data in the user's preferred language.", "description": "Fetches customized NLS (Natural Language Support) JSON files from the backend. These files are intended to be merged with static translations on the client side, \n allowing for the customization and overriding of translation strings as needed.\n The service automatically detects the user's preferred language or accepts a language parameter to specify the desired language.", "parameters": [], "responses": { "200": { "description": "NLS retrieval successful.", "schema": { "type": "object", "properties": { "^[a-z]{2}$": { "type": "object", "additionalProperties": { "type": "string" } } } }, "examples": { "exampleNls": { "en": { "companyId": "Company ID" } } } }, "500": { "description": "Internal server error. The server encountered errors while attempting to retrieve the NLS data." } }, "tags": [ "Utils" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/errors/{errorCode}": { "get": { "summary": "Retrieves detailed error data related to the error code.", "description": "This endpoint is used to retrieve detailed error data related to the error code. \n The endpoint is referenced within error responses for other API endpoints to provide more information about the error.\n This endpoint provides a JSON based response and can thus be used for programmatic error handling, but can also provide plain text error messages for human readability and usage in UI.", "parameters": [ { "name": "errorCode", "type": "string", "required": true, "description": "The error code to retrieve detailed error data for.", "in": "path" }, { "name": "format", "type": "string", "description": "The format of the response. Can be either \"json\" or \"text\". Default is \"json\".", "in": "query" } ], "responses": { "200": { "description": "Error retrieval successful.", "schema": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "number" }, "detail": { "type": "string" }, "reason": { "type": "string" }, "errorCode": { "type": "string" }, "description": { "type": "string" }, "context": { "type": "object" } } }, "examples": { "exampleError": { "type": "http://localhost:3000/people/api/v1/errors/http.bad.request", "status": 400, "detail": "The request was invalid or cannot be served. Check the request format and parameters.", "reason": "Bad Request", "errorCode": "http.bad.request", "instance": "", "description": "This error typically occurs when the request does not meet the API specifications or includes invalid parameters, such as incorrect syntax, missing required fields, or incompatible data types. Verify that all parameters are correct and that the request structure adheres to the expected format as outlined in the API documentation. Reformat the request as needed and resubmit." } } }, "401": { "description": "Unauthorized. The request is missing a valid session." } }, "tags": [ "Utils" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/probes/ping": { "get": { "summary": "Checks if the service is responsive.", "description": "A simple ping operation that checks the service's responsiveness. It is expected to return a success status if the service is running.", "parameters": [], "responses": { "200": { "description": "Service is responsive and running." }, "500": { "description": "Server error or service is not responsive." } }, "tags": [ "Probes" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/probes/ready": { "get": { "summary": "Checks if the service is ready to accept requests.", "description": "Determines if the service has completed its initialization and is ready to accept traffic. Useful for deployment scenarios to ensure traffic is only routed to ready instances.", "parameters": [], "responses": { "200": { "description": "Service is ready and able to accept requests." }, "500": { "description": "Service is not ready or has encountered an initialization error." } }, "tags": [ "Probes" ], "security": [ { "ApiKeyAuth": [] } ] } }, "/people/api/v1/probes/health": { "get": { "summary": "Checks the liveness/health of the service.", "description": "Assesses the health of the service, ensuring it is in a healthy state to process requests.\n It can trigger auto-recovery actions like restarts in deployment environments if the service is found to be unhealthy.", "parameters": [], "responses": { "200": { "description": "Service is alive and healthy." }, "500": { "description": "Service is unhealthy or has encountered a problem affecting its operations." } }, "tags": [ "Probes" ], "security": [ { "ApiKeyAuth": [] } ] } } }, "responses": {}, "definitions": {}, "tags": [], "swagger": "2.0", "securityDefinitions": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization" } } }