MortgageGuidelines API

API Reference

Generated endpoint reference backed by the shared route contract.

Public responses include customer-facing identifiers, answer text, sanitized citations, sanitized source summaries, and metadata.tokens_used. Model names, provider details, prompt context, retrieval diagnostics, and internal service configuration are intentionally excluded.

Account

1 endpoint

get/v1/me

Get authenticated API key details

Returns the authenticated public API key summary and client identity.

cURL
curl -X GET "https://api.mortgageguidelines.com/v1/me" \
  -H "Authorization: Bearer mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/me", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "key": {
    "id": "pak_test",
    "name": "Example Lender Production",
    "status": "active",
    "scopes": [
      "chat:read",
      "chat:write",
      "sources:read"
    ],
    "last_four": "test",
    "client": {
      "name": "Example Lender",
      "organization": "Example Mortgage Company"
    }
  }
}

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "key": {
    "id": "pak_test",
    "name": "Example Lender Production",
    "status": "active",
    "scopes": [
      "chat:read",
      "chat:write",
      "sources:read"
    ],
    "last_four": "test",
    "client": {
      "name": "Example Lender",
      "organization": "Example Mortgage Company"
    }
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "key": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "example": "pak_test"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "example": "Example Lender Production"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "revoked"
          ],
          "example": "active"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "example": [
            "chat:read",
            "chat:write",
            "sources:read"
          ]
        },
        "last_four": {
          "type": "string",
          "minLength": 1,
          "example": "test"
        },
        "client": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "example": "Example Lender"
            },
            "organization": {
              "type": "string",
              "example": "Example Mortgage Company"
            }
          },
          "required": [
            "name"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "scopes",
        "last_four",
        "client"
      ]
    }
  },
  "required": [
    "request_id",
    "key"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Discovery

1 endpoint

get/v1/sources

List the sources available to the authenticated API key

Returns selectable agency, tenant, and shared sources available to this API key.

cURL
curl -X GET "https://api.mortgageguidelines.com/v1/sources" \
  -H "X-API-Key: mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/sources", {
  headers: {
    "X-API-Key": "mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "agency_source_types": [
    "fannie_mae",
    "fha"
  ],
  "tenant_source_keys": [
    "product-guides"
  ],
  "tenant_sources": [
    {
      "key": "product-guides",
      "label": "Product Guides",
      "description": "Internal product guidance",
      "defaultOn": true
    }
  ],
  "default_tenant_source_keys": [
    "product-guides"
  ],
  "shared_source_types": [
    "mortgage_guidelines"
  ],
  "shared_sources": [
    {
      "sourceType": "mortgage_guidelines",
      "label": "Mortgage Guidelines",
      "defaultOn": true
    }
  ],
  "default_shared_source_types": [
    "mortgage_guidelines"
  ]
}

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "agency_source_types": [
    "fannie_mae",
    "fha"
  ],
  "tenant_source_keys": [
    "product-guides"
  ],
  "tenant_sources": [
    {
      "key": "product-guides",
      "label": "Product Guides",
      "description": "Internal product guidance",
      "defaultOn": true
    }
  ],
  "default_tenant_source_keys": [
    "product-guides"
  ],
  "shared_source_types": [
    "mortgage_guidelines"
  ],
  "shared_sources": [
    {
      "sourceType": "mortgage_guidelines",
      "label": "Mortgage Guidelines",
      "defaultOn": true
    }
  ],
  "default_shared_source_types": [
    "mortgage_guidelines"
  ]
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "agency_source_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "fannie_mae",
        "fha"
      ]
    },
    "tenant_source_keys": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "product-guides"
      ]
    },
    "tenant_sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "minLength": 1,
            "example": "product-guides"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "example": "Product Guides"
          },
          "description": {
            "type": "string",
            "example": "Client-specific product guidelines"
          },
          "defaultOn": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "key",
          "label",
          "defaultOn"
        ],
        "additionalProperties": false
      }
    },
    "default_tenant_source_keys": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "product-guides"
      ]
    },
    "shared_source_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "mortgage_guidelines"
      ]
    },
    "shared_sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sourceType": {
            "type": "string",
            "minLength": 1,
            "example": "mortgage_guidelines"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "example": "Mortgage Guidelines"
          },
          "description": {
            "type": "string",
            "example": "Shared platform content available to this client"
          },
          "defaultOn": {
            "type": "boolean",
            "example": false
          }
        },
        "required": [
          "sourceType",
          "label",
          "defaultOn"
        ],
        "additionalProperties": false
      }
    },
    "default_shared_source_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "mortgage_guidelines"
      ]
    }
  },
  "required": [
    "request_id",
    "agency_source_types",
    "tenant_source_keys",
    "tenant_sources",
    "default_tenant_source_keys",
    "shared_source_types",
    "shared_sources",
    "default_shared_source_types"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Embedded Chat

1 endpoint

post/v1/embed-sessions

Create a one-time embedded chat launch

Authenticates a trusted partner backend and returns a single-use embedded-chat launch URL. The API key must remain server-side.

Notes

  • The user must already be provisioned and active.
  • The returned URL expires after two minutes and can be exchanged only once.
  • Borrower PII, employee identity fields, and financial ratios are not accepted.

Idempotency

  • Reuse the same Idempotency-Key only when retrying the identical launch request. Use a new key for every new iframe launch.

Request body

Configured public integration name or explicitly authorized alias, provisioned-user identifier and approved non-PII loan context. All launches omit parent_origin, host_policy and caller source/LOS labels; unknown fields are rejected. Server-owned per-key canonical integration and exact public-name authorization is required. Identical retries preserve the original response and expiry; changing the public name changes the request.

Request body example
{
  "integration": "your_assigned_integration",
  "user": {
    "external_user_id": "partner-user-6d55c95f"
  },
  "loan_context": {
    "external_loan_id": "loan-7f4a2d18",
    "program": "fha",
    "purpose": "purchase",
    "occupancy": "primary_residence",
    "property_type": "single_family",
    "property_state": "TX",
    "units": 1,
    "milestone": "processing",
    "application_date": "2026-07-10"
  }
}
Request body schema
{
  "type": "object",
  "properties": {
    "integration": {
      "type": "string",
      "minLength": 3,
      "maxLength": 64,
      "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
      "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
      "example": "your_assigned_integration"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$",
          "description": "Stable opaque identifier assigned to the user by the partner system. Do not send an email address.",
          "example": "partner-user-6d55c95f"
        }
      },
      "required": [
        "external_user_id"
      ],
      "additionalProperties": false
    },
    "loan_context": {
      "type": "object",
      "properties": {
        "external_loan_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$",
          "description": "Opaque loan correlation identifier. Do not send a lender or source-system loan number.",
          "example": "loan-7f4a2d18"
        },
        "program": {
          "type": "string",
          "enum": [
            "conventional",
            "fha",
            "va",
            "usda",
            "other"
          ],
          "example": "fha"
        },
        "purpose": {
          "type": "string",
          "enum": [
            "purchase",
            "rate_term_refinance",
            "cash_out_refinance",
            "construction",
            "other"
          ],
          "example": "purchase"
        },
        "occupancy": {
          "type": "string",
          "enum": [
            "primary_residence",
            "second_home",
            "investment",
            "other"
          ],
          "example": "primary_residence"
        },
        "property_type": {
          "type": "string",
          "enum": [
            "single_family",
            "condominium",
            "townhouse",
            "manufactured_home",
            "two_to_four_unit",
            "other"
          ],
          "example": "single_family"
        },
        "property_state": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "example": "TX"
        },
        "units": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "example": 1
        },
        "milestone": {
          "type": "string",
          "enum": [
            "application",
            "processing",
            "underwriting",
            "approved",
            "clear_to_close",
            "closed",
            "other"
          ],
          "example": "processing"
        },
        "application_date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
          "example": "2026-07-10"
        }
      },
      "required": [
        "external_loan_id"
      ],
      "additionalProperties": false,
      "description": "Approved non-borrower-PII loan context. Unknown fields are rejected."
    }
  },
  "required": [
    "integration",
    "user",
    "loan_context"
  ],
  "additionalProperties": false
}
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/embed-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: partner-launch-6d55c95f-001" \
  -d '{
  "integration": "your_assigned_integration",
  "user": {
    "external_user_id": "partner-user-6d55c95f"
  },
  "loan_context": {
    "external_loan_id": "loan-7f4a2d18",
    "program": "fha",
    "purpose": "purchase",
    "occupancy": "primary_residence",
    "property_type": "single_family",
    "property_state": "TX",
    "units": 1,
    "milestone": "processing",
    "application_date": "2026-07-10"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/embed-sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "partner-launch-6d55c95f-001",
  },
  body: JSON.stringify({
  "integration": "your_assigned_integration",
  "user": {
    "external_user_id": "partner-user-6d55c95f"
  },
  "loan_context": {
    "external_loan_id": "loan-7f4a2d18",
    "program": "fha",
    "purpose": "purchase",
    "occupancy": "primary_residence",
    "property_type": "single_family",
    "property_state": "TX",
    "units": 1,
    "milestone": "processing",
    "application_date": "2026-07-10"
  }
}),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "launch_id": "launch_06f22d7e7137e087",
  "launch_url": "https://app.mortgageguidelines.com/embed/partner/your_assigned_integration#launch=one-time-code",
  "expires_at": "2026-07-10T14:02:00.000Z"
}

