Let's Talk APIs

Are you a service provider for the Real Estate or Mortgage Industry? Then the MortgageMingler API might be right for you.

The MortgageMingler API allows you to sync your database with MortgageMingler for easier or automated management. Automatically create new listings, add a MortgageMingler feed to your website, access your Dashboard statistics, link campaign stats to your database, remotely add new members or adjust your Experts' posting instructions, and more.

Our API offers in-depth documentation and how-to-documents, and a great deal of the data and functionality within our web application is accessible, so the integration possibilities are limitless.

Need Help?

Not a programmer? Not a problem. We can help you develop custom integrations for your company or website. Simply email us at info@mortgagemingler.com with your request, and someone from our professional services team will contact you.

API: Documentation

User Authorization

MortgageMingler offers simple, standard OAuth2 services for user-friendly authorization of third-party operations. Your users will need to go through the OAuth2 flow before your site can publish listings via MortgageMingler.

Before you can begin, you will need to have MortgageMingler support provide you with a unique API key and secret. Once you receive those, uou'll be able to implement the MortgageMingler API in your website.

API keys

In this documentation, we'll use the following test account:

API Key: 0cbc6611f5540bd0809a388dc95a615b
API Secret: 1e6947ac7fb3a9529a9726eb692c8cc5

Note: These keys are not valid and cannot be used in your code.

Note: You should protect your key and secret like you would a password, particularly the API secret.

OAuth2 endpoints:
Authorization: https://www.mortgagemingler.com/rest/authorize
Access token: https://www.mortgagemingler.com/rest/token

OAuth2 Implementation Overview

To provide a general understanding of how OAuth2 works, here's an outline of how your site and the MortgageMingler API interact together to authorize your site to post listings on behalf of your user:

Your site generates a random "state" string and redirects the user to the MortgageMingler authorization endpoint, with client_id (your API key) and state (random generated string) as GET arguments. Your site should also store the state string in the current session.

Example authorization request URL:

https://www.mortgagemingler.com/rest/authorize?client_id=0cbc6611f5540bd0809a388dc95a615b&state=0ed8eb67d887c67f953359d7cb2ac6a0

MortgageMingler asks the user if they want to allow your site to access their MortgageMingler account. User clicks yes or no.

MortgageMingler redirects the user back to your site's preconfigured redirect URL with an authorization token appended (in a 'code' GET parameter) and the state string (in a 'state' GET argument).

Example redirect URL:

http://www.yoursite.com/oauth_callback?code=0ed3f45743dfebb64cdca6c15011e391701e9340&state=0ed8eb67d887c67f953359d7cb2ac6a0

In this example, the authorization token is:

0ed3f45743dfebb64cdca6c15011e391701e9340.

Your server checks that the 'state' GET argument matches the string stored in the session (in step 1).

Your server then makes an HTTP-authenticated POST request to the MortgageMingler access token endpoint, posting the authorization token.

Example POST request:

URL: https://www.mortgagemingler.com/rest/token
Username: 0cbc6611f5540bd0809a388dc95a615b
Password: 1e6947ac7fb3a9529a9726eb692c8cc5
POST field grant_type:   authorization_code
POST field code: 0ed3f45743dfebb64cdca6c15011e391701e9340
(authorization token from URL in step 3)

MortgageMingler responds with a JSON-encoded string containing an access token, an access token expiration, and a refresh token. All three of these items should be persisted in your site's database for future use. Each of your users who authorize you to access their MortgageMingler account will have their own unique tokens, so you should be sure to include a reference to the current user (generally a user_id column). The state and authorization token are no longer useful and do not need to be stored.

Example JSON response:

{
    "access_token": "e62f1900c6b12c875fc64fa915309b09c2517530",
    "expires_in": 315576000,
    "token_type":"Bearer",
    "scope":"listing account_info",
    "is_live":1
    "refresh_token": "977b97fec11b71360f2fc08e69bac1899568e4c9",
}
                        

You might also receive an error, and your application should be prepared to handle it gracefully.

Example error JSON response:

{ 
    "error": "invalid_grant",
    "error_description": "Authorization code doesn't exist or is invalid for the client"
}
                        

Note: the expires_in value is the number of seconds until the access token expires. To get a date and time of expiry, add the expires_in value to the current UNIX timestamp.

Note: your API account may be in test mode or live mode. The is_live parameter indicates the mode the token was issued in. Tokens issued in test mode are not valid for making changes in production.

OAuth2 Tokens

Tokens are semi-random strings of characters that function as unique identifiers. Each type of token has a different function:

Access token

The access token is your key to the user's MortgageMingler account. You will need to provide this key each time you take an action (e.g. publish a listing) to the user's account. Access tokens are currently long-lived: they're good for 10 years. It's still a good idea to store the access token expiration though, as this may change in the future.

