Partner user lifecycle

Partner-user endpoints use the immutable, opaque external_user_id from your system. Do not use an email address as this identifier, and do not change it when a user's name or email changes.

MortgageGuidelines assigns an integration identifier during onboarding. Substitute that exact allowlisted value for {integration} in every route below; a descriptive placeholder is not accepted by the API. The examples store it in INTEGRATION_ID.

Recommended API-key separation

Grant each server-only key the minimum scopes it needs:

The deletion scope is never added to an existing key automatically. An organization administrator must grant it explicitly.

Provision a user

Use PUT /v1/integrations/{integration}/users/{external_user_id} to create or match a user:

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

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": "taylor.morgan@example.com",
    "name": "Taylor Morgan",
    "team_external_id": "retail-west"
  }'

Provisioning is an identity-matching operation. Sending a different email for an existing user returns 409; use a profile-change operation instead. A deleted user requires explicit reprovisioning.

Public user responses are intentionally sanitized. They include entitlement status, readiness, account generation, profile synchronization state, and lifecycle-operation state, but not names, email addresses, passwords, or WordPress IDs.

Use GET /v1/integrations/{integration}/users to list users and GET /v1/integrations/{integration}/users/{external_user_id} to read one user's current state. Deleted users are excluded from the default list; request status=deleted explicitly to return their sanitized records and count.

Deactivate or reactivate access

Use PATCH /v1/integrations/{integration}/users/{external_user_id}:

{
  "status": "disabled"
}

Deactivation immediately revokes chat grants and pending authorization. A partner-created WordPress account is locked and its sessions are destroyed. A pre-existing MortgageGuidelines account retains unrelated WordPress access but cannot launch or use the partner chat experience.

Send {"status":"active"} to reactivate a disabled user. Reactivation permits a fresh login; it never restores an old session. A deleted account cannot be reactivated through this endpoint.

Change an email address or display name

Use POST /v1/integrations/{integration}/users/{external_user_id}/profile-changes. Idempotency-Key is required.

curl -X POST \
  "$API_BASE_URL/v1/integrations/$INTEGRATION_ID/users/$EXTERNAL_USER_ID/profile-changes" \
  -H "Authorization: Bearer mgapi_live_provisioning_key" \
  -H "Idempotency-Key: profile-employee-123-v2" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "taylor.wilson@example.com",
    "name": "Taylor Wilson"
  }'

Partner-created identities are updated directly. Email changes to a pre-existing MortgageGuidelines identity require verification at the new address unless an authorized MortgageGuidelines administrator applies an audited override. Name-only changes to those pre-existing identities also require that override.

The old profile remains active while verification is pending. After a successful email change, existing grants and WordPress sessions are revoked and the user must authenticate again. A name-only change does not force logout.

Permanently delete an account

Use POST /v1/integrations/{integration}/users/{external_user_id}/deletions with a key that has embed:users:delete. Idempotency-Key is required and the audit note is optional.

curl -X POST \
  "$API_BASE_URL/v1/integrations/$INTEGRATION_ID/users/$EXTERNAL_USER_ID/deletions" \
  -H "Authorization: Bearer mgapi_live_deletion_key" \
  -H "Idempotency-Key: deletion-employee-123-001" \
  -H "Content-Type: application/json" \
  -d '{"note":"Employment ended"}'

The API returns 202 and disables access immediately. Account deletion then completes asynchronously:

• A partner-created WordPress account is deleted.
• A pre-existing MortgageGuidelines account remains, but its partner mapping is detached.
• The current chat identity is blocked.
• The current account generation is closed and the partner user becomes deleted.

Account deletion is not privacy erasure. Authorized auditors retain the user's identified profile history, lifecycle history, and earlier conversations indefinitely. No deletion notification is sent to the user.

Poll an operation

Profile changes, deletions, and reprovisioning return an operation.operation_id. Poll it with:

GET /v1/integrations/{integration}/user-operations/{operation_id}

The key needs embed:users:read. Operation states are queued, verification_pending, processing, completed, failed, expired, or cancelled. Public operation responses never include audit notes, profile values, or verification secrets.

Persist one idempotency key before submitting an operation. Reuse it only to retry the identical route and payload; use a new key for a different user or changed request.

Reprovision a deleted user

Ordinary provisioning and reactivation cannot revive a deleted account. Use POST /v1/integrations/{integration}/users/{external_user_id}/reprovision with embed:users:write and a required Idempotency-Key.

Reprovisioning preserves the root partner-user record and immutable external ID while incrementing account_generation. It creates new WordPress and chat identities. The returning user cannot access conversations from an earlier generation; authorized auditors retain access to that history.

Teams and bulk imports

Team routes use the same assigned integration identifier:

• GET /v1/integrations/{integration}/teams
• PUT /v1/integrations/{integration}/teams/{external_team_id}
• GET /v1/integrations/{integration}/teams/{external_team_id}
• PATCH /v1/integrations/{integration}/teams/{external_team_id}

Use POST /v1/integrations/{integration}/user-imports for up to 1,000 unique users and poll GET /v1/integrations/{integration}/user-imports/{job_id}. Imports provision and match identities; they do not perform profile changes or deletions.