Response bodies

201 response schema
201 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "launch_id": "launch_06f22d7e7137e087",
  "launch_url": "https://app.mortgageguidelines.com/embed/partner/your_assigned_integration#launch=one-time-code",
  "expires_at": "2026-07-10T14:02:00.000Z"
}
201 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "launch_id": {
      "type": "string",
      "minLength": 1,
      "example": "launch_06f22d7e7137e087"
    },
    "launch_url": {
      "type": "string",
      "format": "uri",
      "description": "Load this server-issued target unchanged. The canonical partner determines the route; an authorized public alias does not create another identity or history namespace. A response does not certify actual LOS host compatibility.",
      "example": "https://app.mortgageguidelines.com/embed/partner/your_assigned_integration#launch=one-time-code"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "example": "2026-07-10T14:02:00.000Z"
    }
  },
  "required": [
    "request_id",
    "launch_id",
    "launch_url",
    "expires_at"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Partner Teams

4 endpoints

get/v1/integrations/{integration}/teams

List partner teams

Lists organization-scoped partner teams and current assignment counts.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
statusqueryoptional
status schema
{
  "type": "string",
  "enum": [
    "active",
    "archived"
  ]
}
limitqueryoptional
limit schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 100,
  "example": 100
}
cursorqueryoptional
cursor schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 1024
}
cURL
curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams' \
  --header "Authorization: Bearer $API_KEY"

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "teams": [
    {
      "id": "team_7f4a2d18",
      "integration": "your_assigned_integration",
      "external_team_id": "retail-west",
      "name": "Retail West",
      "status": "active",
      "user_count": 1,
      "created_at": "2026-07-10T14:00:00.000Z",
      "updated_at": "2026-07-10T14:00:00.000Z"
    }
  ],
  "next_cursor": null
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "teams": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "integration": {
            "type": "string",
            "minLength": 3,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
            "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
            "example": "your_assigned_integration"
          },
          "external_team_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ]
          },
          "user_count": {
            "type": "integer",
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "integration",
          "external_team_id",
          "name",
          "status",
          "user_count",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "request_id",
    "teams",
    "next_cursor"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
put/v1/integrations/{integration}/teams/{external_team_id}

Create or match a partner team

Idempotently creates or matches a team. Use PATCH to rename an existing team.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_team_idpathrequired

Stable opaque partner team identifier.

external_team_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "retail-west"
}

Request body

Request body example
{
  "name": "Retail West"
}
Request body schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Retail West"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
cURL
curl \
  --request PUT \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams/retail-west' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Retail West"
}'

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "team": {
    "id": "team_7f4a2d18",
    "integration": "your_assigned_integration",
    "external_team_id": "retail-west",
    "name": "Retail West",
    "status": "active",
    "user_count": 1,
    "created_at": "2026-07-10T14:00:00.000Z",
    "updated_at": "2026-07-10T14:00:00.000Z"
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}
201 response schema
201 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "team": {
    "id": "team_7f4a2d18",
    "integration": "your_assigned_integration",
    "external_team_id": "retail-west",
    "name": "Retail West",
    "status": "active",
    "user_count": 0,
    "created_at": "2026-07-10T14:00:00.000Z",
    "updated_at": "2026-07-10T14:00:00.000Z"
  }
}
201 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
get/v1/integrations/{integration}/teams/{external_team_id}

Get a partner team

Returns an organization-scoped partner team and its current assignment count.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_team_idpathrequired

Stable opaque partner team identifier.

external_team_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "retail-west"
}
cURL
curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams/retail-west' \
  --header "Authorization: Bearer $API_KEY"

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "team": {
    "id": "team_7f4a2d18",
    "integration": "your_assigned_integration",
    "external_team_id": "retail-west",
    "name": "Retail West",
    "status": "active",
    "user_count": 1,
    "created_at": "2026-07-10T14:00:00.000Z",
    "updated_at": "2026-07-10T14:00:00.000Z"
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
patch/v1/integrations/{integration}/teams/{external_team_id}

Update or archive a partner team

Renames or archives a team. A team with current or queued assignments cannot be archived.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_team_idpathrequired

Stable opaque partner team identifier.

external_team_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "retail-west"
}

Request body

Request body example
{
  "name": "Western Retail"
}
Request body schema
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Retail West"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ],
      "example": "archived"
    }
  },
  "additionalProperties": false
}
cURL
curl \
  --request PATCH \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/teams/retail-west' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Western Retail"
}'

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "team": {
    "id": "team_7f4a2d18",
    "integration": "your_assigned_integration",
    "external_team_id": "retail-west",
    "name": "Western Retail",
    "status": "active",
    "user_count": 1,
    "created_at": "2026-07-10T14:00:00.000Z",
    "updated_at": "2026-07-10T14:05:00.000Z"
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "team": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_team_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "archived"
          ]
        },
        "user_count": {
          "type": "integer",
          "minimum": 0
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "integration",
        "external_team_id",
        "name",
        "status",
        "user_count",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "team"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Partner Users

10 endpoints

get/v1/integrations/{integration}/users

List partner users

Lists sanitized partner-user entitlement, mapping readiness, and current team classification. Deleted users are excluded by default and are returned only when status=deleted is supplied explicitly.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
qqueryoptional

Case-insensitive partial external user ID. Email addresses are not accepted.

q schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128
}
external_user_idqueryoptional
external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$"
}
statusqueryoptional

Filter by lifecycle status. Deleted users are excluded unless status=deleted is supplied explicitly.

