Encompass User Management API Guide

Auth method: OAuth 2.0 (client credentials and authorization code flows)

Setup steps

1. Register an application in the Encompass Developer Connect portal (developer.icemortgage.com).
2. Obtain a Client ID and Client Secret for your registered application.
3. Request an access token via POST to https://api.elliemae.com/oauth2/v1/token using client_credentials grant (for server-to-server) or authorization_code grant (for user-delegated access).
4. Include the Bearer token in the Authorization header for all API requests.
5. Ensure the Encompass instance has API access enabled by the administrator.

Required scopes

List Users

• Method: GET
• URL: https://api.elliemae.com/encompass/v3/users
• Watch out for: Returns only users visible to the authenticated user's organizational scope. Use start/limit for pagination.

Request example

GET /encompass/v3/users?start=0&limit=25
Authorization: Bearer {access_token}

Response example

[
  {
    "id": "user123",
    "loginId": "jdoe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "jdoe@example.com",
    "enabled": true
  }
]

Get User

• Method: GET
• URL: https://api.elliemae.com/encompass/v3/users/{userId}
• Watch out for: Use the Encompass internal user ID (not loginId) as the path parameter.

Request example

GET /encompass/v3/users/user123
Authorization: Bearer {access_token}

Response example

{
  "id": "user123",
  "loginId": "jdoe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@example.com",
  "organizationId": "org456",
  "enabled": true
}

Create User

• Method: POST
• URL: https://api.elliemae.com/encompass/v3/users
• Watch out for: Password must meet Encompass complexity requirements. organizationId must reference a valid org node.

Request example

POST /encompass/v3/users
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "loginId": "jsmith",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jsmith@example.com",
  "password": "TempPass123!",
  "organizationId": "org456"
}

Response example

{
  "id": "user789",
  "loginId": "jsmith",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jsmith@example.com",
  "enabled": true
}

Update User (partial)

• Method: PATCH
• URL: https://api.elliemae.com/encompass/v3/users/{userId}
• Watch out for: Only include fields to be changed. loginId changes may have downstream impacts on loan assignments.

Request example

PATCH /encompass/v3/users/user789
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "email": "jsmith_new@example.com",
  "title": "Senior Loan Officer"
}

Response example

{
  "id": "user789",
  "email": "jsmith_new@example.com",
  "title": "Senior Loan Officer"
}

Delete User

• Method: DELETE
• URL: https://api.elliemae.com/encompass/v3/users/{userId}
• Watch out for: Deleting a user with active loan assignments may fail or require reassignment first. Consider disabling (enabled: false) instead.

Request example

DELETE /encompass/v3/users/user789
Authorization: Bearer {access_token}

Response example

HTTP 204 No Content

Get User Personas

• Method: GET
• URL: https://api.elliemae.com/encompass/v3/users/{userId}/personas
• Watch out for: Personas control feature-level access; incorrect persona assignment can expose or restrict critical loan functions.

Request example

GET /encompass/v3/users/user123/personas
Authorization: Bearer {access_token}

Response example

[
  { "id": "persona001", "name": "Loan Officer" },
  { "id": "persona002", "name": "Processor" }
]

List Personas (system-wide)

• Method: GET
• URL: https://api.elliemae.com/encompass/v3/personas
• Watch out for: Use this endpoint to resolve valid persona IDs before assigning them to users.

Request example

GET /encompass/v3/personas
Authorization: Bearer {access_token}

Response example

[
  { "id": "persona001", "name": "Loan Officer" },
  { "id": "persona003", "name": "Admin" }
]

Get Current User (token introspection)

• Method: GET
• URL: https://api.elliemae.com/encompass/v3/users/me
• Watch out for: Returns the user associated with the current access token. Not available for client_credentials tokens with no user context.

Request example

GET /encompass/v3/users/me
Authorization: Bearer {access_token}

Response example

{
  "id": "user123",
  "loginId": "jdoe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "jdoe@example.com"
}

• Rate limits: ICE Mortgage Technology enforces rate limits on Encompass Developer Connect APIs, but specific numeric limits are not publicly documented in official sources.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: Official documentation does not publicly specify per-plan rate limit values or rate-limit response headers. Contact ICE Mortgage Technology support for current limits applicable to your subscription.

• Pagination method: offset

• Default page size: 25

• Max page size: 200

