MC Rate Quote Integration API Guide
Welcome to the Mortgage Connect Rate Quote Integration API Guide.
The Mortgage Connect Rate Quote Integration API Guide provides specifications and details for building direct Rate Quote integrations with clients, service providers, and other parties that intend to leverage Mortgage Connect's API platform.
The benefits of becoming an integrated partner are:
- Reliable message transfer and data integrity
- A common façade that provides a single and consistent access interface
- Data rich API responses
- Integration monitoring and real-time notifications
- Reporting capabilities
- Fast response times to address service-level agreements (SLA)
- Etc.
The Integration API is implemented using a REST API (a.k.a. RESTful API) that supports both JSON and XML payloads. With the definitions, features, and requirements outlined in this API Guide, clients will be empowered to submit Rate Quote requests and if applicable, get information and statuses regarding the different stages of rate quote fulfillment. This guide includes, but is not limited to the following information:
- Authentication requirements
- Identifying message types
- Example payloads in JSON and XML
- Message workflow orchestration
- Required vs optional fields
- Field data types and constraints
- Field enumeration requirements
- Environment and endpoint addresses
- Terms and definitions
- Onboarding checklist
- Etc.
Introduction
To get the most benefit from the Rate Quote Integration API Guide it is best to first familiarize yourself with the general layout, navigation, and features of the site. The following sections will highlight the general layout and navigation features in addition to any general nomenclatures and terms used throughout the API Guide.
Layout & Navigation
The following sections define the layout and navigation features of this API guide.
Browser Support
This site has only been tested using Google Chrome. The use of any other browser may result in unexpected rendering issues and/or functional limitations.
Menu
Under the Mortgage Connect logo in the far upper left side of the document is where you will find the menu and navigation features supported by this API Guide.
The menu is an intuitive collapsable collection of items that once clicked, navigate the user to the associated section of the API Guide.
The menu also supports a search feature at the very top of the navigation section. Entering a value in the search bar will filter the menu items to only show those whose content contains the entered search value.
Content
The middle section of the API Guide is where you will find specific details regarding the menu item that was selected. Also note that you do not have to use the menu to navigate to specific content of interest because you can continuously scroll down the page and the navigation menu will track where you are located.
Examples
The far right side of the API Guide is where you will find more technical details including actual payload examples in JSON and XML. Where technical examples are not applicable, the right side pane will be empty in relationship to the current section the user is on.
In future iterations of this API Guide the "csharp" and "javascript" tabs at the top of the right pane will enable you toggle between referencing actual code examples that invoke the referenced API method.
Action Buttons
The site also supports actionable buttons that provide additional functionality. When you see the following action buttons the corresponding action will be taken when the button is clicked.
| Button | Action |
|---|---|
 |
When you see the button, this means that when it is clicked the site will scroll to the corresponding transaction in the Rate Quote API Workflow Orchestration page. |
 |
When you see the button, this means that when it is clicked it will navigate the user to either the Transaction Header or Transaction Extensions property definitions section on the Rate Quote API Message Structure page. |
 |
When you see the button, this means that when it is clicked it will toggle the collapsing and expanding of the corresponding JSON or XML example. |
 |
When you see the button, this means that when it is clicked it will copy the corresponding JSON or XML to the clipboard. This is applicable to JSON and XML HTTP Requests, Acknowledgments, and Schemas. |
 |