status schema
{
  "type": "string",
  "enum": [
    "active",
    "disabled",
    "deleted"
  ]
}
provisioning_statusqueryoptional
provisioning_status schema
{
  "type": "string",
  "enum": [
    "pending",
    "active",
    "failed"
  ]
}
team_external_idqueryoptional
team_external_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$"
}
unassignedqueryoptional
unassigned schema
{
  "type": "string",
  "enum": [
    "true",
    "false"
  ],
  "example": "false"
}
identity_originqueryoptional
identity_origin schema
{
  "type": "string",
  "enum": [
    "existing_mg",
    "partner_created",
    "unresolved"
  ]
}
experience_typequeryoptional
experience_type schema
{
  "type": "string",
  "enum": [
    "mg",
    "white_label"
  ]
}
mapping_statusqueryoptional
mapping_status schema
{
  "type": "string",
  "enum": [
    "pending",
    "mapped",
    "failed",
    "unmapped"
  ]
}
readinessqueryoptional
readiness schema
{
  "type": "string",
  "enum": [
    "ready",
    "blocked"
  ]
}
limitqueryoptional
limit schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 25,
  "example": 25
}
cursorqueryoptional
cursor schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 1024
}
cURL
curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users' \
  --header "Authorization: Bearer $API_KEY"

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "users": [
    {
      "integration": "your_assigned_integration",
      "external_user_id": "partner-user-6d55c95f",
      "team": {
        "id": "team_7f4a2d18",
        "external_team_id": "retail-west",
        "name": "Retail West",
        "status": "active"
      },
      "assignment_version": 1,
      "identity_origin": "partner_created",
      "experience_type": "white_label",
      "mapping_status": "mapped",
      "launch_eligibility": {
        "can_launch": true,
        "blocking_reasons": []
      },
      "status": "active",
      "provisioning_status": "active",
      "wordpress_linked": true,
      "access_version": 1,
      "account_generation": 1,
      "profile_version": 1,
      "profile_sync_status": "applied",
      "wordpress_sync_status": "applied",
      "lifecycle_operation": null,
      "created_at": "2026-07-10T14:01:00.000Z",
      "updated_at": "2026-07-10T14:01:00.000Z"
    }
  ],
  "counts": {
    "total": 1,
    "active": 1,
    "disabled": 0,
    "deleted": 0,
    "pending": 0,
    "failed": 0
  },
  "next_cursor": null
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "integration": {
            "type": "string",
            "minLength": 3,
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
            "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
            "example": "your_assigned_integration"
          },
          "external_user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "team": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "external_team_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "archived"
                ]
              }
            },
            "required": [
              "id",
              "external_team_id",
              "name",
              "status"
            ],
            "additionalProperties": false
          },
          "assignment_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "identity_origin": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "existing_mg",
              "partner_created"
            ]
          },
          "experience_type": {
            "type": "string",
            "enum": [
              "mg",
              "white_label"
            ]
          },
          "mapping_status": {
            "type": "string",
            "enum": [
              "pending",
              "mapped",
              "failed",
              "unmapped"
            ]
          },
          "launch_eligibility": {
            "type": "object",
            "properties": {
              "can_launch": {
                "type": "boolean"
              },
              "blocking_reasons": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "disabled",
                    "deleted",
                    "provisioning_pending",
                    "provisioning_failed",
                    "profile_sync_pending",
                    "profile_sync_failed",
                    "wordpress_sync_pending",
                    "wordpress_sync_failed",
                    "wordpress_unlinked",
                    "chat_identity_unlinked"
                  ]
                }
              }
            },
            "required": [
              "can_launch",
              "blocking_reasons"
            ],
            "additionalProperties": false
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled",
              "deleted"
            ]
          },
          "provisioning_status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "failed"
            ]
          },
          "wordpress_linked": {
            "type": "boolean"
          },
          "access_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "account_generation": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "profile_version": {
            "type": "integer",
            "exclusiveMinimum": 0
          },
          "profile_sync_status": {
            "type": "string",
            "enum": [
              "applied",
              "pending",
              "failed"
            ]
          },
          "wordpress_sync_status": {
            "type": "string",
            "enum": [
              "applied",
              "pending",
              "failed"
            ]
          },
          "lifecycle_operation": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "operation_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "type": {
                "type": "string",
                "enum": [
                  "profile_change",
                  "deletion",
                  "reprovision"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "queued",
                  "verification_pending",
                  "processing",
                  "completed",
                  "failed",
                  "expired",
                  "cancelled"
                ]
              },
              "error_code": {
                "type": [
                  "string",
                  "null"
                ],
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z0-9._:-]+$"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "operation_id",
              "type",
              "status",
              "error_code",
              "updated_at"
            ],
            "additionalProperties": false,
            "description": "Sanitized state of the partner user's current lifecycle operation."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "integration",
          "external_user_id",
          "team",
          "assignment_version",
          "identity_origin",
          "experience_type",
          "mapping_status",
          "launch_eligibility",
          "status",
          "provisioning_status",
          "wordpress_linked",
          "access_version",
          "account_generation",
          "profile_version",
          "profile_sync_status",
          "wordpress_sync_status",
          "lifecycle_operation",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "counts": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer",
          "minimum": 0
        },
        "active": {
          "type": "integer",
          "minimum": 0
        },
        "disabled": {
          "type": "integer",
          "minimum": 0
        },
        "deleted": {
          "type": "integer",
          "minimum": 0
        },
        "pending": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "total",
        "active",
        "disabled",
        "deleted",
        "pending",
        "failed"
      ],
      "additionalProperties": false
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "request_id",
    "users",
    "counts",
    "next_cursor"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
put/v1/integrations/{integration}/users/{external_user_id}

Provision or match a partner user

Creates or matches the WordPress identity assigned to an immutable opaque partner user ID and can update its team classification. Omit team_external_id to preserve an existing assignment; send null to clear it. A newly created user with no team_external_id is unassigned. A different email for an existing user returns 409; use the profile-change operation instead. Deleted users require the explicit reprovision operation. Passwords are never accepted or returned.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_user_idpathrequired

Stable opaque partner user identifier.

external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

The employee identity WordPress should provision or match, plus an optional team assignment. Omission preserves an existing assignment and null clears it.

Request body example
{
  "email": "taylor.morgan@example.com",
  "name": "Taylor Morgan"
}
Request body schema
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "example": "employee@example.com"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Taylor Morgan"
    },
    "team_external_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Team to assign. Omit to preserve an existing assignment; send null to clear it.",
      "example": "retail-west"
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}
cURL
curl \
  --request PUT \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "taylor.morgan@example.com",
  "name": "Taylor Morgan"
}'

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "user": {
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "team": {
      "id": "team_7f4a2d18",
      "external_team_id": "retail-west",
      "name": "Retail West",
      "status": "active"
    },
    "assignment_version": 1,
    "identity_origin": "partner_created",
    "experience_type": "white_label",
    "mapping_status": "mapped",
    "launch_eligibility": {
      "can_launch": true,
      "blocking_reasons": []
    },
    "status": "active",
    "provisioning_status": "active",
    "wordpress_linked": true,
    "access_version": 1,
    "account_generation": 1,
    "profile_version": 1,
    "profile_sync_status": "applied",
    "wordpress_sync_status": "applied",
    "lifecycle_operation": null,
    "created_at": "2026-07-10T14:01:00.000Z",
    "updated_at": "2026-07-10T14:01:00.000Z"
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}
201 response schema
201 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "user": {
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "team": null,
    "assignment_version": 1,
    "identity_origin": "partner_created",
    "experience_type": "white_label",
    "mapping_status": "mapped",
    "launch_eligibility": {
      "can_launch": true,
      "blocking_reasons": []
    },
    "status": "active",
    "provisioning_status": "active",
    "wordpress_linked": true,
    "access_version": 1,
    "account_generation": 1,
    "profile_version": 1,
    "profile_sync_status": "applied",
    "wordpress_sync_status": "applied",
    "lifecycle_operation": null,
    "created_at": "2026-07-10T14:01:00.000Z",
    "updated_at": "2026-07-10T14:01:00.000Z"
  }
}
201 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}
202 response schema
202 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "user": {
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "team": null,
    "assignment_version": 1,
    "identity_origin": null,
    "experience_type": "white_label",
    "mapping_status": "pending",
    "launch_eligibility": {
      "can_launch": false,
      "blocking_reasons": [
        "provisioning_pending",
        "wordpress_unlinked",
        "chat_identity_unlinked"
      ]
    },
    "status": "active",
    "provisioning_status": "pending",
    "wordpress_linked": false,
    "access_version": 1,
    "account_generation": 1,
    "profile_version": 1,
    "profile_sync_status": "applied",
    "wordpress_sync_status": "applied",
    "lifecycle_operation": null,
    "created_at": "2026-07-10T14:01:00.000Z",
    "updated_at": "2026-07-10T14:01:00.000Z"
  }
}
202 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
get/v1/integrations/{integration}/users/{external_user_id}