Access tokens should be protected and never displayed or otherwise exposed on your website.

Authorization token

This temporary token (issued in step 3 above) is short-lived and single-use. Its only purpose is to retrieve an access token. Once it's used, it expires. Your site should use it to request the access token immediately (in step 5 above) as they expire in 10 seconds.

Refresh token

Once an access token expires, your site can use the refresh token to obtain a new one. Refresh tokens expire a year after access tokens expire.

URL: https://www.mortgagemingler.com/rest/token
Username: 0cbc6611f5540bd0809a388dc95a615b
Password: 1e6947ac7fb3a9529a9726eb692c8cc5
POST field grant_type:   refresh_token
POST field code: 977b97fec11b71360f2fc08e69bac1899568e4c9
(refresh token provided with access token)

Important: refresh tokens become invalid after use. A new refresh token is issued with the new access token.

Get Member Account Settings

Access token scope required: account_info

Once you have obtained a valid access token for a CityBlast member, either through our OAuth2 authentication or provisioning a new MortgageMingler account, your site can manage settings on that user's account via the MortgageMingler API.

Changing settings on a MortgageMingler account is just a matter of making a request to the correct endpoint.

Endpoint: https://www.mortgagemingler.com/rest/member/[:id]

This endpoint conforms to REST standards: it accepts GET requests for read operations and POST requests for write operations.

User account parameters available at this endpoint:
Field name Data type Valid values Default Description Required?
first_name string <= 100 characters Value provided by Facebook The user's first name Optional
last_name string <= 100 characters Value provided by Facebook The user's last name Optional
email string <= 256 characters Value provided by Facebook The user's email address Optional
publishing_enabled boolean true or false true The member's publishing “master switch.” When publishing_enabled is set to true, publishing to individual social media networks is controlled by the facebook_enabled, twitter_enabled and linkedin_enabled parameters. When publishing_enabled is set to false, all publishing is disabled. Optional
facebook_access_valid boolean true or false Whether or not our connection to Facebook for this user is valid. If this value is false, the user must authenticate or reauthenticate against Facebook to continue publishing. Read only
twitter_access_valid boolean true or false Whether or not our connection to Twitter for this user is valid. If this value is false, the user must authenticate or reauthenticate against Twitter to continue publishing. Read only
twitter_enabled boolean true or false false Whether or not Twitter publishing is enabled for this member. We may set this value to false if the user's Twitter publishing fails. You should check that twitter_access_valid is true prior to setting this value. If it is false, you should require the user to authenticate or reauthenticate against Twitter before attempting to set it to true. Optional
linkedin_access_valid boolean true or false Whether or not our connection to LinkedIn for this user is valid. If this value is false, the user must authenticate or reauthenticate against LinkedIn to continue publishing. Read only
linkedin_enabled boolean true or false false Whether or not LinkedIn publishing is enabled for this member. We may set this value to false if the user's LinkedIn publishing fails. You should check that linkedin_access_valid is true prior to setting this value. If it is false, you should require the user to authenticate or reauthenticate against LinkedIn before attempting to set it to true Optional
auto_like boolean true or false true Whether or not to automatically “like’ posts on Facebook. Optional
click_tracking boolean true or false true Whether or not to automatically “like’ posts on Facebook. Optional
branded_content boolean true or false true Whether or not to show a bar with the user's name and contact information at the top of the content shown when clicking links we post to the user's social media accounts. Optional
post_hashtags boolean true or false false Whether or not to use hashtags in posts to the user's social media accounts. Optional
brokerage string The user's brokerage. Optional *
broker_address string The user's brokerage address. Optional *
phone string Valid 9-digit phone number. The user's phone number. Optional *
tags array, members must be integer [] Valid tag IDs Array of one or more publishing tags. If no tags are set, no publishing will occur. Optional
publish_days array, members must be integer [] 0 - 6 Array of one or more days of the week to publish. Days of the week are represented numerically (0 = Sunday, 6 = Saturday). Optional
primary_market string City and state of primary publishing market. Read only
secondary_market string City and state of primary publishing market. Read only
primary_market_place_id string The Google Place ID of the primary publishing market for this account. Write only. Use primary_market to read the secondary market set on this account. You must use this parameter to change the primary_market value.
secondary_market_place_id string The Google Place ID of the secondary publishing market for this account. Write only. Use secondary_market to read the secondary market set on this account. You must use this parameter to change the secondary_market value.

* Optional in API, but API account holders should require this information from their end users. MortgageMingler publishes it in various places to encourage potential leads to contact them.

MortgageMingler will return JSON-encoded data in response to your request.

Example JSON response to GET request, or to a POST request that was successful:

