Provision partner users and create secure, WordPress-authenticated chatbot launches.

Embedded chat launches

Call the embedded-chat APIs only from your trusted backend. Use one server-only key with the user-management scopes needed by your integration and a separate server-only key with only embed:launch for iframe launches. Neither key may appear in a WordPress plugin, browser code, desktop-client configuration, or an iframe URL.

MortgageGuidelines assigns an integration identifier during onboarding. Use that exact allowlisted identifier anywhere the API path or request body contains integration; a descriptive placeholder is not accepted by the API. The examples below store it in INTEGRATION_ID.

Provision the user first

Every opaque external user ID must be linked to an active WordPress identity before launch. Provisioning creates or links the WordPress user and creates the internal chat identity. For partner-created accounts, the normal WordPress password-setup notification is sent only after provisioning has completed successfully.

API_BASE_URL="https://api.mortgageguidelines.com"
INTEGRATION_ID="<assigned-integration-id>"
EXTERNAL_USER_ID="employee-6d55c95f"

curl -X PUT \
  "$API_BASE_URL/v1/integrations/$INTEGRATION_ID/users/$EXTERNAL_USER_ID" \
  -H "Authorization: Bearer mgapi_live_provisioning_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"employee@example.com","name":"Taylor Morgan"}'

Use PATCH /v1/integrations/{integration}/users/{external_user_id} with {"status":"disabled"} to revoke grants and chat access immediately. Bulk provisioning is available through POST /v1/integrations/{integration}/user-imports; imports contain at most 1,000 unique users, require Idempotency-Key, and expose status through GET /v1/integrations/{integration}/user-imports/{job_id}.

See Partner User Lifecycle for profile changes, permanent account deletion, operation polling, and reprovisioning.

Create the launch

After provisioning, call POST /v1/embed-sessions from the trusted partner backend.

curl -X POST "$API_BASE_URL/v1/embed-sessions" \
  -H "Authorization: Bearer mgapi_live_launch_key" \
  -H "Idempotency-Key: launch-$EXTERNAL_USER_ID-001" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
  {
    "integration": "$INTEGRATION_ID",
    "user": {
      "external_user_id": "$EXTERNAL_USER_ID"
    },
    "loan_context": {
      "external_loan_id": "loan-7f4a2d18",
      "program": "fha",
      "purpose": "purchase",
      "property_state": "TX"
    }
  }
JSON

For an origin-bound browser integration, also send its exact approved HTTPS parent_origin. Omit parent_origin when MortgageGuidelines has configured the integration for a desktop host whose iframe origin is not stable.

Launch behavior

The launch URL contains a single-use code in its URL fragment.
The code expires after two minutes.
Consuming the code creates a ten-minute authentication-only session.
When authentication is required, the iframe opens the configured WordPress login in a popup and polls MortgageGuidelines for completion.
Successful WordPress authentication creates an absolute 24-hour server-side grant. A same-day relaunch is authorized without another prompt.
The loan-scoped chat token expires at the earlier of eight hours or the daily grant expiry and is never refreshed.
Refreshing the iframe requires the partner backend to request a fresh launch URL.
Every conversation is scoped to the authenticated organization, partner user, integration, account generation, and opaque loan ID.
Reuse an Idempotency-Key only when retrying the identical launch request.
Clerk is not used by this partner embed flow.

Allowed context

The strict loan_context schema accepts an opaque loan ID and approved categorical fields for program, purpose, occupancy, property type, state, units, milestone, and application date.

Do not send borrower identity, property address, income, assets, credit data, loan ratios, documents, free-form notes, a lender- or system-issued loan number, or other borrower PII. Unknown properties are rejected.

Origin requirements

Origin behavior is configured per integration:

Origin-bound integrations must send an exact approved HTTPS parent_origin.
Desktop-host integrations with unstable iframe origins must omit parent_origin; supplying it is rejected.