Get partner-user access status

Returns sanitized entitlement status without names, email addresses, passwords, or WordPress IDs.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_user_idpathrequired

Stable opaque partner user identifier.

external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}
cURL
curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f' \
  --header "Authorization: Bearer $API_KEY"

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "user": {
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "team": {
      "id": "team_7f4a2d18",
      "external_team_id": "retail-west",
      "name": "Retail West",
      "status": "active"
    },
    "assignment_version": 1,
    "identity_origin": "partner_created",
    "experience_type": "white_label",
    "mapping_status": "mapped",
    "launch_eligibility": {
      "can_launch": true,
      "blocking_reasons": []
    },
    "status": "active",
    "provisioning_status": "active",
    "wordpress_linked": true,
    "access_version": 1,
    "account_generation": 1,
    "profile_version": 1,
    "profile_sync_status": "applied",
    "wordpress_sync_status": "applied",
    "lifecycle_operation": null,
    "created_at": "2026-07-10T14:01:00.000Z",
    "updated_at": "2026-07-10T14:01:00.000Z"
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
patch/v1/integrations/{integration}/users/{external_user_id}

Update partner-user access or team

Soft-disables or re-enables MG access and can update the user's team classification. Omit team_external_id to preserve the current assignment; send null to clear it. Disabling revokes active grants immediately and locks partner-created WordPress accounts; existing MG accounts retain unrelated WordPress access. Deleted users cannot be reactivated with this route.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_user_idpathrequired

Stable opaque partner user identifier.

external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

The desired entitlement status and/or team assignment. Omission preserves the current team and null clears it.

Request body example
{
  "status": "disabled"
}
Request body schema
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ],
      "example": "disabled"
    },
    "team_external_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Team to assign. Omit to preserve the current assignment; send null to clear it.",
      "example": "retail-west"
    }
  },
  "additionalProperties": false
}
cURL
curl \
  --request PATCH \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "disabled"
}'

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "user": {
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "team": {
      "id": "team_7f4a2d18",
      "external_team_id": "retail-west",
      "name": "Retail West",
      "status": "active"
    },
    "assignment_version": 1,
    "identity_origin": "partner_created",
    "experience_type": "white_label",
    "mapping_status": "mapped",
    "launch_eligibility": {
      "can_launch": false,
      "blocking_reasons": [
        "disabled"
      ]
    },
    "status": "disabled",
    "provisioning_status": "active",
    "wordpress_linked": true,
    "access_version": 2,
    "account_generation": 1,
    "profile_version": 1,
    "profile_sync_status": "applied",
    "wordpress_sync_status": "applied",
    "lifecycle_operation": null,
    "created_at": "2026-07-10T14:01:00.000Z",
    "updated_at": "2026-07-10T14:05:00.000Z"
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "user": {
      "type": "object",
      "properties": {
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "team": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1
            },
            "external_team_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          },
          "required": [
            "id",
            "external_team_id",
            "name",
            "status"
          ],
          "additionalProperties": false
        },
        "assignment_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "identity_origin": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "existing_mg",
            "partner_created"
          ]
        },
        "experience_type": {
          "type": "string",
          "enum": [
            "mg",
            "white_label"
          ]
        },
        "mapping_status": {
          "type": "string",
          "enum": [
            "pending",
            "mapped",
            "failed",
            "unmapped"
          ]
        },
        "launch_eligibility": {
          "type": "object",
          "properties": {
            "can_launch": {
              "type": "boolean"
            },
            "blocking_reasons": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "disabled",
                  "deleted",
                  "provisioning_pending",
                  "provisioning_failed",
                  "profile_sync_pending",
                  "profile_sync_failed",
                  "wordpress_sync_pending",
                  "wordpress_sync_failed",
                  "wordpress_unlinked",
                  "chat_identity_unlinked"
                ]
              }
            }
          },
          "required": [
            "can_launch",
            "blocking_reasons"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "disabled",
            "deleted"
          ]
        },
        "provisioning_status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "failed"
          ]
        },
        "wordpress_linked": {
          "type": "boolean"
        },
        "access_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_version": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "profile_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "wordpress_sync_status": {
          "type": "string",
          "enum": [
            "applied",
            "pending",
            "failed"
          ]
        },
        "lifecycle_operation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "operation_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "type": {
              "type": "string",
              "enum": [
                "profile_change",
                "deletion",
                "reprovision"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "queued",
                "verification_pending",
                "processing",
                "completed",
                "failed",
                "expired",
                "cancelled"
              ]
            },
            "error_code": {
              "type": [
                "string",
                "null"
              ],
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9._:-]+$"
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "operation_id",
            "type",
            "status",
            "error_code",
            "updated_at"
          ],
          "additionalProperties": false,
          "description": "Sanitized state of the partner user's current lifecycle operation."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "integration",
        "external_user_id",
        "team",
        "assignment_version",
        "identity_origin",
        "experience_type",
        "mapping_status",
        "launch_eligibility",
        "status",
        "provisioning_status",
        "wordpress_linked",
        "access_version",
        "account_generation",
        "profile_version",
        "profile_sync_status",
        "wordpress_sync_status",
        "lifecycle_operation",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "user"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
post/v1/integrations/{integration}/user-imports

Queue a bulk partner-user import

Queues up to 1,000 unique partner users for bounded asynchronous WordPress provisioning.

Idempotency

  • Idempotency-Key is required. Reuse it only for the identical import payload.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}

Request body

Unique partner users to provision.

Request body example
{
  "users": [
    {
      "external_user_id": "partner-user-6d55c95f",
      "email": "taylor.morgan@example.com",
      "name": "Taylor Morgan"
    },
    {
      "external_user_id": "partner-user-10a3c2b1",
      "email": "alex.lee@example.com",
      "name": "Alex Lee"
    }
  ]
}
Request body schema
{
  "type": "object",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "external_user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "example": "partner-user-6d55c95f"
          },
          "email": {
            "type": "string",
            "maxLength": 254,
            "format": "email",
            "example": "employee@example.com"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120,
            "example": "Taylor Morgan"
          },
          "team_external_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$",
            "description": "Team to assign. Omit to preserve an existing assignment; send null to clear it.",
            "example": "retail-west"
          }
        },
        "required": [
          "external_user_id",
          "email"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 1000
    }
  },
  "required": [
    "users"
  ],
  "additionalProperties": false
}
cURL
curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/user-imports' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "users": [
    {
      "external_user_id": "partner-user-6d55c95f",
      "email": "taylor.morgan@example.com",
      "name": "Taylor Morgan"
    },
    {
      "external_user_id": "partner-user-10a3c2b1",
      "email": "alex.lee@example.com",
      "name": "Alex Lee"
    }
  ]
}'

Response bodies

202 response schema
202 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "job_id": "pjob_06f22d7e7137e087",
  "status": "queued",
  "total": 2
}
202 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "job_id": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "processing",
        "completed",
        "completed_with_errors"
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "request_id",
    "job_id",
    "status",
    "total"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
