MortgageGuidelines API

Getting Started

Send your first request and understand the core workflow.

Getting Started

The public API supports direct server-to-server chat and embedded partner experiences:

  1. Use POST /v1/messages to create a conversation automatically on the first message.
  2. Use POST /v1/conversations first when your integration needs the conversation ID before the first assistant response.
  3. For embedded chat, provision the external user through /v1/integrations/{integration}/users/{external_user_id}, then create a one-time launch through POST /v1/embed-sessions.

Base URL

https://api.mortgageguidelines.com

For most integrations, start with POST /v1/messages.

Responses include the fields needed by integrations: request and conversation identifiers, answer text, sanitized citations, sanitized source summaries, and metadata.tokens_used. Internal model, provider, prompt, retrieval, and service configuration details are not returned.

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"
  }
}'
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
  }
}

Use the Postman collection

Import the current Postman Collection into Postman. It includes every public API route, JSON request and response examples, and streaming message requests.

Set the collection variables for your requests:

VariableValue
baseUrlhttps://api.mortgageguidelines.com
apiKeyYour server-only API key with the scopes required by the request
partnerIntegrationThe exact integration identifier assigned during onboarding
partnerExternalTeamIdYour team's opaque external_team_id
partnerExternalUserIdThe immutable opaque partner user ID from your system

Partner variables are needed for partner-integration requests. Other variables, such as conversationId, hold identifiers returned by the API. Check the request's description for its required scopes and headers.

In the base requests, optional filters appear unchecked in the Params tab; pagination defaults are enabled. Enable the filters you need and set their values before sending. In Partner Users → List partner users, enable team_external_id to list a team's users and add external_user_id to check one user in that team. The saved requests List users in a team and Find a user in a team have those filters enabled. Do not combine q with external_user_id, or unassigned=true with team_external_id.

See List users for a team for matching behavior, pagination, and the meaning of response counts. Download the collection again after a documentation update to import the latest requests and parameters.

Next steps