Encompass SDK: get started

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Install

npm install @alter-ai/sdk @alter-ai/encompass
# Python (installs core automatically)
pip install alter-sdk-encompass

The provider package includes only Encompass types and response schemas and pins its contract version.

Connect and call

Connect Encompass in one of three ways, and retain the grant ID:

• OAuth: an Encompass user signs in. The token ends after 24 hours at most and the user reconnects.
• ISV partner: a partner’s API key for one lender instance.
• API user: a lender’s own API key and a dedicated Encompass user.

All three reach the same API through this package, and the Encompass user’s persona decides what a call may do. Alter supplies the credential; it never belongs in operation input.

import { App } from "@alter-ai/sdk";
import { EncompassIntegration } from "@alter-ai/encompass";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const client = new EncompassIntegration(app, { grantId: process.env.ENCOMPASS_GRANT_ID! });
  const result = await (await client.loanMetadata.v1GetLoanMetadata({
    path: { loanId: process.env.ENCOMPASS_LOAN_ID! },
  })).wait();
  console.log(result.bodyJson());
} finally {
  await app.close();
}

from alter_sdk import App
from alter_sdk_encompass import EncompassIntegration

async def first_call(api_key: str, grant_id: str, loan_id: str):
    async with App(api_key=api_key) as app:
        client = EncompassIntegration(app, {"grant_id": grant_id})
        call = await client.loan_metadata.v1_get_loan_metadata({"path": {"loanId": loan_id}})
        result = await call.wait()
        return result.body_json()

Complete versioned contract

Contract 2026-10-31 contains 541 Encompass Developer Connect operations. Field names, types and policy identities are in the package’s types, in the Developer Portal provider view, and in alter integrations operations encompass --version 2026-10-31. Each operation is summarized by its name and method; ICE’s Developer Connect documentation describes what its fields mean.

Generated calls pin the Alter contract version. Encompass’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

alter integrations execute encompass encompass.v1_get_loan_metadata \
  --version 2026-10-31 --grant "$ENCOMPASS_GRANT_ID" \
  --input '{"path":{"loanId":"LOAN_ID"}}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way the provider’s document declares them: one delimited value where it declares explode: false (or a pipe- or space-delimited style), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

Approvals

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

Loan files

loanManagement.importerToUpdateLoan, and the other two importers, take a whole loan file. Pass body: { format, content }: format is mismo34, or fnma32 or fnma30 for the Fannie Mae import, and content is the file’s text, which is masked for approvers. Alter sends the text under the media type Encompass expects. The shared proxy limit of 5 MiB applies. Under an approval rule, a raw request carrying the file as XML or text is refused because its fields cannot be masked; use these operations instead. Attachment, letter template and trade document bytes go to the signed storage URLs Encompass returns; those transfers are not operations.

Policy and sensitive data

• Families. Operations that move money or change how it moves (rate locks, funding, fees, pricing, service orders) carry payment. Sending disclosures, notifications and invitations carries send. Users, personas, settings, webhooks and service accounts carry admin.
• Sensitive input. Social security and tax ids, bank and routing numbers, dates of birth, loan files, passwords, client secrets, private keys, signing keys, API key headers and service-provider logins can all be sent. Setting a user’s password (a user create or update that carries one, on either user API, or the internal- or external-user password change) is refused by default with credential_minting_refused until an organization admin’s credential_minting allowance names the operation; the same create or update without a password runs as usual. Under an approval rule the held request is encrypted in the secret store and approvers see each value masked. These values stay out of logs and are masked in every payload capture, which follows the application’s capture setting on managed and raw proxied calls alike; binary bodies, calls that can return a credential and calls carrying raw card data are never stored.
• Field Writer. Fields are named by id, so any value can be an identifier: v3-field-writer masks every value for approvers. update-user does the same for its patch values.
• Refused by default. Only operations whose response returns a live credential to the caller. Alter refuses them with credential_minting_refused until an organization admin allows them:

Operation	What the caller would hold
get-recipients	The links and codes that open a borrower’s document portal
get_webhook-v1-functions-auth	Each custom auth function’s private key, client secret and headers
create-a-session	A borrower’s signing session

Reading webhook subscriptions (get-all-subscriptions, get-a-subscription) is not refused: a subscription’s signing key only lets the lender’s receiver verify the events ICE sends. A rule for an API user connection names provider encompass-api-user, because each connection type has its own catalog.

• Not usable through Alter. create-a-session also needs a Point of Sale partner’s request signature, which no Alter connection holds. The webhook custom authentication operations need ICE’s premium licensing on the lender’s instance.
• Concurrency. Encompass allows 30 simultaneous calls per lender by default, shared by the lender and every partner, and answers 429 beyond that. Alter does not retry writes.
• Partial writes. ICE documents that updating a loan with an invalid value for a non-editable option field clears the field and returns no error. Asynchronous jobs report failure later on their status operation, not on the accepting call.

Maintenance

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Resume after a restart

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Rules for SDK functions

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations encompass. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged. A raw call can share an endpoint with several SDK functions and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval for one function:

{
  "effect": "require_approval",
  "when": { "operation": "encompass.create_contact" },
  "approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.