post/v1/integrations/{integration}/users/{external_user_id}/profile-changes

Change a partner user's profile

Queues a versioned email and/or display-name change for the exact mapped identity. Partner-created identities process directly. Existing MG email changes enter verification_pending for up to 24 hours; existing-MG name-only changes require an audited MG-admin override. Ordinary provisioning never performs this change.

Idempotency

  • Idempotency-Key is required. Reuse it only for the identical profile-change payload.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_user_idpathrequired

Stable opaque partner user identifier.

external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

At least one new profile field. The immutable external_user_id is never changed.

Request body example
{
  "email": "taylor.wilson@example.com",
  "name": "Taylor Wilson"
}
Request body schema
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "example": "taylor.wilson@example.com"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Taylor Wilson"
    }
  },
  "additionalProperties": false
}
cURL
curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f/profile-changes' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "taylor.wilson@example.com",
  "name": "Taylor Wilson"
}'

Response bodies

202 response schema
202 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_06f22d7e7137e087",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "profile_change",
    "status": "verification_pending",
    "account_generation": 1,
    "error_code": null,
    "verification_expires_at": "2026-07-11T14:02:00.000Z",
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}
202 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
post/v1/integrations/{integration}/users/{external_user_id}/deletions

Permanently delete a partner account

Immediately disables access and queues permanent account deletion without notifying the user. Identified audit and conversation history is retained indefinitely; the optional audit note is never returned by the public API.

Idempotency

  • Idempotency-Key is required. Reuse it only for the identical deletion request.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_user_idpathrequired

Stable opaque partner user identifier.

external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

An optional audit note. Send an empty object when no note is needed.

Request body example
{
  "note": "Employment ended"
}
Request body schema
{
  "type": "object",
  "properties": {
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Optional audit note. It is retained for authorized audit viewers and is not returned by the public API.",
      "example": "Employment ended"
    }
  },
  "additionalProperties": false
}
cURL
curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f/deletions' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "note": "Employment ended"
}'

Response bodies

202 response schema
202 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_16e33e8f8248f198",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "deletion",
    "status": "queued",
    "account_generation": 1,
    "error_code": null,
    "verification_expires_at": null,
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}
202 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
post/v1/integrations/{integration}/users/{external_user_id}/reprovision

Reprovision a deleted partner user

Creates a new account generation for a deleted external user ID. The returning user receives new WordPress and chat identities and cannot access earlier-generation conversations.

Idempotency

  • Idempotency-Key is required. Reuse it only for the identical reprovision request.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
external_user_idpathrequired

Stable opaque partner user identifier.

external_user_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "partner-user-6d55c95f"
}

Request body

Identity and optional team assignment for the new account generation.

Request body example
{
  "email": "taylor.returned@example.com",
  "name": "Taylor Wilson",
  "team_external_id": "retail-west"
}
Request body schema
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "example": "returning.employee@example.com"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "example": "Taylor Wilson"
    },
    "team_external_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9._:-]+$",
      "description": "Team to assign to the new account generation. Omit to start unassigned.",
      "example": "retail-west"
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false,
  "description": "Identity and optional team assignment for a new account generation of a deleted partner user."
}
cURL
curl \
  --request POST \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/users/partner-user-6d55c95f/reprovision' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Idempotency-Key: replace-with-a-unique-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "taylor.returned@example.com",
  "name": "Taylor Wilson",
  "team_external_id": "retail-west"
}'

Response bodies

202 response schema
202 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_66f930b80ca0402a",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "reprovision",
    "status": "queued",
    "account_generation": 2,
    "error_code": null,
    "verification_expires_at": null,
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}
202 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
get/v1/integrations/{integration}/user-operations/{operation_id}

Get a partner-user lifecycle operation

Returns sanitized deletion, profile-change, or reprovision progress. Audit notes, identity values, and verification secrets are never returned.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
operation_idpathrequired

Partner-user lifecycle operation identifier.

operation_id schema
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "pattern": "^[A-Za-z0-9._:-]+$",
  "example": "pop_06f22d7e7137e087"
}
cURL
curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/user-operations/pop_06f22d7e7137e087' \
  --header "Authorization: Bearer $API_KEY"

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "operation": {
    "operation_id": "pop_06f22d7e7137e087",
    "integration": "your_assigned_integration",
    "external_user_id": "partner-user-6d55c95f",
    "type": "profile_change",
    "status": "verification_pending",
    "account_generation": 1,
    "error_code": null,
    "verification_expires_at": "2026-07-11T14:02:00.000Z",
    "created_at": "2026-07-10T14:02:00.000Z",
    "updated_at": "2026-07-10T14:02:00.000Z",
    "completed_at": null
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "operation": {
      "type": "object",
      "properties": {
        "operation_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "integration": {
          "type": "string",
          "minLength": 3,
          "maxLength": 64,
          "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
          "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
          "example": "your_assigned_integration"
        },
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "type": {
          "type": "string",
          "enum": [
            "profile_change",
            "deletion",
            "reprovision"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "verification_pending",
            "processing",
            "completed",
            "failed",
            "expired",
            "cancelled"
          ]
        },
        "account_generation": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "error_code": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9._:-]+$"
        },
        "verification_expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "operation_id",
        "integration",
        "external_user_id",
        "type",
        "status",
        "account_generation",
        "error_code",
        "verification_expires_at",
        "created_at",
        "updated_at",
        "completed_at"
      ],
      "additionalProperties": false,
      "description": "Sanitized partner-user lifecycle operation. Identity values, verification secrets, and audit notes are never returned."
    }
  },
  "required": [
    "request_id",
    "operation"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
get/v1/integrations/{integration}/user-imports/{job_id}

Get bulk import progress and sanitized results

Returns paginated per-user results. Identity data and encrypted work payloads are never returned.

Path and query parameters

integrationpathrequired

Configured public partner name or explicitly authorized provisioning alias. Identity and lifecycle operations use the resolved canonical partner.

integration schema
{
  "type": "string",
  "minLength": 3,
  "maxLength": 64,
  "pattern": "^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$",
  "description": "MG-assigned public integration name or explicitly authorized alias. An alias resolves to the same canonical partner identity, not a new user namespace. Syntax is not authorization: configuration must be active and match the key's organization, linked client, scopes and public-name authorization. Source attribution is server-owned, never caller supplied.",
  "example": "your_assigned_integration"
}
job_idpathrequired

Provisioning import job identifier.

job_id schema
{
  "type": "string",
  "pattern": "^pjob_[A-Za-z0-9_-]{8,80}$",
  "example": "pjob_06f22d7e7137e087"
}
pagequeryoptional
page schema
{
  "type": "integer",
  "exclusiveMinimum": 0,
  "default": 1,
  "example": 1
}
per_pagequeryoptional
per_page schema
{
  "type": "integer",
  "minimum": 1,
  "maximum": 100,
  "default": 100,
  "example": 100
}
cURL
curl \
  --request GET \
  --url 'https://api.mortgageguidelines.com/v1/integrations/your_assigned_integration/user-imports/pjob_06f22d7e7137e087' \
  --header "Authorization: Bearer $API_KEY"

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "job_id": "pjob_06f22d7e7137e087",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "failed": 0,
  "page": 1,
  "per_page": 100,
  "results": [
    {
      "external_user_id": "partner-user-6d55c95f",
      "status": "created"
    },
    {
      "external_user_id": "partner-user-10a3c2b1",
      "status": "matched"
    }
  ]
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "job_id": {
      "type": "string",
      "minLength": 1
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "processing",
        "completed",
        "completed_with_errors"
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 0
    },
    "completed": {
      "type": "integer",
      "minimum": 0
    },
    "failed": {
      "type": "integer",
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "exclusiveMinimum": 0
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "external_user_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "created",
              "matched",
              "failed"
            ]
          },
          "error_code": {
            "type": "string",
            "enum": [
              "identity_conflict",
              "wordpress_unavailable",
              "provisioning_failed",
              "team_not_found",
              "team_archived"
            ]
          }
        },
        "required": [
          "external_user_id",
          "status"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "request_id",
    "job_id",
    "status",
    "total",
    "completed",
    "failed",
    "page",
    "per_page",
    "results"
  ],
  "additionalProperties": false
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Conversations

