Introduction

ListSMRT will be building an API integration with client’s existing systems, enabling them to use output generated from ListSMRT to their system. With this API, clients can:

• Retrieve and update data from their CMS to ListSMRT

• Using ListSMRT to generate content details for their listings

• Push it back to their CMS system instantly.

General Flow

1. The client will need to add a new button into their CMS that is basically just a URL (https://api-app.listsmrt.com/api/v1/client/authorize/?api_key=meowmeowmeow ) pointing to Listsmrt based on our provided format.

2. When the user clicks the URL, it will redirect them to Listsmrt platform.

3. Users will follow the usual flow (log in if they haven't) and generate the content.

4. The webhook is then triggered and sends the data to the client system.

5. The webhook will be triggered when the user manually clicks the button "Send data to CRM" to confirm.

6. Developers on the client side will need to implement their solution for receiving our webhook data and storing it into their system.

Preparation Steps

To seamlessly integrate with ListSMRT's Generation Page and automate the property listing generation process, follow these steps:

Generate API Key

Please contact admin to generate an API Key. This key will serve as the authentication token for accessing ListSMRT's API.

API Key: DjEzRb8PkMvFY5YXgQhaW6dTySKcV5tmpepuV630Kn4xe5TRfFxNYkv0HnFkh4hH

Whitelist Domains

The user admin must whitelist the domain(s) that will be making API requests to ListSMRT (Please contact admin to whitelist the domain(s)). This ensures secure communication between the client's CMS system and ListSMRT.

Domain: https://example.com

Configure Webhook

The user admin should set up a webhook URL and a secret key. This URL will be used to receive data generated by ListSMRT (Please contact admin to set up a webhook URL and a secret key). The secret key adds an extra layer of security to the webhook communication.

Webhook URL: https://api-example.com/property-notification-handler

Secret Key: Ba2R1DUHZy7avEvM7ty2zLYX

Integration Steps

Follow these steps to seamlessly integrate ListSMRT's Generation Page:

Implement Button Element HTML

The client needs to implement an HTML button element that redirects to the authorization page:

https://api-app.listsmrt.com/api/v1/client/authorize/?api_key=DjEzRb8PkMvFY5YXgQhaW6dTySKcV5tmpepuV630Kn4xe5TRfFxNYkv0HnFkh4hH&address=SydneyNSW,Australia&type=House&bed=2&bath=1&garage=1&parking=1&metadata=propertyId:1,userId:1

• The URL requires the apiKey query parameter along with other relevant parameters to pre-populate values on ListSMRT's Generation Page.

• ListSMRT's system will verify the API key, whitelist domains, and user login status before granting authorization.

• Note: Users have the flexibility to include additional metadata parameters (e.g., property ID, user ID) to cater to their specific requirements. This metadata will be attached to the payload sent via the webhook.

The following are the parameters that the user needs to include in the URL's details

Property Types

The specific property types can vary depending on the campaign type. In this documentation, we will outline the property types associated with two common campaign types: Residential Sale/Lease and Commercial Sale/Lease.

1. Residential Property Types:

2. Commercial Property Types:

Features

Below is a list of features available in the ListSMRT system:

Generate Content

• Upon successful authorization, users will be directed to the "Generate" page.

• The page will be automatically populated based on parameters sent by the client's Content Management System (CMS).

• Users can review the populated information and make any necessary adjustments.

• Clicking the "Generate" button triggers the content generation process.

• After clicking, users will be redirected to the "Result Generate" page.

Trigger Notification

Example of how the HTTP notification will be sent from ListSMRT side:

// This example is built with Node.js

const axios = require('axios');

const url = 'https://api-example.com/property-notification-handler/';
const headers = {
  'User-Agent': 'ListSMRT',
  'ListSMRT-Signature': 't=1693446511,v1=15af584462edbb5052d302600bb2f832be45f608a5479a9209e324e4f7458233',
  'Content-type': 'application/json',
};

const data = {
  "created": "2023-09-25T06:38:50.180Z",
  "type": "property.generate-content",
  "data": {
    "bed": 3,
    "bath": 4,
    "type": "Townhouse",
    "garage": 2,
    "address": "111 Harrington Street",
    "parking": 3,
    "highlight": "Strategic location",
    "land_size": "",
    "land_rates": "",
    "land_status": "",
    "perfect_for": null,
    "tenure_type": "",
    "water_rates": "",
    "weekly_rent": "",
    "strata_rates": "",
    "the_location": true,
    "campaign_type": "Sale",
    "land_area_max": "",
    "land_area_min": "",
    "tone_of_voice": "Neutral",
    "floor_area_max": "",
    "floor_area_min": "",
    "language_input": "en",
    "language_output": "en",
    "feature_details_id": "1,7,15,19",
    "nabers_energy_rating": "",
    "metadata": {
      "requestId": "mUvZ3voNOQwzcmuJjnR2GXccd8looWlo",
      "secretKey": "IvXfgldQYokWHcgM7b9E664NeemPAylj"
    },
  },
  "result": "Check out this spacious 3 bed, 4 bath townhouse with a strategic location! Don't miss your chance to own it. #ForSale #Townhouse"
}

axios.post(url, data, { headers })
  .then((response) => {
    console.log('Response:', response.data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

curl --request POST \
  --url https://api-example.com/property-notification-handler \
  --header 'Content-Type: application/json' \
  --header 'ListSMRT-Signature: t=1693446511,v1=15af584462edbb5052d302600bb2f832be45f608a5479a9209e324e4f7458233' \
  --header 'User-Agent: ListSMRT' \
  --data '{
    "created": "2023-09-25T06:38:50.180Z",
    "type": "property.generate-content",
    "data": {
      "bed": 3,
      "bath": 4,
      "type": "Townhouse",
      "garage": 2,
      "address": "111 Harrington Street",
      "parking": 3,
      "highlight": "Strategic location",
      "land_size": "",
      "land_rates": "",
      "land_status": "",
      "perfect_for": null,
      "tenure_type": "",
      "water_rates": "",
      "weekly_rent": "",
      "strata_rates": "",
      "campaign_type": "Sale",
      "land_area_max": "",
      "land_area_min": "",
      "tone_of_voice": "Neutral",
      "floor_area_max": "",
      "floor_area_min": "",
      "language_input": "en",
      "language_output": "en",
      "feature_details_id": "1,7,15,19",
      "nabers_energy_rating": "",
      "metadata": {
        "requestId": "mUvZ3voNOQwzcmuJjnR2GXccd8looWlo",
        "secretKey": "IvXfgldQYokWHcgM7b9E664NeemPAylj"
      },
    },
    "result": "Check out this spacious 3 bed, 4 bath townhouse with a strategic location! Don'\''t miss your chance to own it. #ForSale #Townhouse"
  }'

• Once the content has been generated, users have the option to manually trigger a notification.

• The notification sends the generated content's data to the preconfigured URL in the CMS.

• The payload includes any metadata provided by the user.

Webhook

To ensure a secure and reliable data exchange between client's CMS system and ListSMRT, follow these guidelines for setting up and managing the webhook integration:

URL and Security

• ListSMRT's system requires a client's webhook to use HTTPS for secure data transmission and POST method.

• When ListSMRT sends data to the client's webhook, the system must respond with an HTTP status code 200 OK to acknowledge successful receipt of the data.

Signature

• For enhanced security, each webhook payload includes a signature.

• The signature is a unique token that ListSMRT generates for each payload, which the client's CMS system can use to verify the authenticity of the incoming request.

• Before processing the payload, the client CMS system should calculate the signature using the same algorithm provided by ListSMRT and compare it with the signature included in the payload.

Validate Signature

Example of how to validate signature:

// This example is built with Node.js

const crypto = require("crypto");
const express = require("express");
const bodyParser = require("body-parser");

const app = express();

// Middleware to parse JSON payloads
app.use(bodyParser.json());

// Your endpoint's signing secret
const API_KEY =
  "DjEzRb8PkMvFY5YXgQhaW6dTySKcV5tmpepuV630Kn4xe5TRfFxNYkv0HnFkh4hH";

// Your custom middleware to verify the signature
app.use((req, res, next) => {
  const header = req.get("ListSMRT-Signature");
  const elements = header.split(",");

  let timestamp;
  let receivedSignature;

  // Step 1: Extract timestamp and signatures from the header
  for (const element of elements) {
    const [prefix, value] = element.split("=");
    if (prefix === "t") {
      timestamp = value;
    }
    if (prefix === "v1") {
      receivedSignature = value;
    }
  }

  // Step 2: Prepare the signed_payload string
  const payload = JSON.stringify(req.body);
  const signedPayload = `${timestamp}.${payload}`;

  // Step 3: Determine the expected signature
  const hmac = crypto.createHmac("sha256", API_KEY);
  const expectedSignature = hmac.update(signedPayload).digest("hex");

  // Step 4: Compare the signatures
  let isValid = false;
  if (
    crypto.timingSafeEqual(
      Buffer.from(expectedSignature),
      Buffer.from(receivedSignature)
    )
  ) {
    const currentTimestamp = Math.floor(Date.now() / 1000);
    if (Math.abs(currentTimestamp - timestamp) < 300) {
      // 5 minutes tolerance
      isValid = true;
    }
  }

  if (isValid) {
    next();
  } else {
    res.status(401).send("Invalid signature");
  }
});

app.post("/property-notification-handler", (req, res) => {
  res.send("Payload verified");
});

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
});

Example of how to validate signature from ListSMRT:

Step 1: Extract the timestamp and signatures from the header

• Begin by splitting the header using the comma (,) character as the separator. This operation generates a list of individual elements. Proceed to split each element further using the equals (=) character as the separator, resulting in pairs of prefixes and values. The prefix "t" signifies the timestamp, while the prefix "v1" denotes the signature.

Step 2: Prepare the signed_payload string

• Formulate the signed_payload string by combining the following components:
  • The timestamp, presented as a string.
  • The period (.) character.
  • The JSON payload, which corresponds to the content of the request body.

Step 3: Determine the expected signature

• Calculate an HMAC (Hash-Based Message Authentication Code) using the SHA256 hashing algorithm. Utilize the signing secret associated with the endpoint as the cryptographic key, and take the signed_payload string as the input message.

Step 4: Compare the signatures

• Match the signature(s) found within the header against the anticipated signature. In case of an exact match, calculate the time disparity between the current timestamp and the received timestamp. Subsequently, assess whether this disparity falls within an acceptable range defined by your tolerance level.

• To thwart timing-based attacks, utilize a constant-time string comparison method to equate the anticipated signature with each of the received signature.