{
    "id": "123456",
    "first_name": "Joe",
    "last_name": "Agent",
    "email": "joe@realestatebrokerage.com",
    "publishing_enabled": true,
    "facebook_enabled": true,
    "twitter_enabled": false,
    "linkedin_enabled": false,
          "auto_like": true,
    "click_tracking": true,
    "branded_content": true,
    "brokerage": "Real Estate Brokerage, Inc.",
    "broker_address": "123 First St., Toronto, ON",
    "phone" : "555-443-2124",
    "publish_days" : [1,3,5],
    "tags" : [10680,10682,10683,10686,10690,10692,10696],
    "primary_market" : "Toronto, ON",
    "secondary_market" : "London, ON"
}
                        

Example JSON response when an error has occurred in response to a POST request:

{
    "updated": "false",
    "error": "invalid_member_settings",
    "error_description": "Invalid value for parameter 'email'"
}
                        

When an account is not found, MortgageMingler will return a 404 HTTP response code, along with error JSON:

{
    "updated": "false",
    "error": "invalid_member",
    "error_description": "Member not found"
}
                        
API error types

Errors are returned in the following JSON format:

{
    "error": "invalid_listing",
    "error_description": "A listing with this information already exists."
}
                            
Possible error values

Your code should be capable of handling these errors gracefully:

Error Description
invalid_listing Incorrect or missing listing information
invalid_listing_image One or more listing images could not be accepted (due to incorrect format, invalid file data or interrupted upload)
invalid_listing_location Valid listing city and state was not provided or invalid.
invalid_token The access token provided has expired or been revoked (possibly due to a lapsed MortgageMingler account)
malformed_token The string provided does not appear to be an access token.
insufficient_scope The member has declined (during OAuth authorization) or revoked the permission required to take the requested action.
insufficient_scope The member has declined (during OAuth authorization) or revoked the permission required to take the requested action.

These errors are possible, and likely indicate a bug in your implementation. The error_description value will provide specifics in each case.

Error
invalid_grant
invalid_request
invalid_client
invalid_uri
redirect_uri_mismatch
unsupported_response_type
unauthorized_client
invalid_scope
Pass-through OAuth: Create Member Account

Normally, members must first sign up with MortgageMingler to create an account, then authorize any third-party operations via OAuth authentication.

API accounts who have been given permission to create members may use the /rest/member/create endpoint to create member accounts with a pre-provisioned OAuth access token. No member parameters can be posted to this endpoint—its only functionality is to initialize a member account.

After sending a POST request to /rest/member/create, you will receive back data similar to the example below. To do anything further with this account, you must next have the user authenticate against Facebook through our Pass-through OAuth mechanism.

Example JSON response when member has been created:

{
    "created": "true",
    "id": "123456"
    "access_token": "e62f1900c6b12c875fc64fa915309b09c2517530"
}
                        
Pass-through OAuth: Social Media Integration

Pass-Through OAuth allows your end users to connect their social media accounts to MortgageMingler without needing to interact with our site (in most cases). It is not related to our OAuth user authentication, which allows your site to manage your end-users' MortgageMingler accounts and associated property listings.

The cornerstone of MortgageMingler's ability to publish to our members' social media accounts is the OAuth authentication functionality provided by social media networks. OAuth provides a means of authorizing MortgageMingler to publish to those accounts and gather statistics.

Normally, your end users would need to separately log into MortgageMingler and provide this authorization, but when you provision MortgageMingler accounts through our API you can use Pass-Through OAuth to offer this functionality directly on your own site, without requiring your end users to take any action on the MortgageMingler site in most cases.

Pass-Through OAuth works much the same way that regular OAuth2 authentication works at Facebook, Twitter and LinkedIn, with an additional redirect at the beginning and end of the process. To use it, you link your users to a URL in the following format:

https://www.mortgagemingler.com/auth/login?access_token=e62f1[...]&redirect=http://yoursite.com/settings

Both the access_token and redirect URL parameters are required.

Sending your user to this URL will do the following:

1. Silently redirect the user to Facebook to authorize the MortgageMingler Facebook app. The user must proceed with this step to allow MortgageMingler to post to his or her Facebook account.

2. Return the user to the MortgageMingler site, where our servers can then request and store basic information (name and email address) from Facebook.

3. In most cases, we won't show your user anything (they will only see the pages that Facebook, Twitter or LinkedIn display in the authentication process). However, if we determine that they already have a pre-existing MortgageMingler account, we'll show them a page asking them to grant you access to it.

4. Finally, we'll redirect the user to the URL specified in the redirect parameter specified above. We will append an authentication_status parameter to your redirect URL with a value of success when authentication has succeeded. In the example above, we would redirect the user to http://yoursite.com/settings?authentication_status=success.

This documentation covers Facebook only. Twitter and LinkedIn authentication must be done in similar ways. Documentation for these is forthcoming.

Get Started.

You'll need an API key and an API secret something our professional services team would be happy to help with!

Seamlessly integrate all of the great functions of MortgageMingler. Get Involved.