3 endpoints

post/v1/conversations

Create a conversation explicitly

Creates a conversation before sending any assistant messages. Use this when you need a stable conversation ID up front.

Idempotency

  • `Idempotency-Key` is supported for non-streaming POST requests so that safe retries return the original completed response.

Request body

Conversation creation payload.

Request body example
{
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}
Request body schema
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Optional conversation title.",
      "example": "FHA gift funds"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "description": "Stable identifier from your system for the end user.",
          "example": "user_123"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Optional email address for the external user.",
          "example": "user@example.com"
        },
        "name": {
          "type": "string",
          "description": "Optional display name for the external user.",
          "example": "Test User"
        }
      },
      "required": [
        "external_user_id"
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
      "example": {
        "external_ticket_id": "ticket_789",
        "channel": "crm"
      }
    }
  },
  "required": [
    "user"
  ]
}
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/conversations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: first-turn-user-123-001" \
  -d '{
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "first-turn-user-123-001",
  },
  body: JSON.stringify({
  "title": "FHA gift funds",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "metadata": {
    "external_ticket_id": "ticket_789"
  }
}),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12"
}

Response bodies

201 response schema
201 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12"
}
201 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    }
  },
  "required": [
    "request_id",
    "conversation_id"
  ]
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
get/v1/conversations/{conversationId}

Get a conversation

Returns the conversation metadata for a conversation owned by the authenticated API key.

Path and query parameters

conversationIdpathrequired

Conversation identifier returned by the API.

conversationId schema
{
  "type": "string",
  "minLength": 1,
  "example": "conv_3c2fd2bcf41f4f12"
}
cURL
curl -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12" \
  -H "Authorization: Bearer mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation": {
    "conversation_id": "conv_3c2fd2bcf41f4f12",
    "title": "FHA gift funds",
    "status": "active",
    "created_at": "2025-04-19T18:20:00.000Z",
    "updated_at": "2025-04-19T18:21:30.000Z",
    "message_count": 2,
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  }
}

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation": {
    "conversation_id": "conv_3c2fd2bcf41f4f12",
    "title": "FHA gift funds",
    "status": "active",
    "created_at": "2025-04-19T18:20:00.000Z",
    "updated_at": "2025-04-19T18:21:30.000Z",
    "message_count": 2,
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation": {
      "type": "object",
      "properties": {
        "conversation_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique conversation identifier returned by the API.",
          "example": "conv_3c2fd2bcf41f4f12"
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "example": "FHA gift funds"
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "example": "active"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Timestamp string returned by the backing data store.",
          "example": "2025-04-19T18:20:00.000Z"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Timestamp string returned by the backing data store.",
          "example": "2025-04-19T18:21:30.000Z"
        },
        "message_count": {
          "type": "integer",
          "minimum": 0,
          "example": 2
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "example": {
            "external_ticket_id": "ticket_789"
          }
        }
      },
      "required": [
        "conversation_id",
        "message_count",
        "metadata"
      ]
    }
  },
  "required": [
    "request_id",
    "conversation"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
get/v1/conversations/{conversationId}/messages

List messages in a conversation

Returns the stored messages for a conversation owned by the authenticated API key.

Path and query parameters

conversationIdpathrequired

Conversation identifier returned by the API.

conversationId schema
{
  "type": "string",
  "minLength": 1,
  "example": "conv_3c2fd2bcf41f4f12"
}
cURL
curl -X GET "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Authorization: Bearer mgapi_live_your_key_here"
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages", {
  headers: {
    Authorization: "Bearer mgapi_live_your_key_here",
  },
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "messages": [
    {
      "message_id": "msg_user_123",
      "role": "user",
      "content": "What are FHA gift fund rules?",
      "citations": [],
      "sources": [],
      "metadata": {
        "channel": "crm"
      },
      "created_at": "2025-04-19T18:20:00.000Z"
    },
    {
      "message_id": "msg_1fecc99b7f334e6c",
      "role": "assistant",
      "content": "Gift funds are generally allowed with documentation.",
      "citations": [
        {
          "documentTitle": "Fannie Mae Selling Guide",
          "section": "B3-4.3-04",
          "url": "https://selling-guide.fanniemae.com/",
          "pageNumber": 12
        }
      ],
      "sources": [
        {
          "url": "https://selling-guide.fanniemae.com/",
          "title": "Fannie Mae Selling Guide",
          "description": "Document from selling-guide.fanniemae.com",
          "citationCount": 1
        }
      ],
      "metadata": {
        "tokens_used": 123
      },
      "created_at": "2025-04-19T18:21:30.000Z"
    }
  ]
}

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "messages": [
    {
      "message_id": "msg_user_123",
      "role": "user",
      "content": "What are FHA gift fund rules?",
      "citations": [],
      "sources": [],
      "metadata": {
        "channel": "crm"
      },
      "created_at": "2025-04-19T18:20:00.000Z"
    },
    {
      "message_id": "msg_1fecc99b7f334e6c",
      "role": "assistant",
      "content": "Gift funds are generally allowed with documentation.",
      "citations": [
        {
          "documentTitle": "Fannie Mae Selling Guide",
          "section": "B3-4.3-04",
          "url": "https://selling-guide.fanniemae.com/",
          "pageNumber": 12
        }
      ],
      "sources": [
        {
          "url": "https://selling-guide.fanniemae.com/",
          "title": "Fannie Mae Selling Guide",
          "description": "Document from selling-guide.fanniemae.com",
          "citationCount": 1
        }
      ],
      "metadata": {
        "tokens_used": 123
      },
      "created_at": "2025-04-19T18:21:30.000Z"
    }
  ]
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    },
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string",
            "minLength": 1,
            "description": "Unique message identifier returned by the API.",
            "example": "msg_1fecc99b7f334e6c"
          },
          "role": {
            "type": [
              "string",
              "null"
            ],
            "example": "assistant"
          },
          "content": {
            "type": [
              "string",
              "null"
            ],
            "example": "Gift funds are generally allowed with documentation."
          },
          "citations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "contentKind": {
                  "type": "string",
                  "enum": [
                    "faq"
                  ],
                  "description": "Supplementary agency FAQ guidance; controlling Guide content takes precedence."
                },
                "faqQuestion": {
                  "type": "string"
                },
                "faqPublishedAt": {
                  "type": "string",
                  "description": "Publisher publication date, not a policy effective date."
                },
                "faqUpdatedAt": {
                  "type": "string",
                  "description": "Publisher update date, not a crawl timestamp or policy effective date."
                },
                "documentTitle": {
                  "type": "string",
                  "example": "Fannie Mae Selling Guide"
                },
                "section": {
                  "type": "string",
                  "example": "B3-4.3-04"
                },
                "subsection": {
                  "type": "string",
                  "example": "Personal Gifts"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://selling-guide.fanniemae.com/"
                },
                "pdfUrl": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://selling-guide.fanniemae.com/guide.pdf"
                },
                "pageNumber": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "example": 12
                },
                "pageRangeStart": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "example": 12
                },
                "pageRangeEnd": {
                  "type": "integer",
                  "exclusiveMinimum": 0,
                  "example": 13
                },
                "pageRangeLabel": {
                  "type": "string",
                  "example": "12-13"
                },
                "tenantSourceKey": {
                  "type": "string",
                  "example": "product-guides"
                },
                "tenantSourceLabel": {
                  "type": "string",
                  "example": "Product Guides"
                }
              },
              "additionalProperties": false,
              "description": "Sanitized citation fields for display and source navigation."
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "contentKind": {
                  "type": "string",
                  "enum": [
                    "faq"
                  ],
                  "description": "Supplementary agency FAQ source."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "example": "https://selling-guide.fanniemae.com/"
                },
                "title": {
                  "type": "string",
                  "example": "Fannie Mae Selling Guide"
                },
                "description": {
                  "type": "string",
                  "example": "Document from selling-guide.fanniemae.com"
                },
                "citationCount": {
                  "type": "integer",
                  "minimum": 0,
                  "example": 1
                },
                "tenantSourceKey": {
                  "type": "string",
                  "example": "product-guides"
                },
                "tenantSourceLabel": {
                  "type": "string",
                  "example": "Product Guides"
                }
              },
              "additionalProperties": false,
              "description": "Sanitized source summary fields for display and source navigation."
            }
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {},
            "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
            "example": {
              "external_ticket_id": "ticket_789",
              "channel": "crm"
            }
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "Timestamp string returned by the backing data store.",
            "example": "2025-04-19T18:21:30.000Z"
          }
        },
        "required": [
          "message_id",
          "citations",
          "sources",
          "metadata"
        ]
      }
    }
  },
  "required": [
    "request_id",
    "conversation_id",
    "messages"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}

