SDK Migration: Encompass SDK to REST APIs

This section is for migrating Encompass SDK to Developer Connect REST APIs for External Users.

Managing External Users

For any external system (Third party originators) that is designed to support lenders who work with External Organizations/TPO Organizations, these REST interfaces provide a seamless integration for managing the contacts/users of these external organizations. Thus allowing these users to be able to manage loans.

Just as all communications with SDK, all External user API operations pass through the External user Object. In our REST APIs, our External user object is a resource available at this endpoint: /encompass/v3/externalUsers/. The standard REST methods around this endpoint provides options to Create, Update and Delete an External user.

Retrieving an External User (GET)

As with the current SDK, External users are retrieved with a userId which is considered as a unique identifier for an External User. An External user retrieval allows a client (or) client application to view the contents of an existing External User. either orgid or tpoid can be passed on query parameter to retreive users.

Things to Note:

• Retrieve External user is a GET method call and hence wouldn't require any request body
• A resource id, in this case, a valid userId or tpoid is a required parameter sent as part of the URL
• A Session object is not required for a REST API call. A Session is automatically created within the context of a REST API access token
• Orgid and Tpoid can not be passed together
• Logged in user need to have access to get external user

Resources:

• Example Request and Response Payload: Postman Collection

• API Reference: Get External User

• Endpoints:

        GET   /v3/externalUsers/{userId} 
        GET   /v3/externalUsers?orgid={orgid}
  

Query Parameters

Creating an External User (PATCH)

The new REST API allows client applications to create new External Users. And enable these created users to login to TPO Connect portal and manage loans. Create External user is a PATCH method call requiring a External users object (json) as input. This API is plural and supports creating multiple users (Note: For the 22.1 release, this API is certified for only single external user).

Things to Note:

• Unlike the current SDK call, a commit() method is not required to create the External user with the new REST API.
• updatedBy and updatedDate are not allowed to be passed as request parameters for the new REST API.
• Any user with access rights to create External user can create the External user with the new REST API.
• Unlike in SKD method, if user parent info attribute is set as true and the user passes the related attributes in the request payload, the API will fail indicating that the user cannot pass these attributes when the useParentInfo is set as true.
• If the ORG is defined with one site URL and if we create any external user, the site URL will not be inherited unless the parameter is explicitly supplied in the request payload.
• Unlike smart client or SDK call, the API will not create the external user under root org if the ORG ID is missing in the request. If ORG ID is missing in the request, the API will fail.
• It is important to configure Encompass server with Hazelcast Cache. Without which the API may fail due to data mismatch between the cache and the database.
• Unlike SDK method, License status can't be a free text. Hence the API will fail if the License status is not one of the valid value.
• If the supplied URL or Persona or SalesRep user or State license is invalid or any temporary issue with DB connection during the transaction, the external user POST API will fail unlike the Smart client where the error is thrown but the user is created in the system.
• A new attribute 'licenseStatusType' introduces in the API contract which will accept ENUM values for license status.
• API query parameter action will assume default value as update. Hence for Create functionality, the action parameter must be passed with value as add.

Resources:

• Example Request and Response Payload: Postman Collection

• API Reference: Manage External Users

• Endpoint:

        PATCH    /v3/externalUsers?orgid={oid}&action=add&View=entity
  

Query Parameters

[
  {
    "useCompanyAddress": true,
    "firstName": "string",
    "middleName": "string",
    "lastName": "string",
    "suffix": "string",
    "title": "string",
    "address": "string",
    "city": "string",
    "state": "AL",
    "zipCode": "string",
    "phone": "string",
    "cellPhone": "string",
    "fax": "string",
    "email": "string",
    "nmlsId": "string",
    "nmlsCurrent": true,
    "ssn": "string",
    "useParentInfoForRateLock": true,
    "emailForRateSheet": "string",
    "faxForRateSheet": "string",
    "emailForLockInfo": "string",
    "faxForLockInfo": "string",
    "emailForLogin": "string",
    "siteUrls": [
      "string"
    ],
    "salesRep": {
      "entityId": "string",
      "entityName": "string",
      "entityUri": "string",
      "entityType": "Default"
    },
    "personas": [
      {
        "entityId": "string",
        "entityName": "string",
        "entityUri": "string",
        "entityType": "Default"
      }
    ],
    "peerLoanAccess": "Disabled",
    "accessMode": "ReadWrite",
    "licenses": [
      {
        "selected": true,
        "stateAbbrevation": "AL",
        "licenseNumber": "string",
        "issueDate": "2021-12-14T22:58:29.628Z",
        "startDate": "2021-12-14T22:58:29.628Z",
        "endDate": "2021-12-14T22:58:29.628Z",
        "licenseStatusType": "TransitionRequested",
        "statusDate": "2021-12-14T22:58:29.628Z",
        "lastChecked": "2021-12-14T22:58:29.628Z"
      }
    ],
    "notes": "string",
    }
  }
]

SDK Methods That Are Replaced by This API:

• CreateUser(String, String, String, String, ExternalUrlList)
• CreateUser(String, String, String, String, ExternalUrlList, ExternalUser)
• CreateUser(String, String, String, String, ExternalUrlList, User)

Updating an External User (PATCH)

A external user is updated with a userId which is considered as a unique identifier for an External User. Current API support deleting a single user at a time.

Things to Note:

• Update External user is a PATCH method call supporting to update multiple external users in a single API call.
• Maximum number of records supported is 100.
• API query parameter action will assume default value as update.
• Any user with access rights will be able to update external users.
• If skip persona check is enabled, the user will be assumed to have all access rights.
• If any read only attributes are passed in the request payload, the API will throw error as bad request.
• For Personas and URLs, whatever the data that is being passed in the request will always override on the external user. Hence Even if you want to add one persona, or remove one persona, you must pass entire array of personas.
• For updating licenses, if you want to remove any license, set the value for field licenses.selected as false.
• For updating licenses, if you want to add only one new license, just pass only one record in licenses object in request payload.

Resources:

• API Reference: Manage External Users

• Endpoint:

       PATCH  /v3/externalUsers?orgid={oid}&action=delete
  

Deleting an External User (PATCH)

A external user is deleted with a userId which is considered as a unique identifier for an External User. Current API support deleting a single user at a time.

Things to Note:

• Delete External user is a PATCH method call
• Logged in user must have access to delete external user
• API query parameter action will assume default value as update. Hence for Delete functionality, the action parameter must be passed with value as delete.

Resources:

• Example Request and response payload: Postman Collection

• API Reference: Manage External Usersv3-contracts-externalusers

• Endpoint:

      PATCH   /v3/externalUsers?orgid={oid}&action=delete 
  

Query Parameters

[
  {
    "id": "6990131318"
  },
  {
    "id": "6990131319"
  }
]