• Pagination pointer: start / limit

• Webhooks available: Yes

• Webhook notes: Encompass Developer Connect supports webhooks (called 'Encompass Webhooks') for event-driven notifications on loan and system events.

• Alternative event strategy: User lifecycle events (create/update/delete) are not explicitly listed as webhook event types in publicly available documentation. Polling the Users API is the documented alternative for user change detection.

• Webhook events: loan.created, loan.updated, loan.deleted, loan.locked, loan.unlocked

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.elliemae.com/encompass/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, GET /ServiceProviderConfig, GET /Schemas

Limitations:

• Requires Enterprise subscription tier.
• SCIM provisioning configuration must be completed by an Encompass administrator.
• Group management via SCIM maps to Encompass organizational units; full parity with native org hierarchy is not guaranteed.
• Specific IdP connector documentation (Okta, Entra ID) is not publicly listed as officially supported in current help center docs.
• SCIM endpoint base URL should be confirmed with ICE Mortgage Technology support as it may be instance-specific.

Three workflows cover the main Encompass identity lifecycle tasks.

Provisioning a new loan officer usually requires this sequence:

• Obtain a Bearer token with the required admin scope.
• Resolve the target persona ID.
• Resolve the target organizationId.
• Create the user with login, identity, org, and persona fields.

For offboarding, prefer disabling over hard deletion:

• Resolve the internal userId first.
• PATCH the user with enabled set to false.
• Reassign active loan work before attempting any irreversible cleanup.

SCIM 2.0 can support IdP-driven provisioning on Enterprise, but instance-specific mapping still matters.

Treat personas and organizationId as first-class identity attributes when reconciling Encompass against the rest of the SaaS stack.

Provision a new loan officer

1. Authenticate via OAuth 2.0 client_credentials to obtain a Bearer token with encompass_admin scope.
2. GET /encompass/v3/personas to retrieve the ID for the 'Loan Officer' persona.
3. GET /encompass/v3/organizations (or equivalent) to retrieve the target organizationId.
4. POST /encompass/v3/users with loginId, firstName, lastName, email, password, organizationId, and personas array.
5. Verify creation by GET /encompass/v3/users/{newUserId}.

Watch out for: Password must meet Encompass complexity policy. Persona and organization IDs must be valid for the specific Encompass instance.

Deactivate a departing employee

1. Authenticate and obtain a Bearer token.
2. GET /encompass/v3/users?loginId={loginId} to resolve the internal user ID.
3. PATCH /encompass/v3/users/{userId} with body {"enabled": false} to deactivate the account.
4. Confirm deactivation via GET /encompass/v3/users/{userId} and verify enabled=false.

Watch out for: Prefer deactivation over deletion to preserve audit trail and avoid breaking loan record associations.

Sync users via SCIM from an Identity Provider

1. Confirm Enterprise subscription with ICE Mortgage Technology.
2. Obtain SCIM endpoint URL and Bearer token credentials from Encompass administrator.
3. Configure the IdP (e.g., Okta, Entra ID) SCIM connector with the Encompass SCIM base URL and token.
4. Map IdP user attributes to SCIM standard attributes (userName → loginId, etc.).
5. Perform a test provisioning of a single user and validate via GET /encompass/scim/v2/Users.
6. Enable automated provisioning and deprovisioning rules in the IdP.

Watch out for: SCIM endpoint URL may be instance-specific. Attribute mapping between IdP schema and Encompass SCIM schema requires careful validation, especially for mortgage-specific fields like nmlsOriginatorId which may not be in the standard SCIM schema.

Several API behaviors are non-obvious and will cause silent failures if not accounted for in integration design. client_credentials tokens have no user context; GET /encompass/v3/users/me will not function with them.

Scope requirements differ by endpoint - validate that your token carries encompass_admin before attempting write operations, not after receiving a 403. Persona IDs must be fetched from /personas at runtime per environment; they are not stable across Encompass instances and cannot be assumed from documentation or prior deployments.

Webhook support exists for loan lifecycle events (loan.created, loan.updated, etc.), but user lifecycle events - create, update, deactivate - are not listed as supported webhook event types in current public documentation. Polling GET /encompass/v3/users with start/limit pagination is the documented approach for detecting user changes. API versioning is path-based (v3);

v1 and v2 endpoints may still respond but are deprecated and should not be used in new integrations.