When you see the button, this means that when it is clicked it will navigate you to the corresponding sections to view the JSON or XML example. |
Schemas
While still a work in progress, some schema validation files can be found throughout this documentation. Schema files are typically very large in comparison to the actual JSON or XML payload they are validating. In addition, they are much more technical in nature and thus are not easily read. It is for this reason you will notice that schema file examples will have scrollable regions, so as to cut down on the vertical scrolling required to navigate the site. Actual payload examples, will not have scrollable regions.
Nomenclatures & Legends
The following sections define specific nomenclatures used throughout the API Guide along with any specific legends or codes for reference.
Directional Indicator Definitions
Throughout the API Guide you will see images of arrows. These are used to quickly and visually determine the direction of an API message. Direction in this context refers to who is initiating the method and who is receiving it.
| Directional Indicator | Description |
|---|---|
| → | Indicates that the API message is an inbound message. Which is to say it is sent by the Client to Mortgage Connect. |
| ← | Indicates that the API message is an outbound message. Which is to say it is sent by Mortgage Connect to the Client. |
| ⇄ | Indicates that the API message is an inbound and outbound message (i.e. bidirectional). Which is to say it can be sent by either the Client or Mortgage Connect. |
Property Definitions
Throughout the API Guide you will find Property Definition tables that define the requirements per property in reference to the JSON or XML supporting a specific API Method. One column of interest is the "Requirement" column whose state is represented by the following values.
| Code | Term | Description |
|---|---|---|
| R | Required | Indicates that the property is mandatory and is required to be present in the JSON or XML at all times. |
| O | Optional | Indicates that the property is optional and may or may not be present in the JSON or XML. |
| C | Conditional | Indicates that the property is conditionally required, which is typically dependent on which additional metadata in the request that provides additional context. |
If space permits the Term will always be used, however where screen real estate is at a premium, the Code will be used.
In addition, the property definition tables contained throughout this document will have property names that are highlighted in blue. This is nothing more than a visual cue to distinguish objects and arrays from general properties in the JSON and XML payloads, with the hope that it makes it quicker to find these sections in the documentation.
NULL Values
An optional collection or property by definition implies that there values may be null. By convention, it is standard for null collections or properties to not exist in the physical payload when they are null and the client should code accordingly for this scenario. Note that in some circumstances you may see null properties returned as empty strings instead of nulls and if the field is optional the client should subsequently treat it as null or an empty string at their discretion.
Authentication
The following sections provide implementation details regarding the default authentication mechanisms supported by the Integration API.
Token-Based Authentication
Authentication by default is handled via JSON Web Tokens (JWTs), also known as Token-Based Authentication.
JSON Web Token Overview
JSON Web Tokens (JWTs) are commonly used as tokens in token-based authentication systems, where the client authenticates with the server by exchanging credentials for a JWT.
The server then verifies the JWT to authenticate the client and grants access if successful.
Token-based authentication is a stateless authentication mechanism, meaning that the server does not need to store session information for each client. Instead, the client includes the JWT in subsequent requests to the server for authentication. The server validates the JWT's integrity and authenticity by checking the signature and expiration, allowing the client to access protected resources if the verification is successful.
It provides a compact and self-contained way of securely transmitting information between parties as a JSON object. For more details: JSON Web Token - Wiki
JSON Web Token Components
JWTs are compact, URL-safe tokens that can be used for secure communication between parties. They are commonly used in web applications and APIs. A JWT consist of three components:
a Header, a Payload, and a Signature. The header specifies the algorithm used for signing the token, while the payload contains the claims or information about the user or system.
While the digitally signed signature ensures the integrity and authenticity of the token, thus allowing the server to verify the authenticity of the token and ensure that it has not
been tampered with.
Token-Based Authentication Handshake
Token-based authentication using JWTs involves the following steps:
- Client Authentication: The client authenticates with the server by providing their assigned credentials, i.e. username and password. The client must send a request to a specific authentication endpoint, providing the necessary credentials. The specific endpoint per environment will be shared during the onboarding process.
- Token Issuance: Upon successful authentication, the server will generate a signed JWT and issues it to the client. A JWT is generated by combining the
Header,Payload, andSignature, using a secret key. The secret key is used to sign the JWT and ensure its integrity. The JWT serves as proof of authentication and is returned to the client in the response body. - Token Inclusion: The client is responsible for storing the JWT in a secure storage mechanism, such as local storage or a cookie. The client must then include the JWT in subsequent requests to the server. This can be done by adding the token to the request headers or as part of the request payload. Mortgage Connect's default implementation requires that the JWT be included in the
Authenticationheader using the Bearer authentication scheme. See theBearer Specificationsection for more details. - Token Verification: The server verifies the JWT to authenticate the client. It verifies the token's integrity by checking the signature using the secret key, and ensures the token has not expired, and validates any other necessary claims. This process ensures that the token has not been tampered with.
- Access Granted: If the verification is successful and the token has not expired, the server grants access to the requested resources or performs the requested actions.
- Access Denied: If the verification is unsuccessful or the token has expired, then the server will deny access to the requested resources and return a 401 HTTP status code.
- Token Expiration: If the token has expired, the server will deny access to the requested resources and return a 401 HTTP status code. The client must reauthenticate and use the newly issued JWT in subsequent requests.
Token-Based Authentication Orchestration
The following visual representation depicts the interactions between the client and the server during authentication.
Handling Token Expiration and Refresh
Token expiration and refresh are important considerations in JWT-based authentication:
Token Expiration: To handle token expiration, an expiration time is set in the JWT. The server checks the expiration time to determine if the token is still valid. If the token has
expired, the server denies access and requires the client to obtain a new token by authenticating again.
Token Refresh: Mortgage Connect does not currently support refresh tokens. In order to refresh an expired token, the client must reauthenticate and acquire a new token.
Bearer Specification
The Bearer specification is used to process JSON Web Tokens (JWTs) in the Authorization header. It provides a stateless authentication mechanism for accessing protected routes
and resources. When a user wants to access a protected route or resource, the user agent sends the JWT in the Authorization header using the Bearer schema. The content of the
header should look like the following: Authorization: Bearer <JWT>, where <JWT> is replaced with JWT returned when authenticating. The server's protected routes then check
for a valid JWT in the Authorization header, and if it's present, valid, and not expired, the user is allowed to access the protected resources.
Bearer Tokens are the predominant type of access token used with OAuth 2.0. They are opaque strings that are not intended to have any meaning to clients using them.
Beyond Passwords
Mortgage Connect has embraced JSON Web Tokens as the default authentication mechanism for its API platform. However, Mortgage Connect is keenly aware of a need for yet
even stronger authentication mechanisms given the increased reliance on digital systems and the rise of cyber threats. This is why Mortgage Connect is so diligent in following
and keeping up with industry standards as it relates to authentication. While passwords are commonly used for authentication, there is a growing need for additional authentication
technologies. Passwords alone may not provide sufficient security, as they can be vulnerable to various attacks. Multi-factor Authentication (MFA) and Biometrics are examples
of alternative methods that enhance security. Subsequently, Mortgage Connect's authentication schema is always evaluated in order to provide the most secure solution while
weighing the capabilities and reasonable technical hurdles of their Clients.
Rate Quote API
The following sections detail the Rate Quote API methods that are specific to Mortgage Connect's provided services.
Rate Quote - API Event Matrix
The following matrix details the API event matrix supported by the Rate Quote API. The EventId is an internal Mortgage Connect code that the individual methods are often referenced by.
Client & Mortgage Connect Acknowledgments
The Integration Rate Quote workflow orchestration currently supports the following acknowledgment events.
While technically speaking an Acknowledgment response is not an event, it is being loosely grouped in this category for documentation purposes.
| EventId | Event Code | HTTP | Description |
|---|---|---|---|
| RQ010 ⇄ | Acknowledgment | POST | The Acknowledgment response is the mechanism in which the Client and Mortgage Connect can communicate that a message was processed successfully or failed. In addition, exception information can be returned as well if applicable. These are essentially the response payloads returned in response to a request and are virtually the same for each request with a couple deviations that are outlined in the RQ010 - Acknowledgment section. All events whether initiated by the Client or Mortgage Connect should return a RQ010 Acknowledgment message.View Details |
Client Initiated Events
The Integration Rate Quote workflow orchestration currently supports the following events that are to be initiated by the Client LOS and sent to the Mortgage Connect Integration API.
flowchart LR Client(Client LOS) -- POST --> API(MC Integration API)| EventId | Event Code | HTTP | Description |
|---|---|---|---|
| RQ050 → | Authenticate | POST | The Authenticate API method is the mechanism in which a Client authenticates their credentials and obtains a JSON Web Toke (JWT) for subsequent requests.View Details |
| RQ100 → | Rate Quote | POST | The Rate Quote API method is the mechanism in which a Client submits a request to Mortgage Connect for a rate quote.View Details |
Rate Quote - API Message Structure
✅ The following is an example 'Message Envelope'.
/* Copyright © 2024 Mortgage Connect LP */
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
/* Message Type Specific Metadata Goes Here */
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<!-- Message Type Specific Metadata Goes Here -->
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->All messages are wrapped in a parent MortgageConnect object which serves as the Message Envelope for each message's metadata.
Within the Message Envelope you will find three (3) root level objects.
- Transaction Header (transactionHeader)
- Transaction Body (transactionBody)
- Transaction Extensions (transactionExtensions)
The Transaction Header and Transaction Extensions are identical for every message and thus will be documented here to eliminate redundancy.
References to this section will be found in the corresponding sections of each supported message type.
The Transaction Body on the other hand is message type specific and will be documented separately in a section dedicated to each supported message type.
Property Definitions - Transaction Header
Defines the properties represented in the Transaction Header object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| transactionHeader | Required | A parent object (JSON) or node (XML) that contains the transaction header metadata. | ||
| transactionIdempotentId | Conditional | GUID | A new globally unique identifier to be generated per every single response. This value is used to ensure transactions are processed idempotently. Idempotent message identification is NOT currently implemented. However, when a need for this feature bubbles up to the top and it is added to the development pipeline it will work as follows. The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a new order does not respond due to a network connection error, you can retry the request with the same idempotency Id to guarantee that no more than one order is created. Idempotency works by saving the resulting status code and body of the first request made for any given idempotency Id, regardless of whether it succeeded or failed. Subsequent requests with the same idempotency Id will return the same result, including 500 errors. An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. Idempotent Ids should be GUIDs to ensure uniqueness. Under consideration is also the ability to expire previously processed idempotent Ids, for example ignoring those that are 24 hours old or more. Thus enabling the same transaction to be sent again. Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests. All POST requests will accept idempotency keys. Sending idempotent Id in GET and DELETE requests has no effect, as these requests are idempotent by definition. |
|
| transactionDate | Required | DateTime | The date and time that is associated with the message request. | |
| clientCode | Required | String | This represents Mortgage Connect's client code which uniquely identifies a client. Internally Mortgage Connect often refers to this property as the ClientId. |
|
| clientName | Required | String | 1 / 100 | This represents the name associated with the client. It is not uncommon for multiple clients, i.e. ClientCode(s) to be grouped under the same parent client and thus this field often reflects the parent name instead of individual branch names. |
| vendorCode | Required | String | 1 / 100 | A code supplied by Mortgage Connect that uniquely identifies the Integration Platform Instance or Tenant being used to service the integration. |
| vendorName | Required | String | 1 / 100 | A name supplied by Mortgage Connect that uniquely identifies the Integration Platform Instance or Tenant being used to service the integration. |
Property Definitions - Transaction Body
Defines the properties represented in the Transaction Body object (JSON) or node (XML).
Property Definitions - Transaction Extensions
Defines the properties represented in the TransactionExtensions object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| transactionExtensions | Optional | A parent object (JSON) or node (XML) that contains a list of transaction extensions. (0 to Many). |
||
| transactionExtension | Required | A parent object (JSON) or node (XML) that contains the metadata associated with a transaction extension. | ||
| key | Required | String | 1 / 200 | The key (i.e. name) that uniquely identifies the transaction extension. |
| value | Required | String | 1 / MAX | The value that is associated with the transaction extension. |
Rate Quote - API Workflow Orchestration
The following sections provide a graphical overview of the typical Rate API workflow, from an API sequencing and orchestration perspective.
Rate Quote - RQ010 - Acknowledgment
✅ The following is an 'Accepted' example payload to be returned in the HTTP response.
/* Copyright © 2024 Mortgage Connect LP */
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Acknowledgment",
"ackStatus": "true",
"ackMessage": "Accepted",
"ackException": "",
"responseType": "",
"response": ""
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Acknowledgment</transactionCode>
<ackStatus>true</ackStatus>
<ackMessage>Accepted</ackMessage>
<ackException></ackException>
<responseType></responseType>
<response></response>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->⛔ The following is a 'Rejected' example payload to be returned in the HTTP response.
/* Copyright © 2024 Mortgage Connect LP */
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Acknowledgment",
"ackStatus": "false",
"ackMessage": "Rejected",
"ackException": "Invalid Underwriter",
"responseType": "",
"response": ""
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Acknowledgment</transactionCode>
<ackStatus>false</ackStatus>
<ackMessage>Rejected</ackMessage>
<ackException>Invalid Underwriter</ackException>
<responseType></responseType>
<response></response>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->👍 The response payload can be verified using the following validation schema.
The response payload JSON schema validation is under construction. 🚧The response payload XML schema validation is under construction. 🚧The Acknowledgment event is essentially the payload that is to be returned by all HTTP requests whether it was initialized by the Client or Mortgage Connect.
Simply put, it is the response payload that is to be returned after every request and is used to indicate whether the operation was a success or failure, along with exception information if applicable.
flowchart RL API(MC Integration API) <-- POST --> Client(Client LOS)Property Definitions - Transaction Header
Defines the properties represented in the Transaction Header object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
View Transaction Header Details
Property Definitions - Transaction Body
Defines the properties represented in the Transaction Body object (JSON) or node (XML).
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| transactionBody | Required | A parent object (JSON) or node (XML) that contains the transaction metadata. | ||
| transactionCode | Required | String | 14 / 14 | A static value of Acknowledgment. The transaction code is meant to identify the message type and the context or action that should be taken. An Acknowledgment transaction code is unique from all other transaction codes in that the context is actually derived from the value of the AckStatus property. Possible Values:
|
| ackStatus | Required | Boolean | A boolean code indicating whether the request message was successfully processed. This is the property you should interrogate to determine if the message was successful or a failure. Note that booleans are actually returned as strings. Possible Values:
|
|
| ackMessage | Required | String | 1 / MAX | A message indicating whether the request message was successfully processed. This property is typically just populated with Success or Failure. However, it can optionally be populated with additional metadata that provides additional context as to why it was a successful or failed message. It is for this reason you should key off of the ackStatus field to determine whether it was a successful or failed message. Typical Values:
|
| ackException | Conditional | String | 0 / MAX | A message that provides additional exception details in the event the message was not successfully processed. |
| responseType | Conditional | String | 0 / MAX | The requested action has returned a response object of the type specified by this property's value. |
| response | Conditional | Object | A JSON or XML representation of the response object. |
Property Definitions - Transaction Extensions
Defines the properties represented in the TransactionExtensions object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
View Transaction Extension Details
Rate Quote - RQ050 - Authenticate
🌐 The following is an example payload to be posted in the body of the HTTP request.
/* Copyright © 2024 Mortgage Connect LP */
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Authenticate",
"username": "AcmeInc123",
"password": "7#^sdMnB4v#(h)"
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc123</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Authenticate</transactionCode>
<username>AcmeInc1</username>
<password>7#^sdMnB4v#(h)</password>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->👍 The request payload can be verified using the following validation schema.
/* Copyright © 2024 Mortgage Connect LP */
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "root",
"description": "Copyright @ 2024 Mortgage Connect LP - Title & Tax Schema.",
"type": "object",
"additionalProperties": false,
"properties": {
"legalHeader": {
"type": "object",
"additionalProperties": false,
"properties": {
"version": {
"examples": [
"1.0.9.0"
],
"type": "string",
"minLength": 1,
"maxLength": 20
},
"disclosingParty": {
"examples": [
"Copyright @ 2024 Mortgage Connect LP"
],
"type": "string",
"minLength": 1,
"maxLength": 100
},
"proprietaryInformationAndConfidential": {
"examples": [
"Ownership of Proprietary Information. The Recipient agrees that it shall not receive any right, title or interest, or any license or right to use, the Disclosing Party's Proprietary Information, including, but not limited to, technology, ideas, concepts, drawings, documentation, designs, prototypes, processes, trade secrets, trademarks or other intellectual property rights therein, by implication or otherwise."
],
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"version",
"disclosingParty",
"proprietaryInformationAndConfidential"
],
"minProperties": 3,
"maxProperties": 3
},
"transactionHeader": {
"type": "object",
"additionalProperties": false,
"properties": {
"transactionIdempotentId": {
"examples": [
"90039F81-73C1-4788-98BC-90553888D301"
],
"type": "string",
"minLength": 36,
"maxLength": 36,
"pattern": "^[\\da-fA-F]{8}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{12}$"
},
"transactionDate": {
"examples": [
"2024-04-11T02:03:40"
],
"type": "string",
"format": "date-time"
},
"clientCode": {
"examples": [
"1799"
],
"type": "string",
"minLength": 1,
"maxLength": 100,
"format": "integer"
},
"clientName": {
"examples": [
"AcmeInc"
],
"type": "string",
"minLength": 1,
"maxLength": 100
},
"vendorCode": {
"examples": [
"MC"
],
"type": "string",
"minLength": 1,
"maxLength": 100
},
"vendorName": {
"examples": [
"Mortgage Connect"
],
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"transactionIdempotentId",
"transactionDate",
"clientCode",
"clientName",
"vendorCode",
"vendorName"
],
"minProperties": 6,
"maxProperties": 6
},
"transactionBody": {
"type": "object",
"additionalProperties": false,
"properties": {
"transactionCode": {
"examples": [
"Authenticate"
],
"type": "string",
"const": "Authenticate"
},
"username": {
"examples": [
"AcmeInc123"
],
"type": "string",
"minLength": 1,
"maxLength": 50
},
"password": {
"examples": [
"7#^sdMnB4v#(h)"
],
"type": "string",
"minLength": 1,
"maxLength": 50
}
},
"required": [
"transactionCode",
"username",
"password"
]
},
"transactionExtensions": {
"type": "object",
"properties": {
"transactionExtension": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"examples": [
"Client Specific Key"
],
"type": "string",
"minLength": 1,
"maxLength": 200
},
"value": {
"examples": [
"Client Specific Value"
],
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"value"
],
"minProperties": 2,
"maxProperties": 2
},
"minItems": 0
}
}
}
},
"required": [
"transactionHeader",
"transactionBody"
],
"minProperties": 2,
"maxProperties": 4
}
/* Copyright © 2024 Mortgage Connect LP */The request payload XML schema validation is under construction. 🚧✅ The following is an 'Accepted' example payload to be returned in the HTTP response.
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Acknowledgment",
"ackStatus": "true",
"ackMessage": "Accepted",
"ackException": "",
"responseType": "AuthenticateResponse",
"response": {
"statusType": 1,
"statusMessage": "Authorized, valid username and password was accepted.",
"jsonWebToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImFpLWFwaS11c2VyLWRldmVsb3BtZW50IiwianRpIjoiNzBkNTZlNzktZDQ0ZS00MmI5LWEwZTMtM2YzOGIwNTQxYjllIiwibmJmIjoxNzE1MDA3NTY1LCJleHAiOjE3MTUwMjkxNjUsImlhdCI6MTcxNTAwNzU2NSwiaXNzIjoiaHR0cDovL2FpLWlzc3Vlci5tb3J0Z2FnZWNvbm5lY3RscC5jb20iLCJhdWQiOiJodHRwOi8vYWktYXVkaWVuY2UubW9ydGdhZ2Vjb25uZWN0bHAuY29tIn0.5PxEOFR_1aD0CgNtUyPFBV7USMKd7TicijBDoA_BK2tyE46edZV1azpSODIr0fx3xaRPiUZrONS6h87o0NQiJQ",
"jsonWebTokenValidFrom": "2024-05-06T14:59:25Z",
"jsonWebTokenValidTo": "2024-05-06T20:59:25Z"
}
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc123</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Acknowledgment</transactionCode>
<ackStatus>true</ackStatus>
<ackMessage>Accepted</ackMessage>
<ackException></ackException>
<responseType>AuthenticateResponse</responseType>
<response>
<statusType>1</statusType>
<statusMessage>Authorized, valid username and password was accepted.</statusMessage>
<jsonWebToken>eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImFpLWFwaS11c2VyLWRldmVsb3BtZW50IiwianRpIjoiNzBkNTZlNzktZDQ0ZS00MmI5LWEwZTMtM2YzOGIwNTQxYjllIiwibmJmIjoxNzE1MDA3NTY1LCJleHAiOjE3MTUwMjkxNjUsImlhdCI6MTcxNTAwNzU2NSwiaXNzIjoiaHR0cDovL2FpLWlzc3Vlci5tb3J0Z2FnZWNvbm5lY3RscC5jb20iLCJhdWQiOiJodHRwOi8vYWktYXVkaWVuY2UubW9ydGdhZ2Vjb25uZWN0bHAuY29tIn0.5PxEOFR_1aD0CgNtUyPFBV7USMKd7TicijBDoA_BK2tyE46edZV1azpSODIr0fx3xaRPiUZrONS6h87o0NQiJQ</jsonWebToken>
<jsonWebTokenValidFrom>2024-05-06T14:59:25Z</jsonWebTokenValidFrom>
<jsonWebTokenValidTo>2024-05-06T20:59:25Z</jsonWebTokenValidTo>
</response>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->⛔ The following is a 'Rejected' example payload to be returned in the HTTP response.
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Acknowledgment",
"ackStatus": "false",
"ackMessage": "Rejected",
"ackException": "",
"responseType": "AuthenticateResponse",
"response": {
"statusType": 2,
"statusMessage": "Unauthorized, invalid username and/or password was rejected.",
"jsonWebToken": null,
"jsonWebTokenValidFrom": null,
"jsonWebTokenValidTo": null
}
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc123</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Acknowledgment</transactionCode>
<ackStatus>false</ackStatus>
<ackMessage>Rejected</ackMessage>
<ackException></ackException>
<responseType>AuthenticateResponse</responseType>
<response>
<statusType>2</statusType>
<statusMessage>Unauthorized, invalid username and/or password was rejected.</statusMessage>
<jsonWebToken></jsonWebToken>
<jsonWebTokenValidFrom></jsonWebTokenValidFrom>
<jsonWebTokenValidTo></jsonWebTokenValidTo>
</response>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->The Authenticate API method is the mechanism in which a Client can submit a message to Mortgage Connect to authenticate their credentials and acquire a
JSON Web Token (JWT) for subsequent requests.
View Workflow Orchestration
Mortgage Connect URL
POST 🔒 https://{BaseUrl}/Api/V1.0/SubmitMessage
Mortgage Connect URL Properties
Defines the dynamic properties in the URL (i.e. those enclosed in curly brakets {}) that are used to uniquely identify the targeted endpoint. The actual property values will be determined during the onboarding process, however you can reference the Environments section to acquaint yourself with the standard BaseUrls exposed by Mortgage Connect.
| Property | Requirement | Description |
|---|---|---|
| BaseUrl | Required | A unique base Url that represents a specific Mortgage Connect endpoint and targeted environment. |
Passing User Credentials In Headers VS Posted Payload Body
Mortgage Connect supports two mechanisms for the Client to send their credentials, when submitting a RQ050 - Authenticate request, i.e. Headers and Posted Payload Body.
Headers
If using headers you must add the following header values to your request and populate their values accordingly.
| Header Key | Header Value | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|---|
| TBD | Required | String | 1 / 50 | A header with a key value of x-username and whose value is set to the Username assigned to the Client by Mortgage Connect during the onboarding process. |
|
| TBD | Required | String | 1 / 50 | A header with a key value of x-password and whose value is set to the Password assigned to the Client by Mortgage Connect during the onboarding process. |
Technical, details regarding adding these headers to the request are outside the scope of this document, as those details are specific to the technologies and stack being used by the Client.
Example With Headers Being Set In Postman
Posted Payload Body
When using the Posted Payload Body to authenticate you must populate the username and password properties of the transactionBody in the message envelope.
All of the example payloads in the right most column are all populated as if the Client wishes to use the Posted Payload Body mechanism for authenticating.
Setting the corresponding properties of the transactionBody is very straight forward from an implementation perspective.
| Property | Value | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|---|
| username | TBD | Required | String | 1 / 50 | A property whose value is set to the Username assigned to the Client by Mortgage Connect during the onboarding process. |
| password | TBD | Required | String | 1 / 50 | A property whose value is set to the Password assigned to the Client by Mortgage Connect during the onboarding process. |
Property Definitions - Transaction Header
Defines the properties represented in the Transaction Header object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
View Transaction Header Details
Property Definitions - Transaction Body
Defines the properties represented in the Transaction Body object (JSON) or node (XML).
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| transactionBody | Required | A parent object (JSON) or node (XML) that contains the transaction metadata. | ||
| transactionCode | Required | String | 12 / 12 | A static value of Authenticate. The transaction code is meant to identify the message type and the context or action that should be taken. In this context it implies that a request is being placed to authenticate the clients credentials.Possible Values:
|
| username | Conditional | String | 1 / 50 | A string that represents the username assigned to the client by Mortgage Connect. |
| password | Conditional | String | 1 / 50 | A string that represents the password assigned to the client by Mortgage Connect. |
Property Definitions - Transaction Extensions
Defines the properties represented in the TransactionExtensions object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
View Transaction Extension Details
Response Definition - Acknowledgment Response Properties
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| responseType | Required | String | 20 / 20 | A static value of AuthenticateResponse. |
| response | Required | String | 1 / MAX | JSON/XML representation of the authentication response as defined in the next section. |
Response Definition - Response Properties
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| statusType | Required | Integer | A static value of either 1 or 2, which indicates whether the authentication attempt was successful or not. Possible Values:
|
|
| statusMessage | Required | String | 0 / MAX | A textural description of the authentication status, which provides additional context regarding why an authentication request was accepted or rejected. |
| jsonWebToken | Optional | String | 0 / MAX | The actual JWT that the Client must store and send in the Authentication header of subsequent requests.The JWT consist of three components: a Header, a Payload, and a Signature. The header specifies the algorithm used for signing the token, while the payload contains the claims or information about the user or system. While the digitally signed signature ensures the integrity and authenticity of the token, thus allowing the server to verify the authenticity of the token and ensure that it has not been tampered with. |
| jsonWebTokenValidFrom | Optional | DateTime | Represents the time from which the JWT is valid. | |
| jsonWebTokenValidTo | Optional | DateTime | Represents the time when the JWT will expire. |
Rate Quote - RQ100 - Rate Quote
🌐 The following is an example payload to be posted in the body of the HTTP request.
/* Copyright © 2024 Mortgage Connect LP */
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Rate-Quote",
"onlyReturnLowestRate": false,
"state": "PA",
"countyFipsCode": "41003",
"loanNumber": "73201-3433",
"loanAmount": 150000.00,
"unpaidBalanceAmount": 45000.00,
"ownerInsuredAmount": 130000.00,
"priorPolicyAmount": 140000.00,
"priorPolicyDate": "1999-04-11T02:03:40",
"underwriterId": "2"
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Rate-Quote</transactionCode>
<onlyReturnLowestRate>false</onlyReturnLowestRate>
<state>PA</state>
<countyFipsCode>41003</countyFipsCode>
<loanNumber>73201-3433</loanNumber>
<loanAmount>150000.00</loanAmount>
<unpaidBalanceAmount>45000.00</unpaidBalanceAmount>
<ownerInsuredAmount>130000.00</ownerInsuredAmount>
<priorPolicyAmount>140000.00</priorPolicyAmount>
<priorPolicyDate>1999-04-11T02:03:40</priorPolicyDate>
<underwriterId>2</underwriterId>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->👍 The request payload can be verified using the following validation schema.
/* Copyright © 2024 Mortgage Connect LP */
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "root",
"description": "Copyright @ 2024 Mortgage Connect LP - Title & Tax Schema.",
"type": "object",
"additionalProperties": false,
"properties": {
"legalHeader": {
"type": "object",
"additionalProperties": false,
"properties": {
"version": {
"examples": [
"1.0.9.0"
],
"type": "string",
"minLength": 1,
"maxLength": 20
},
"disclosingParty": {
"examples": [
"Copyright @ 2024 Mortgage Connect LP"
],
"type": "string",
"minLength": 1,
"maxLength": 100
},
"proprietaryInformationAndConfidential": {
"examples": [
"Ownership of Proprietary Information. The Recipient agrees that it shall not receive any right, title or interest, or any license or right to use, the Disclosing Party's Proprietary Information, including, but not limited to, technology, ideas, concepts, drawings, documentation, designs, prototypes, processes, trade secrets, trademarks or other intellectual property rights therein, by implication or otherwise."
],
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"version",
"disclosingParty",
"proprietaryInformationAndConfidential"
],
"minProperties": 3,
"maxProperties": 3
},
"transactionHeader": {
"type": "object",
"additionalProperties": false,
"properties": {
"transactionIdempotentId": {
"examples": [
"90039F81-73C1-4788-98BC-90553888D301"
],
"type": "string",
"minLength": 36,
"maxLength": 36,
"pattern": "^[\\da-fA-F]{8}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{4}-[\\da-fA-F]{12}$"
},
"transactionDate": {
"examples": [
"2024-04-11T02:03:40"
],
"type": "string",
"format": "date-time"
},
"clientCode": {
"examples": [
"1799"
],
"type": "string",
"minLength": 1,
"maxLength": 100,
"format": "integer"
},
"clientName": {
"examples": [
"AcmeInc"
],
"type": "string",
"minLength": 1,
"maxLength": 100
},
"vendorCode": {
"examples": [
"MC"
],
"type": "string",
"minLength": 1,
"maxLength": 100
},
"vendorName": {
"examples": [
"Mortgage Connect"
],
"type": "string",
"minLength": 1,
"maxLength": 100
}
},
"required": [
"transactionIdempotentId",
"transactionDate",
"clientCode",
"clientName",
"vendorCode",
"vendorName"
],
"minProperties": 6,
"maxProperties": 6
},
"transactionBody": {
"type": "object",
"additionalProperties": false,
"properties": {
"transactionCode": {
"examples": [
"Rate-Quote"
],
"type": "string",
"const": "Rate-Quote"
},
"onlyReturnLowestRate": {
"examples": [
true,
false
],
"type": "boolean"
},
"state": {
"type": "string",
"examples": [
"PA"
],
"enum": [
"AK",
"AL",
"AR",
"AS",
"AZ",
"CA",
"CO",
"CT",
"DC",
"DE",
"FL",
"FM",
"GA",
"GU",
"HI",
"IA",
"ID",
"IL",
"IN",
"KS",
"KY",
"LA",
"MA",
"MD",
"ME",
"MH",
"MI",
"MN",
"MO",
"MP",
"MS",
"MT",
"NC",
"ND",
"NE",
"NH",
"NJ",
"NM",
"NV",
"NY",
"OH",
"OK",
"OR",
"PA",
"PR",
"PW",
"RI",
"SC",
"SD",
"TN",
"TX",
"UT",
"VA",
"VI",
"VT",
"WA",
"WI",
"WV",
"WY"
]
},
"countyFipsCode": {
"examples": [
"06037"
],
"type": "string",
"minLength": 5,
"maxLength": 5
},
"loanNumber": {
"examples": [
"73201-3433"
],
"type": "string",
"minLength": 1
},
"loanAmount": {
"type": "number",
"format": "money",
"examples": [ "150000.00" ]
},
"unpaidBalanceAmount": {
"type": "number",
"format": "money",
"examples": [ "45000.00" ]
},
"ownerInsuredAmount": {
"type": "number",
"format": "money",
"examples": [ "130000.00" ]
},
"priorPolicyAmount": {
"type": "number",
"format": "money",
"examples": [ "140000.00" ]
},
"priorPolicyDate": {
"type": "string",
"format": "date-time",
"examples": [ "1999-04-11T02:03:40" ]
},
"underwriterId": {
"type": "string",
"examples": [ "2" ]
}
},
"required": [
"transactionCode",
"onlyReturnLowestRate",
"state",
"countyFipsCode",
"loanNumber",
"loanAmount"
]
},
"transactionExtensions": {
"type": "object",
"properties": {
"transactionExtension": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"key": {
"examples": [
"Client Specific Key"
],
"type": "string",
"minLength": 1,
"maxLength": 200
},
"value": {
"examples": [
"Client Specific Value"
],
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"value"
],
"minProperties": 2,
"maxProperties": 2
},
"minItems": 0
}
}
}
},
"required": [
"transactionHeader",
"transactionBody"
],
"minProperties": 2,
"maxProperties": 4
}
/* Copyright © 2024 Mortgage Connect LP */The request payload XML schema validation is under construction. 🚧✅ The following is an 'Accepted' example payload to be returned in the HTTP response.
{
"transactionHeader": {
"transactionIdempotentId": "90039F81-73C1-4788-98BC-90553888D301",
"transactionDate": "2024-04-11T02:03:40",
"clientCode": "1799",
"clientName": "AcmeInc",
"vendorCode": "MC",
"vendorName": "Mortgage Connect"
},
"transactionBody": {
"transactionCode": "Acknowledgment",
"ackStatus": "true",
"ackMessage": "Accepted",
"ackException": "",
"responseType": "RateQuoteResponse",
"response": {
"rateQuoteId": 1,
"onlyReturnLowestRate": false,
"state": "PA",
"countyFipsCode": "41003",
"loanNumber": "73201-3433",
"loanAmount": 150000.00,
"unpaidBalanceAmount": 45000.00,
"ownerInsuredAmount": 130000.00,
"priorPolicyAmount": 140000.00,
"priorPolicyDate": "1999-04-11T02:03:40",
"underwriterId": "44",
"rates": [
{
"underwriterName": "FIRST AMERICAN TITLE INSURANCE COMPANY",
"rateType": "Sale Rate",
"rateTotal": 765.77,
"rateIsLowest": false,
"lendersPremium": null,
"ownersPremium": null,
"premium": 500.00,
"endorsements": [
{
"endorsementName": "TIRBOP PA Endorsement 900 - (ALTA Endorsement 8.1-06) (Environmental Protectio...",
"feeAmount": 215.77
},
{
"endorsementName": "ALTA Endorsement 8.1-06",
"feeAmount": 50.00
}
]
},
{
"underwriterName": "FIRST AMERICAN TITLE INSURANCE COMPANY",
"rateType": "Refinance",
"rateTotal": 2207.65,
"rateIsLowest": false,
"lendersPremium": null,
"ownersPremium": null,
"premium": 2157.65,
"endorsements": [
{
"endorsementName": "TIRBOP PA Endorsement 810 - (ALTA Endorsement 4.1-06) (Condominium)",
"feeAmount": 50.00
},
{
"endorsementName": "TIRBOP PA Endorsement 820 - (ALTA Endorsement 5.1-06) (Planned Unit Developmen...",
"feeAmount": 0.00
}
]
},
{
"underwriterName": "FIRST AMERICAN TITLE INSURANCE COMPANY",
"rateType": "Simultaneous Issue",
"rateTotal": 619.00,
"rateIsLowest": true,
"lendersPremium": 0.00,
"ownersPremium": 569.00,
"premium": null,
"endorsements": [
{
"endorsementName": "TIRBOP PA Endorsement 810 - (ALTA Endorsement 4.1-06) (Condominium)",
"feeAmount": 50.00
},
{
"endorsementName": "TIRBOP PA Endorsement 820 - (ALTA Endorsement 5.1-06) (Planned Unit Developmen...",
"feeAmount": 0.00
}
]
}
]
}
},
"transactionExtensions": {
"transactionExtension": [
{
"key": "Client Specific Key 1",
"value": "Client Specific Value 1"
},
{
"key": "Client Specific Key 2",
"value": "Client Specific Value 2"
}
]
}
}
/* Copyright © 2024 Mortgage Connect LP */<!-- Copyright © 2024 Mortgage Connect LP -->
<root>
<transactionHeader>
<transactionIdempotentId>90039F81-73C1-4788-98BC-90553888D301</transactionIdempotentId>
<transactionDate>2024-04-11T02:03:40</transactionDate>
<clientCode>1799</clientCode>
<clientName>AcmeInc123</clientName>
<vendorCode>MC</vendorCode>
<vendorName>Mortgage Connect</vendorName>
</transactionHeader>
<transactionBody>
<transactionCode>Acknowledgment</transactionCode>
<ackStatus>true</ackStatus>
<ackMessage>Accepted</ackMessage>
<ackException></ackException>
<responseType>RateQuoteResponse</responseType>
<response>
<rateQuoteId>1</rateQuoteId>
<onlyReturnLowestRate>false</onlyReturnLowestRate>
<state>PA</state>
<countyFipsCode>41003</countyFipsCode>
<loanNumber>73201-3433</loanNumber>
<loanAmount>150000</loanAmount>
<unpaidBalanceAmount>45000</unpaidBalanceAmount>
<ownerInsuredAmount>130000</ownerInsuredAmount>
<priorPolicyAmount>140000</priorPolicyAmount>
<priorPolicyDate>1999-04-11T02:03:40</priorPolicyDate>
<underwriterId>44</underwriterId>
<rates>
<rate>
<underwriterName>FIRST AMERICAN TITLE INSURANCE COMPANY</underwriterName>
<rateType>Sale Rate</rateType>
<rateTotal>765.77</rateTotal>
<rateIsLowest>false</rateIsLowest>
<lendersPremium />
<ownersPremium />
<premium>500.00</premium>
<endorsements>
<endorsement>
<endorsementName>TIRBOP PA Endorsement 900 - (ALTA Endorsement 8.1-06) (Environmental Protectio...</endorsementName>
<feeAmount>215.77</feeAmount>
</endorsement>
<endorsement>
<endorsementName>ALTA Endorsement 8.1-06</endorsementName>
<feeAmount>50.00</feeAmount>
</endorsement>
</endorsements>
</rate>
<rate>
<underwriterName>FIRST AMERICAN TITLE INSURANCE COMPANY</underwriterName>
<rateType>Refinance</rateType>
<rateTotal>2207.65</rateTotal>
<rateIsLowest>false</rateIsLowest>
<lendersPremium />
<ownersPremium />
<premium>2157.65</premium>
<endorsements>
<endorsement>
<endorsementName>TIRBOP PA Endorsement 810 - (ALTA Endorsement 4.1-06) (Condominium)</endorsementName>
<feeAmount>50.00</feeAmount>
</endorsement>
<endorsement>
<endorsementName>TIRBOP PA Endorsement 820 - (ALTA Endorsement 5.1-06) (Planned Unit Developmen...</endorsementName>
<feeAmount>0.00</feeAmount>
</endorsement>
</endorsements>
</rate>
<rate>
<underwriterName>FIRST AMERICAN TITLE INSURANCE COMPANY</underwriterName>
<rateType>Simultaneous Issue</rateType>
<rateTotal>619.00</rateTotal>
<rateIsLowest>true</rateIsLowest>
<lendersPremium>0.00</lendersPremium>
<ownersPremium>569.00</ownersPremium>
<premium />
<endorsements>
<endorsement>
<endorsementName>TIRBOP PA Endorsement 810 - (ALTA Endorsement 4.1-06) (Condominium)</endorsementName>
<feeAmount>50.00</feeAmount>
</endorsement>
<endorsement>
<endorsementName>TIRBOP PA Endorsement 820 - (ALTA Endorsement 5.1-06) (Planned Unit Developmen...</endorsementName>
<feeAmount>0.00</feeAmount>
</endorsement>
</endorsements>
</rate>
<rates>
</response>
</transactionBody>
<transactionExtensions>
<transactionExtension>
<key>Client Specific Key 1</key>
<value>Client Specific Value 1</value>
</transactionExtension>
<transactionExtension>
<key>Client Specific Key 2</key>
<value>Client Specific Value 1</value>
</transactionExtension>
</transactionExtensions>
</root>
<!-- Copyright © 2024 Mortgage Connect LP -->⛔ The following is a 'Rejected' example payload to be returned in the HTTP response.
Rejected Acknowledgment payloads are typically message type agnostic.Rejected Acknowledgment payloads are typically message type agnostic.The Rate Quote API method is the mechanism in which a Client can submit a message to Mortgage Connect requesting a Rate Quote.
View Workflow Orchestration
Mortgage Connect URL
POST 🔒 https://{BaseUrl}/Api/V1.0/SubmitMessage
Mortgage Connect URL Properties
Defines the dynamic properties in the URL (i.e. those enclosed in curly brakets {}) that are used to uniquely identify the targeted endpoint. The actual property values will be determined during the onboarding process, however you can reference the Environments section to acquaint yourself with the standard BaseUrls exposed by Mortgage Connect.
| Property | Requirement | Description |
|---|---|---|
| BaseUrl | Required | A unique base Url that represents a specific Mortgage Connect endpoint and targeted environment. |
Property Definitions - Transaction Header
Defines the properties represented in the Transaction Header object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
View Transaction Header Details
Property Definitions - Transaction Body
Defines the properties represented in the Transaction Body object (JSON) or node (XML).
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| transactionBody | Required | A parent object (JSON) or node (XML) that contains the transaction metadata. | ||
| transactionCode | Required | String | 10 / 10 | A static value of Rate-Quote. The transaction code is meant to identify the message type and the context or action that should be taken. In this context it implies that a Rate Quote is being requested. Possible Values:
|
| onlyReturnLowestRate | Required | Boolean | Indicates whether the client wants all rates returned or if only the lowest rate should be returned. | |
| state | Required | String | 2 / 2 | The property state abbreviation. Possible Values: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UT, VA, VI, VT, WA, WI, WV, WY. |
| countyFipsCode | Required | String | 5 / 5 | The property county FIPS Code. |
| loanNumber | Required | String | 1 / MAX | The client's loan number alpha-numeric. |
| loanAmount | Required | Money | The loan amount. | |
| unpaidBalanceAmount | Optional | Money | The unpaid balance amount. | |
| ownerInsuredAmount | Optional | Money | The owner insured amount. | |
| priorPolicyAmount | Optional | Money | The prior policy amount. | |
| priorPolicyDate | Optional | Date | The date the previous policy was put into effect. | |
| underwriterId | Optional | String | 1 / 50 | The underwriter Id. Traditionally this is set to a numeric value that represents Mortgage Connect's Underwriter Id. However, it supports alpha-numeric values in the event Mortgage Connect is resposible for performing any mapping operations where the Client's Underwriter Id is a code or similar string value. |
Property Definitions - Transaction Extensions
Defines the properties represented in the TransactionExtensions object (JSON) or node (XML). Note that this message artifact is identical for each and every message type.
View Transaction Extension Details
Response Definition - Acknowledgment Response Properties
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| responseType | Required | String | 17 / 17 | A static value of RateQuoteResponse. |
| response | Required | String | 1 / MAX | JSON/XML representation of the rate quote as defined in the next section. |
Response Definition - Response Properties
| Property | Requirement | Data Type | Min / Max | Description |
|---|---|---|---|---|
| rateQuoteId | Required | Integer | The unique Mortgage Connect Id that is associated with each Rate Quote request. | |
| onlyReturnLowestRate | Required | Boolean | Indicates whether the client wants all rates returned or if only the lowest rate should be returned. | |
| state | Required | String | 2 / 2 | The property state abbreviation. Possible Values: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UT, VA, VI, VT, WA, WI, WV, WY. |
| countyFipsCode | Required | String | 5 / 5 | The property county FIPS Code. |
| loanNumber | Required | String | 1 / MAX | The client's loan number alpha-numeric. |
| loanAmount | Required | Money | The loan amount. | |
| unpaidBalanceAmount | Optional | Money | The unpaid balance amount. | |
| ownerInsuredAmount | Optional | Money | The owner insured amount. | |
| priorPolicyAmount | Optional | Money | The prior policy amount. | |
| priorPolicyDate | Optional | Date | The date the previous policy was put into effect. | |
| underwriterId | Optional | String | 1 / 50 | The underwriter Id. Traditionally this is set to a numeric value that represents Mortgage Connect's Underwriter Id. However, it supports alpha-numeric values in the event Mortgage Connect is resposible for performing any mapping operations where the Client's Underwriter Id is a code or similar string value. |
| rates | Required | Array | An array of rate objects generated in response to the Rate Quote request. | |
| underwriterName | Required | Integer | 1 / 64 | The name of the underwriter. |
| rateType | Required | String | 1 / 255 | The rate type. Possible Values:
|
| rateTotal | Required | Money | The total rate cost, which is a summation of the lendersPremium, ownersPremium, premium, and all the endorsement feeAmounts. |
|
| rateIsLowest | Required | Boolean | Indicates whether the rate is the lowest or not. | |
| lendersPremium | Optional | Money | The lenders premium. | |
| ownersPremium | Optional | Money | The owners premium. | |
| premium | Required | Money | The standard underwriter's premium. | |
| endorsements | Required | Array | An array of endorsement objects associated with a corresponding rate. | |
| endorsementName | Required | String | 1 / 255 | The name of the endorsement. |
| feeAmount | Required | Money | The endorsement fee amount. |
Mapping Artifacts
The following sections highlight internal Mortgage Connect artifacts such as Document Types, Product Codes, etc. that will need mapped by the client to their corresponding internal code.
Underwriters
The following section defines the Mortgage Connect Rate Quote Underwriters. These underwriters need to be mapped to the client's corresponding underwriter Id, Name or Code.
🚧 This section is currently under construction 🚧
Endorsements
The following section defines the Mortgage Connect Rate Quote Endorsements. These endorsements need to be mapped to the client's corresponding endorsement.
🚧 This section is currently under construction 🚧
Environments
The following sections define the different environments and BaseUrls supported by the Mortgage Connect Integration API.
Test Environment
The following section provides details about the Mortgage Connect Rate Quote Integration Test environments.
Mortgage Connect Base URLs
| Base URL | Description |
|---|---|
| https://test-titlequote.mortgageconnectlp.com | The primary test environment. |
Development Environment
The following section provides details about the Mortgage Connect Rate Quote Integration Development environments.
Mortgage Connect Base URLs
| Base URL | Description |
|---|---|
| https://dev-titlequote.mortgageconnectlp.com | The primary development environment. |
Production Environment
The following section provides details about the Mortgage Connect Rate Quote Integration Production environments.
Mortgage Connect Base URLs
| Base URL | Description |
|---|---|
| https://titlequote.mortgageconnectlp.com | The primary production environment. |
Try It Out
The following sections provide details on how a client can interact with the Mortgage Connect Rate Quote Integration API, using tools such as Swagger and PostMan.
Swagger
The following section provides information on how to access and use Swagger to test the Mortgage Connect Rate Quote Integration API.
Swagger Tool
This is a future feature to be implemented. 🚧
Postman
A client specific Postman collection that can be used to test the Mortgage Connect Rate Quote Integration API will be provided upon request.
Onboarding
The following sections identify steps and procedures required of the Client and Mortgage Connect to onboard and integrate.
Client Checklist
The following section defines the action items to be taken by the Client to successfully onboard and integrate with the Mortgage Connect Rate Quote Integration API platform.
Action Items
| Check | Action Item |
|---|---|
| ⬜ | Identify the public facing URLs for the Mortgage Connect Gateway REST API Service endpoints per targeted environment. |
| ⬜ | Optionally, if your company whitelists inbound traffic, then you will need to work with Mortgage Connects to acquire the public IP Addresses (per environment), of the Mortgage Connect services that send outbound messages to the client. |
| ⬜ | Obtain the username and password required to authenticate to each Mortgage Connect environment to be targeted. |
| ⬜ | Obtain the Client Integration Code assigned to the Client by Mortgage Connect, which is used to uniquely identify the client when invoking the Mortgage Connect Gateway. |
| ⬜ | |
| ⬜ | |
| ⬜ | |
| ⬜ | |
| ⬜ |
Mortgage Connect Checklist
The following section defines the action items to be taken by Mortgage Connect to successfully on board the Client to the Mortgage Connect Rate Quote Integration API platform.
Action Items
| Check | Action Item |
|---|---|
| ⬜ | Identify the public facing URLs for the Client endpoints per targeted environment. These are the applicable URLs that will be invoked when sending outbound asynchronous message back to the Client. |
| ⬜ | Optionally, Mortgage Connect may choose to whitelist inbound traffic, which will require working with the Client to acquire the public IP Addresses (per environment), of the Client services that send inbound messages to Mortgage Connect. |
| ⬜ | Obtain the username and password required to authenticate to each Client environment to be targeted. |
| ⬜ | Build and configure the integration configuration. |
| ⬜ | Build and configure the client profiles in each of the targeted sub systems. |
| ⬜ | |
| ⬜ | |
| ⬜ | |
| ⬜ |
Onboarding Milestones
The following sections provide a graphical overview at a macro level of the milestones required to be completed to on board a client.
Appendix
The following sections highlight additional information such as terms, abbreviations, tools, and helpful links.
Terms & Definitions
The following section defines the Mortgage Connect Integration API terms and defintions
Terms & Abbreviations
| Term | Definition |
|---|---|
| eConnect | Mortgage Connects's proprietary valuation system. |
| Asynchronous | Asynchronous in this context is in relationship to an HTTP request. Specifically, an asynchronous response does not return to the client in the same HTTP connection as the request was made. In fact, many times this means that another out of process service, is responsible to sending the response back to the client by invoking an endpoint on the client’s server. |
| Base64 Encoding | Base64 Encoding is a group of binary-to-text encoding schemes that represent binary data (more specifically, a sequence of 8-bit bytes) in sequences of 24 bits that can be represented by four 6-bit Base64 digits. Base64 is designed to carry data stored in binary formats across channels that only reliably support text content. See: https://en.wikipedia.org/wiki/Base64. |
| Basic Auth | This stands for Basic Access Authentication, which is a method for an HTTP user agent (e.g. a web browser) to provide a user name and password when making a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic "credentials", where "credentials" are the Base64 encoding of an ID and password joined by a single colon : https://en.wikipedia.org/wiki/Basic_access_authentication. |
| ClientCode | A client code is a unique code assigned to a client by Mortgage Connect that is used to identifiy client requests in the early stages of the API processing pipeline. |
| DMZ | DMZ refers to a Demilitarized Zone (sometimes referred to as a perimeter network or screened subnet) which is a physical or logical subnetwork that contains and exposes an organization's external-facing services to an untrusted, usually larger, network such as the internet. See: https://en.wikipedia.org/wiki/DMZ_(computing). |
| eConnect | Mortgage Connects's proprietary title system. |
| EventId | This a unique code, which is a shortcut annotation to refer to the context of a specific API message payload. For example, "MC100" is the code associated with a "New-Order" request. |
| Gateway | Gateway is the informal name that Mortgage Connect used to refer to the public REST based Web API service that exists in the DMZ that accepts inbound messages from clients. |
| JWT | JSON web token (JWT), pronounced "jot", is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. See: https://auth0.com/docs/secure/tokens/json-web-tokens. |
| LOS | Loan Origination System |
| LVR | Legal and Vesting Report |
| MC | Mortgage Connect |
| PRT | Property Report |
| QC | Quality Control |
| REST | A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. REST stands for representational state transfer and was created by computer scientist Roy Fielding. |
| SessionId | A session Id is a unique code assigned to a client that is used to uniquely identify their messages from other client messages. It is in many ways synonymous to ClientCode and ClientId. |
| SLA | A service-level agreement (SLA) defines the level of service expected by a client. |
| Synchronous | Synchronous in this context is in relation to an HTTP request. Specifically, a synchronous response returns to the client in the same HTTP connection as the request was made. |
| Token-Based Authentication | Token-based authentication is a protocol which allows users to verify their identity, and in return receive a unique access token. See: https://www.okta.com/identity-101/what-is-token-based-authentication. |
| TTL | Title Insurance |
HTTP Status Codes
The following HTTP status codes are examples of the types of codes returned from the Mortgage Connect Integration API.
A 400, 401, 404, and 500, are the typical HTTP codes a client will want code against.
HTTP Status Codes
| Status Code | Meaning |
|---|---|
| 200 | Ok -- The request was successful. |
| 400 | Bad Request -- The request could not be understood by the server due to malformed syntax. |
| 401 | Unauthorized -- Your authentication credentials are invalid or your account has not been set up. |
| 403 | Forbidden -- The requested is hidden for administrators only. |
| 404 | Not Found -- The specified URL could not be found. |
| 405 | Method Not Allowed -- You tried to access an invalid method. |
| 406 | Not Acceptable -- You requested a format that is not permitted. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Tools and Links
The following sections define some general tools, links and references that can accelerate your integration development and testing.
JSON Schema Validator
JSON Schema Validator is an online utility that validates JSON against a JSON Schema. It Supports JSON Schema Draft 3, Draft 4, Draft 6, Draft 7 and Draft 2019-09. This can be a very convenient tool for quickly validating an integration message.
https://www.jsonschemavalidator.net
Newtonsoft
Newtonsoft is a popular high-performance JSON framework for .NET that makes it relatively easy to interact with JSON payloads, from serialization and deserialization to and from strongly typed types to schema validation.
https://www.newtonsoft.com/json
Postman
Postman is an online or locally installed utility that facilitates invoking REST APIs in real-time.
Quick Type
Quick Type is an online utility that enables you to convert JSON and/or JSON Schema files to C# classes or one of many other languages such as C++, Java, JavaScript, Python, and Ruby to name a few. This can significantly jump start your development.
Support
The following sections identify methods of communcation and options for obtaining help in support of the Mortgage Connect Rate Quote Integration API platform.
Service Desk
The following section defines the different options for contacting Mortgage Connect's service desk.
Service Desk Contact Information
Internal Call: ext. 22501
External Call: 855-595-3563 x22501
Service Portal Url: https://mortgageconnect.samanage.com/welcome.portal