Messages

2 endpoints

post/v1/messages

Send a message and optionally create the conversation

Creates the conversation when `conversation_id` is omitted, sends the user message, and returns the assistant response.

Idempotency

  • `Idempotency-Key` is supported only for non-streaming requests.
  • Reusing the same key with a different request body returns `409 idempotency_conflict`.

Streaming

  • When `stream: true`, the response content type becomes `text/event-stream`.
  • The first event is `public_api_conversation`, followed by sanitized token, citation, source, and completion events, and then `public_api_complete`.
  • Streaming metadata contains only `tokens_used`.

Request body

First-message payload. Supply `conversation_id` to continue an existing conversation or omit it to create one automatically.

Request body example
{
  "message": "What are FHA gift fund rules?",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "conversation": {
    "title": "FHA gift funds",
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  },
  "metadata": {
    "channel": "crm"
  }
}
Request body schema
{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000,
          "description": "Prompt or question to send to the assistant.",
          "example": "What documentation is required?"
        },
        "user": {
          "type": "object",
          "properties": {
            "external_user_id": {
              "type": "string",
              "minLength": 1,
              "description": "Stable identifier from your system for the end user.",
              "example": "user_123"
            },
            "email": {
              "type": "string",
              "format": "email",
              "description": "Optional email address for the external user.",
              "example": "user@example.com"
            },
            "name": {
              "type": "string",
              "description": "Optional display name for the external user.",
              "example": "Test User"
            }
          },
          "required": [
            "external_user_id"
          ]
        },
        "stream": {
          "type": "boolean",
          "description": "Set to true to receive a text/event-stream response.",
          "example": false
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {},
          "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
          "example": {
            "external_ticket_id": "ticket_789",
            "channel": "crm"
          }
        },
        "search_options": {
          "type": "object",
          "properties": {
            "agency_source_types": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Subset of agency sources to include in this request.",
              "example": [
                "fha",
                "va"
              ]
            },
            "tenant_source_keys": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Subset of tenant bucket sources to include in this request.",
              "example": [
                "product-guides"
              ]
            },
            "shared_source_types": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Subset of shared source types to include in this request.",
              "example": [
                "mortgage_guidelines"
              ]
            }
          }
        }
      },
      "required": [
        "message",
        "user"
      ]
    },
    {
      "type": "object",
      "properties": {
        "conversation_id": {
          "type": "string",
          "minLength": 1,
          "description": "Existing conversation identifier. Omit this to let the API create a new conversation.",
          "example": "conv_3c2fd2bcf41f4f12"
        },
        "conversation": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Optional conversation title used when the API creates a new conversation.",
              "example": "FHA gift funds"
            },
            "metadata": {
              "type": "object",
              "additionalProperties": {},
              "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
              "example": {
                "external_ticket_id": "ticket_789",
                "channel": "crm"
              }
            }
          }
        }
      }
    }
  ]
}
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgapi_live_your_key_here" \
  -H "Idempotency-Key: first-turn-user-123-001" \
  -d '{
  "message": "What are FHA gift fund rules?",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "conversation": {
    "title": "FHA gift funds",
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  },
  "metadata": {
    "channel": "crm"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer mgapi_live_your_key_here",
    "Idempotency-Key": "first-turn-user-123-001",
  },
  body: JSON.stringify({
  "message": "What are FHA gift fund rules?",
  "user": {
    "external_user_id": "user_123",
    "email": "user@example.com",
    "name": "Test User"
  },
  "conversation": {
    "title": "FHA gift funds",
    "metadata": {
      "external_ticket_id": "ticket_789"
    }
  },
  "metadata": {
    "channel": "crm"
  }
}),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "conversation_created": true,
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}
Streaming example
data: {"type":"public_api_conversation","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","conversation_created":true}

data: {"type":"content","content":"Gift funds are generally allowed with "}

data: {"type":"content_postprocessed","content":"Gift funds are generally allowed with documentation."}

data: {"type":"complete","metadata":{"tokens_used":123}}

