CRM Partnership Integration Guide

Welcome to the Matchouse CRM Integration Guide. This documentation explains how to connect your real estate CRM backend to the Matchouse property listing platform.

Last updated About 1 month ago

By completing this integration, you enable your users (estate agencies) to seamlessly connect their Matchouse accounts to your CRM, allowing your server to securely receive their property push API keys and automate their property listings.

Overview of the Flow

  1. Authenticate: Your server requests an access token from Matchouse.

  2. Generate URL: Your server requests a unique signed URL, passing your internal ID for that specific agency.

  3. User Action: The estate agency clicks the link in your CRM UI to log in or register on Matchouse.

  4. Webhook Delivery: Matchouse posts the agency's Matchouse API key back to your pre-configured Webhook URL, mapped to your internal agency ID.

  5. Push Properties: Your CRM uses the received API key to push listings to Matchouse on behalf of the agency.

Prerequisites

Before writing any code, ensure you have completed the initial setup process with the Matchouse partnership team.

What you will receive from Matchouse via email:

  • Base URL

  • x-crm-client-id

  • x-crm-client-secret

What you must provide to Matchouse:

  • webhook_url: A secure endpoint on your server where we will POST the agency's property push API keys once they successfully connect.

  • Developer Email Address: A monitored contact email where we can notify your technical team in the event of consecutive webhook delivery failures.

Step 1: Authentication (/crm/oauth)

To interact with the Matchouse API, your server must first obtain an authentication token using your provided credentials.

  • Endpoint: POST {Base_URL}/crm/oauth

  • Headers:

    • x-crm-client-id: [Your Client ID]

    • x-crm-client-secret: [Your Client Secret]

  • Response: Returns an x-crm-token valid for 6 hours.

⚠️ Important: Token Caching & Rate Limiting Your system must cache the x-crm-token. Do not call /crm/oauth every time you need to generate a new integration link, as this will result in rate-limiting errors. We recommend caching the token in your backend until it expires, or implementing a background job to refresh the token every 5.5 hours.

Step 2: Generate the Integration Link (/crm/integrate)

Once authenticated, your server will request a unique signed URL for the specific estate agency trying to connect. You must pass your CRM's internal ID for this agency so we can map it correctly later.

  • Endpoint: POST {Base_URL}/crm/integrate

  • Headers:

    • Authorization: Bearer [Your x-crm-token]

  • Payload: Include the agencyId (your CRM's internal unique identifier for this estate agency).

  • Response: Returns a unique signed URL.

Step 3: The User Experience (UI)

In your CRM's user interface, create a clear call-to-action (e.g., a button that says "Click to connect to Matchouse").

When the estate agency clicks this button, redirect them to the unique signed URL generated in Step 2.

  • They will be prompted to log into their existing Matchouse account or register for a new one.

  • Once authorized, Matchouse will securely capture their connection.

Step 4: Receiving API Keys via Webhook

Once the estate agency successfully connects their account, Matchouse will automatically send their property push API keys directly to your CRM's server.

  • Delivery Method: We will make a POST request to the webhook_url you provided during the initial setup.

  • Payload Format: 

    { "x-api-key": "random_long_string", "agencyId": "your_internal_agency_id" }

  • Mapping the Data: You will use the returned agencyId to identify which specific agency just connected, and securely store the x-api-key against their profile in your database.

  • Expected Response: Your server must return a 200 OK HTTP status code upon successfully receiving the payload.

Webhook Retry Policy

If your webhook endpoint fails to return a 200 OK status code (e.g., your server is down or times out), Matchouse will automatically retry the POST request up to 3 times. If all attempts fail, we will notify you via your registered developer email.

Step 5: Pushing Properties

Now that you have the agency's x-api-key, your CRM can automate their property management.

Use this x-api-key to authenticate requests to the Matchouse Listing API to push or update their property listings.