Identity methods

createUsers(User[] users, Org org)

Adds new users to the supplied organization.

Input

• users: all required attributes
• org : internalId or (externalId, parent, type)

Response

User[] (D)

Availability

Engage 7.3.3

Errors returned

• ARG_INVALID_CHAR – Invalid Data, argument '%s' contains invalid characters
• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• This method may successfully create some of the supplied users and fail to create others. In this case the failures will be returned as warnings (one per failure).
• The maximum number of items that may be supplied using this method is 1,000.
• All users will automatically be created with passwordChangeRequired equal to true.
• Required fields:
  • externalId must be either a phone number or a valid email address
  • firstName, lastName and role are mandatory

createUsersUsingString(String users, Org org)

Adds new users to the supplied organization.

Input

• users: all required attributes (see Notes)
• org : internalId or (externalId, parent, type)

Response

User[] (D)

Availability

Engage 8.10

Errors returned

• ARG_INVALID_CHAR – Invalid Data, argument '%s' contains invalid characters
• ARG_INVALID_DATA – Invalid Data '%s
• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_EXISTS – Object '%s' already exists
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• SYSTEM_LIMIT_EXCEEDED – maximum number of users exceeded

Notes

• This method may successfully create some of the supplied users and fail to create others. In this case the failures will be returned as warnings (one per failure).
• The user string must be formatted as per the specification in the Appendix.
• The maximum length (in bytes) supported for the users string is 100,000.
• The maximum number of users active is 1,000.
• All users will automatically be created with passwordChangeRequired equal to true.
• Required fields:
  • externalId must be either a phone number or a valid email address
  • firstName, lastName and role is mandatory

deleteUsers(User[] users)

Deletes supplied users.

Input

users : externalId

Response

NONE

Availability

Engage 7.3.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ARG_TOO_LARGE – Invalid Data, argument '%s' exceeds allowed size
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

• This method may successfully delete some of the supplied users and fail to delete others. In this case the failures will be returned as warnings (one per failure).
• The maximum number of items that may be supplied using this method is 1,000.

showUser(User user)

Retrieves information about the supplied user.

Input

user : externalId

Response

User (D): Complete User object.

Availability

Engage 7.3.3

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

listUsers(Org org, User sample)

Lists all users in the supplied organization that match the supplied sample User.

Input

• org: internalId or (externalId, parent, type)
• sample: optional list of user attributes to narrow the returned set

Response

User[] (D)

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• RESULT_TOO_LARGE – Result returned would be too large

Notes

• If sample is null – all users within Org will be returned.
• If sample is non-null all attributes must match.
• The maximum number of items returned using this method is 1,000.

changeUser(User user)

Updates fields/attributes of the supplied User.

Input

user : externalId + any fields to be changed

Response

user (D): Updated object

Availability

Future

Errors returned

• ARG_INVALID_CHAR – Invalid Data, argument '%s' contains invalid characters
• ARG_INVALID_DATA – Invalid Data '%s
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

To change a user's password use changePassword().

changePassword(User user, string currentPassword, string newPassword)

Change password of the identified user.

Input

• user : externalId
• currentPassword: current password of logged in user
• newPassword: valid password to update user's password given enterprise security settings

Response

NONE

Availability

Engage 7.3.3

Errors returned

• INVALID_PASSWORD – Invalid Password
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

The current password is not necessarily that of the user; it is commonly the individual currently authorized to change this password.

resetPassword(User user, string newPassword)

Resets password of the identified user.

Input

• user: externalId
• newPassword: valid password to update user's password given enterprise security settings

Response

NONE

Availability

Engage 11.8

Errors returned

• INVALID_PASSWORD – Invalid Password
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

addToOrg(Org org, User user)

Adds existing user to supplied organization.

Input

• org: internalId or (externalId, parent, type)
• user: externalId

Response

NONE

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

moveUsersToOrg(User[] users, Org oldOrg, Org newOrg)

Moves an existing set of users from one organization to another organization.

Input

• users : externalId
• oldOrg : internalId or (externalId, parent, type)
• newOrg : internalId or (externalId, parent, type)

Response

NONE

Availability

Future

Errors returned

• ARG_INVALID_TYPE – Argument is of invalid type '%s'
• ARG_NULL – Invalid Data, argument '%s' must be non-null
• NOT_SUPPORTED – This Operation is not supported
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

removeUsersFromOrg(User[] users, Org org)

Removes users from supplied organization. User must belong to at least one organization.

Input

• user : externalId
• org : internalId or (externalId, parent, type)

Response

NONE

Availability

Future

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

createContactPointValidation(ContactPointValidation contactPointValidation)

Initiates contact point validation request for given user.

Input

contactPointValidation: user's externalId

Response

NONE

Availability

Engage 11.9

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL- Null attributes are provided
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

This API initiates the user's contact point validation process. The API supports only email validation. After successful execution the API sends the user an email that contains a URL for validating the email address.

changeContactPointValidation(ContactPointValidation contactPointValidation)

Processes the contact point validation request for the given user.

Input

contactPointValidation: attribute url

Response

ContactPointValidation[] (D)

Availability

Engage 11.9

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL- Null attributes are provided
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist
• URL_EXPIRED- if URL is expired.

Notes

This API processes the user's contact point validation. The API supports only email validation. The API validates:

• If input URL is not tempered by validating MAC against given input parameters in the URL.
• If URL is expired.
• That low authority users (non-SYSOPS, ADMIN, WSDL) can work from their userId only.

createPasswordResetRequest(PasswordResetRequest passwordResetRequest)

Initiates password reset request for the given user.

Input

passwordResetRequest: user's externalId

Response

PasswordResetRequest[] (D)

Availability

Engage 11.9

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL- Null attributes are provided
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

This API initiates the user's password reset request process. The API:

• Checks if the user has the password reset preference enabled.
• Checks if the user's email address is valid.
• Generates a secure URL and sends the user an email that contains a URL for resetting their password.

changePasswordResetRequest(PasswordResetRequest passwordReestRequest)

Progresses password reset request for given user.

Input

passwordResetRequest: attribute url

Response

PasswordResetRequest[] (D)

Availability

Engage 11.9

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL- Null attributes are provided
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

This API initiates user's password reset request process. The API:

• Checks if input URL is not tempered by validating MAC against given input params in URL
• Checks if the URL is expired
• Verifies that low authority users (non-SYSOPS, ADMIN, WSDL) can work from their userId only.
• Validates that the user has not exceeded failed attempts and is not in a lockout period.
• Validates input security questions against answers stored in the database.

showPasswordResetRequest(PasswordResetRequest passwordReestRequest)

Returns password reset request for given user.

Input

passwordResetRequest: attribute url

Response

PasswordResetRequest[] (D)

Availability

Engage 11.9

Errors returned

• ARG_NULL – Invalid Data, argument '%s' must be non-null
• ATTRIBUTE_NULL- Null attributes are provided
• OBJECT_NOT_EXISTS – Referenced object '%s' does not exist

Notes

This API initiates the user's password reset request process. The API:

• Checks if input URL is not tempered by validating MAC against given input params in URL
• Checks if the URL is expired
• Verifies that low authority users (non-SYSOPS, ADMIN, WSDL) can work from their userId only.
• Validates that the user has not exceeded failed attempts and is not in a lockout period.
• Validates input security questions against answers stored in the database.