data: {"type":"public_api_complete","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c"}

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "conversation_created": true,
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    },
    "conversation_created": {
      "type": "boolean",
      "description": "Present only on POST /v1/messages. Indicates whether the API created the conversation during this request.",
      "example": true
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique message identifier returned by the API.",
      "example": "msg_1fecc99b7f334e6c"
    },
    "response": {
      "type": "string",
      "example": "Gift funds are generally allowed with documentation."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contentKind": {
            "type": "string",
            "enum": [
              "faq"
            ],
            "description": "Supplementary agency FAQ guidance; controlling Guide content takes precedence."
          },
          "faqQuestion": {
            "type": "string"
          },
          "faqPublishedAt": {
            "type": "string",
            "description": "Publisher publication date, not a policy effective date."
          },
          "faqUpdatedAt": {
            "type": "string",
            "description": "Publisher update date, not a crawl timestamp or policy effective date."
          },
          "documentTitle": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "section": {
            "type": "string",
            "example": "B3-4.3-04"
          },
          "subsection": {
            "type": "string",
            "example": "Personal Gifts"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "pdfUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/guide.pdf"
          },
          "pageNumber": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeStart": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeEnd": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 13
          },
          "pageRangeLabel": {
            "type": "string",
            "example": "12-13"
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized citation fields for display and source navigation."
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contentKind": {
            "type": "string",
            "enum": [
              "faq"
            ],
            "description": "Supplementary agency FAQ source."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "title": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "description": {
            "type": "string",
            "example": "Document from selling-guide.fanniemae.com"
          },
          "citationCount": {
            "type": "integer",
            "minimum": 0,
            "example": 1
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized source summary fields for display and source navigation."
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "tokens_used": {
          "type": "integer",
          "minimum": 0,
          "description": "Total tokens recorded for the completion.",
          "example": 123
        }
      },
      "required": [
        "tokens_used"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "conversation_id",
    "message_id",
    "response",
    "citations",
    "sources",
    "metadata"
  ]
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
post/v1/conversations/{conversationId}/messages

Send a message to an existing conversation

Sends a user message to an existing conversation and returns the assistant response.

Idempotency

  • `Idempotency-Key` is supported only for non-streaming requests.
  • Matching retries replay the stored JSON response snapshot.

Streaming

  • When `stream: true`, the response content type becomes `text/event-stream`.
  • Existing-conversation streams omit the leading `public_api_conversation` event and always finish with `public_api_complete`.
  • Streaming metadata contains only `tokens_used`.

Path and query parameters

conversationIdpathrequired

Conversation identifier returned by the API.

conversationId schema
{
  "type": "string",
  "minLength": 1,
  "example": "conv_3c2fd2bcf41f4f12"
}

Request body

Message payload for an existing conversation.

Request body example
{
  "message": "What documentation is required?",
  "user": {
    "external_user_id": "user_123"
  }
}
Request body schema
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "Prompt or question to send to the assistant.",
      "example": "What documentation is required?"
    },
    "user": {
      "type": "object",
      "properties": {
        "external_user_id": {
          "type": "string",
          "minLength": 1,
          "description": "Stable identifier from your system for the end user.",
          "example": "user_123"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Optional email address for the external user.",
          "example": "user@example.com"
        },
        "name": {
          "type": "string",
          "description": "Optional display name for the external user.",
          "example": "Test User"
        }
      },
      "required": [
        "external_user_id"
      ]
    },
    "stream": {
      "type": "boolean",
      "description": "Set to true to receive a text/event-stream response.",
      "example": false
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Customer-supplied metadata. Reserved internal keys may be stored for operations but are not echoed in public responses.",
      "example": {
        "external_ticket_id": "ticket_789",
        "channel": "crm"
      }
    },
    "search_options": {
      "type": "object",
      "properties": {
        "agency_source_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Subset of agency sources to include in this request.",
          "example": [
            "fha",
            "va"
          ]
        },
        "tenant_source_keys": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Subset of tenant bucket sources to include in this request.",
          "example": [
            "product-guides"
          ]
        },
        "shared_source_types": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Subset of shared source types to include in this request.",
          "example": [
            "mortgage_guidelines"
          ]
        }
      }
    }
  },
  "required": [
    "message",
    "user"
  ]
}
cURL
curl -X POST "https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mgapi_live_your_key_here" \
  -H "Idempotency-Key: follow-up-user-123-001" \
  -d '{
  "message": "What documentation is required?",
  "user": {
    "external_user_id": "user_123"
  }
}'
TypeScript fetch
const response = await fetch("https://api.mortgageguidelines.com/v1/conversations/conv_3c2fd2bcf41f4f12/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "mgapi_live_your_key_here",
    "Idempotency-Key": "follow-up-user-123-001",
  },
  body: JSON.stringify({
    message: "What documentation is required?",
    user: {
      external_user_id: "user_123",
    },
  }),
});

const data = await response.json();
Example response
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}
Streaming example
data: {"type":"content","content":"The conversation can continue using the existing ID."}

data: {"type":"complete","metadata":{"tokens_used":88}}

data: {"type":"public_api_complete","request_id":"req_9b8f0b5fcb5b4eaa","conversation_id":"conv_3c2fd2bcf41f4f12","message_id":"msg_1fecc99b7f334e6c"}

Response bodies

200 response schema
200 example
{
  "request_id": "req_9b8f0b5fcb5b4eaa",
  "conversation_id": "conv_3c2fd2bcf41f4f12",
  "message_id": "msg_1fecc99b7f334e6c",
  "response": "Gift funds are generally allowed with documentation.",
  "citations": [
    {
      "documentTitle": "Fannie Mae Selling Guide",
      "section": "B3-4.3-04",
      "url": "https://selling-guide.fanniemae.com/",
      "pageNumber": 12
    }
  ],
  "sources": [
    {
      "url": "https://selling-guide.fanniemae.com/",
      "title": "Fannie Mae Selling Guide",
      "description": "Document from selling-guide.fanniemae.com",
      "citationCount": 1
    }
  ],
  "metadata": {
    "tokens_used": 123
  }
}
200 schema
{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique request identifier returned by the API.",
      "example": "req_9b8f0b5fcb5b4eaa"
    },
    "conversation_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique conversation identifier returned by the API.",
      "example": "conv_3c2fd2bcf41f4f12"
    },
    "conversation_created": {
      "type": "boolean",
      "description": "Present only on POST /v1/messages. Indicates whether the API created the conversation during this request.",
      "example": true
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "Unique message identifier returned by the API.",
      "example": "msg_1fecc99b7f334e6c"
    },
    "response": {
      "type": "string",
      "example": "Gift funds are generally allowed with documentation."
    },
    "citations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contentKind": {
            "type": "string",
            "enum": [
              "faq"
            ],
            "description": "Supplementary agency FAQ guidance; controlling Guide content takes precedence."
          },
          "faqQuestion": {
            "type": "string"
          },
          "faqPublishedAt": {
            "type": "string",
            "description": "Publisher publication date, not a policy effective date."
          },
          "faqUpdatedAt": {
            "type": "string",
            "description": "Publisher update date, not a crawl timestamp or policy effective date."
          },
          "documentTitle": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "section": {
            "type": "string",
            "example": "B3-4.3-04"
          },
          "subsection": {
            "type": "string",
            "example": "Personal Gifts"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "pdfUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/guide.pdf"
          },
          "pageNumber": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeStart": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 12
          },
          "pageRangeEnd": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "example": 13
          },
          "pageRangeLabel": {
            "type": "string",
            "example": "12-13"
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized citation fields for display and source navigation."
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contentKind": {
            "type": "string",
            "enum": [
              "faq"
            ],
            "description": "Supplementary agency FAQ source."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://selling-guide.fanniemae.com/"
          },
          "title": {
            "type": "string",
            "example": "Fannie Mae Selling Guide"
          },
          "description": {
            "type": "string",
            "example": "Document from selling-guide.fanniemae.com"
          },
          "citationCount": {
            "type": "integer",
            "minimum": 0,
            "example": 1
          },
          "tenantSourceKey": {
            "type": "string",
            "example": "product-guides"
          },
          "tenantSourceLabel": {
            "type": "string",
            "example": "Product Guides"
          }
        },
        "additionalProperties": false,
        "description": "Sanitized source summary fields for display and source navigation."
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "tokens_used": {
          "type": "integer",
          "minimum": 0,
          "description": "Total tokens recorded for the completion.",
          "example": 123
        }
      },
      "required": [
        "tokens_used"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "request_id",
    "conversation_id",
    "message_id",
    "response",
    "citations",
    "sources",
    "metadata"
  ]
}
400 response schema
400 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
400 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
401 response schema
401 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
401 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
403 response schema
403 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
403 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
404 response schema
404 example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
404 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
409 response schema
409 example
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency key was reused with a different request body",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
409 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
429 response schema
429 example
{
  "error": {
    "code": "rate_limited",
    "message": "API key rate limit exceeded",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
429 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
500 response schema
500 example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
500 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}
502 response schema
502 example
{
  "error": {
    "code": "upstream_error",
    "message": "Upstream service unavailable",
    "request_id": "req_9b8f0b5fcb5b4eaa"
  }
}
502 schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_request",
            "unauthorized",
            "forbidden",
            "not_found",
            "rate_limited",
            "idempotency_conflict",
            "identity_conflict",
            "team_not_found",
            "team_archived",
            "team_in_use",
            "upstream_error",
            "internal_error"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message.",
          "example": "Invalid request body"
        },
        "request_id": {
          "type": "string",
          "minLength": 1,
          "description": "Unique request identifier returned by the API.",
          "example": "req_9b8f0b5fcb5b4eaa"
        }
      },
      "required": [
        "code",
        "message",
        "request_id"
      ]
    }
  },
  "required": [
    "error"
  ]
}