Agents API Reference

List Agents

GET /api/v1/agents

Retrieve a list of agents based on various filter criteria.

Query Parameters

Parameter	Type	Description
page	Number	Page number (default: 1)
limit	Number	Number of items per page (default: 20, max: 100)
id	Number	Numeric ID of the agent
s	String	Search term for agent name, email, or associated website
accessKey	String	Access key for website filtering
hostname	String	Hostname for website filtering
websiteID	Number	Website ID for filtering
suburb	String	Suburb for location-based filtering
state	String	State for location-based filtering
postcode	String	Postcode for location-based filtering
fullSuburb	String	Full suburb details for location-based filtering
region	String	Region Names(s), can be comma-separated
areaname	String	Area Names(s), can be comma-separated
address	String	Address for location-based filtering
email	String	Agent's email address (agency or CRM)
name	String	Agent's name (partial match)
slug	String	Agent's unique slug
department	String	Comma-separated list of departments

Example Request

javascript

const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/agents?name=John&department=sales", { headers })
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response

json

{
  "total": 2705,
  "hasNext": true,
  "totalPage": 136,
  "data": [
    {
      "id": 12345,
      "websiteID": 321,
      "officeID": ["123", "456"],
      "name": "John Doe",
      "firstname": "John",
      "lastname": "Doe",
      "slug": "john-doe",
      "telephone": [
        {
          "number": "9600 0000",
          "type": "BH"
        },
        {
          "number": "0411 000 000",
          "type": "mobile"
        }
      ],
      "email": "johndoe@realestatewebsite.com.au",
      "profileVideo": "",
      "departments": ["principal", "sales"],
      "positions": ["Group Principal"],
      "profileImage": "https://images.realestatewebsite.com.au/Lara-2.jpg",
      "profileLink": "https://realestatewebsite.com.au/agents/ray-fayad/",
      "listingsStats": [
        {
          "totalListings": 51,
          "totalListingValues": 47210000,
          "totalSoldPrices": 0,
          "totalRentPrices": 0,
          "status": "current",
          "listingType": "residential",
          "modtime": "2024-09-09T14:55:57.000Z"
        },
        {
          "totalListings": 22,
          "totalListingValues": 139230000,
          "totalSoldPrices": 148230000,
          "totalRentPrices": 0,
          "status": "sold",
          "listingType": "commercial",
          "modtime": "2024-09-05T12:32:00.000Z"
        },
        {
          "totalListings": 178,
          "totalListingValues": 201382000,
          "totalSoldPrices": 201310000,
          "totalRentPrices": 0,
          "status": "sold",
          "listingType": "land",
          "modtime": "2024-09-05T12:32:00.000Z"
        },
        {
          "totalListings": 176,
          "totalListingValues": 183835500,
          "totalSoldPrices": 182945500,
          "totalRentPrices": 0,
          "status": "sold",
          "listingType": "residential",
          "modtime": "2024-09-05T12:35:01.000Z"
        },
        {
          "totalListings": 12,
          "totalListingValues": 12825000,
          "totalSoldPrices": 0,
          "totalRentPrices": 0,
          "status": "current",
          "listingType": "commercial",
          "modtime": "2024-09-06T12:04:51.000Z"
        },
        {
          "totalListings": 3,
          "totalListingValues": 2100000,
          "totalSoldPrices": 0,
          "totalRentPrices": 0,
          "status": "current",
          "listingType": "land",
          "modtime": "2024-08-15T00:50:04.000Z"
        }
      ],
      "socialMedia": {
        "facebook": "",
        "twitter": "",
        "instagram": "",
        "linkedIn": "",
        "youtube": ""
      },
      "website": {
        "websiteID": 321,
        "name": "Real Estate Website",
        "link": "https://realestatewebsite.com.au/",
        "accessKey": "eBAPN6IJmCmf2kpPlGt8",
        "address": {
          "fullAddress": ",",
          "streetAddress": "",
          "fullSuburb": ",",
          "subNumber": "",
          "lotNumber": "",
          "streetNumber": "",
          "street": "",
          "suburb": "",
          "state": "",
          "postcode": "",
          "latitude": "-33.8668623",
          "longitude": "151.209658"
        },
        "config": {
          "primaryColor": "#000000",
          "secondaryColor": "#f2f2f2",
          "tertiaryColor": "",
          "video": "",
          "cloudFrontCDN": "/",
          "cloudFlareCDN": "http://images.realestatewebsite.com.au/",
          "listingTypes": {
            "hasForSale": true,
            "hasForRent": true
          }
        },
        "integrations": {
          "reviews": "",
          "offmarketLink": "",
          "propertyEstimateLink": "https://realestatewebsite.com.au/property-estimate/",
          "propertyAppraisalLink": "https://realestatewebsite.com.au/property-appraisal/",
          "switchToUsLink": "https://realestatewebsite.com.au/property-management/#switch-to-us-section",
          "suburbProfileLink": "https://realestatewebsite.com.au/suburb-profiles/",
          "privacyPolicyLink": ""
        },
        "logo": {
          "light": "https://assets-agencyhub.stepps.net/realestatewebsite/logo-light.png",
          "dark": "https://assets-agencyhub.stepps.net/realestatewebsite/logo-light.png",
          "override": ""
        },
        "hostname": "realestatewebsite.com.au"
      },
      "createdAt": "2024-01-29T00:01:04.384Z",
      "updatedAt": "2024-09-09T05:16:23.589Z"
    }
    // ... more agents
  ]
}

Get a Single Agent

GET /api/v1/agents/{id}

Retrieve details of a specific agent by their ID.

Path Parameters

Parameter	Type	Description
id	String	Unique identifier of the agent (can be MongoDB ObjectId or numeric ID)

Example Request

javascript

const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/agents/12345", { headers })
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response

json

{
  "id": 12345,
  "websiteID": 321,
  "officeID": ["123", "456"],
  "name": "John Doe",
  "firstname": "John",
  "lastname": "Doe",
  "slug": "john-doe",
  "telephone": [
    {
      "number": "9600 0000",
      "type": "BH"
    },
    {
      "number": "0411 000 000",
      "type": "mobile"
    }
  ],
  "email": "johndoe@realestatewebsite.com.au",
  "profileVideo": "",
  "biography": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
  "departments": ["principal", "sales"],
  "positions": ["Group Principal"],
  "profileImage": "https://images.realestatewebsite.com.au/johndoe.jpg",
  "profileLink": "https://realestatewebsite.com.au/agents/john-doe/",
  "listingsStats": [
    {
      "totalListings": 51,
      "totalListingValues": 47210000,
      "totalSoldPrices": 0,
      "totalRentPrices": 0,
      "status": "current",
      "listingType": "residential",
      "modtime": "2024-09-09T14:55:57.000Z"
    },
    {
      "totalListings": 22,
      "totalListingValues": 139230000,
      "totalSoldPrices": 148230000,
      "totalRentPrices": 0,
      "status": "sold",
      "listingType": "commercial",
      "modtime": "2024-09-05T12:32:00.000Z"
    },
    {
      "totalListings": 178,
      "totalListingValues": 201382000,
      "totalSoldPrices": 201310000,
      "totalRentPrices": 0,
      "status": "sold",
      "listingType": "land",
      "modtime": "2024-09-05T12:32:00.000Z"
    },
    {
      "totalListings": 176,
      "totalListingValues": 183835500,
      "totalSoldPrices": 182945500,
      "totalRentPrices": 0,
      "status": "sold",
      "listingType": "residential",
      "modtime": "2024-09-05T12:35:01.000Z"
    },
    {
      "totalListings": 12,
      "totalListingValues": 12825000,
      "totalSoldPrices": 0,
      "totalRentPrices": 0,
      "status": "current",
      "listingType": "commercial",
      "modtime": "2024-09-06T12:04:51.000Z"
    },
    {
      "totalListings": 3,
      "totalListingValues": 2100000,
      "totalSoldPrices": 0,
      "totalRentPrices": 0,
      "status": "current",
      "listingType": "land",
      "modtime": "2024-08-15T00:50:04.000Z"
    }
  ],
  "socialMedia": {
    "facebook": "",
    "twitter": "",
    "instagram": "",
    "linkedIn": "",
    "youtube": ""
  },
  "website": {
    "websiteID": 321,
    "name": "Real Estate Website",
    "link": "https://realestatewebsite.com.au/",
    "accessKey": "eBAPN6IJmCmf2kpPlGt8",
    "address": {
      "fullAddress": ",",
      "streetAddress": "",
      "fullSuburb": ",",
      "subNumber": "",
      "lotNumber": "",
      "streetNumber": "",
      "street": "",
      "suburb": "",
      "state": "",
      "postcode": "",
      "latitude": "-33.8668623",
      "longitude": "151.209658"
    },
    "config": {
      "primaryColor": "#000000",
      "secondaryColor": "#f2f2f2",
      "tertiaryColor": "",
      "video": "",
      "cloudFrontCDN": "/",
      "cloudFlareCDN": "http://images.realestatewebsite.com.au/",
      "listingTypes": {
        "hasForSale": true,
        "hasForRent": true
      }
    },
    "integrations": {
      "reviews": "",
      "offmarketLink": "",
      "propertyEstimateLink": "https://realestatewebsite.com.au/property-estimate/",
      "propertyAppraisalLink": "https://realestatewebsite.com.au/property-appraisal/",
      "switchToUsLink": "https://realestatewebsite.com.au/property-management/#switch-to-us-section",
      "suburbProfileLink": "https://realestatewebsite.com.au/suburb-profiles/",
      "privacyPolicyLink": ""
    },
    "logo": {
      "light": "https://assets-agencyhub.stepps.net/realestatewebsite/logo-light.png",
      "dark": "https://assets-agencyhub.stepps.net/realestatewebsite/logo-light.png",
      "override": ""
    },
    "hostname": "realestatewebsite.com.au"
  },
  "createdAt": "2024-01-29T00:01:04.384Z",
  "updatedAt": "2024-09-09T05:16:23.589Z"
}

Create an Agent

POST /api/v1/agents

Create a new agent.

Request Body

Field	Type	Description	Example
name	String	Full name of the agent (required)	John Doe
firstname	String	First name of the agent (required)	John
lastname	String	Last name of the agent (required)	Doe
websiteID	Number	Website ID associated with the agent (required)	321
email	Object	Agent's email addresses	{ agency: "johndoe@realestatewebsite.com.au", crm: "johndoe@crm.com.au" }
telephone	Array of Object	Agent's phone numbers	[ { number: "9600 0000", type: "BH" }, { number: "0411 000 000", type: "mobile" } ]
departments	String[]	List of departments the agent belongs to	["sales", "administrator"]
profileImage	String	URL of the agent's profile image	https://assets-agencyhub.stepps.net/realestatewebsite/johndoe.jpg
biography	String	Agent's biography	string content about the agent
socialMedia	Object	Agent's social media links	{ facebook: "", twitter: "", instagram: "", linkedIn: "", youtube: "" }

Example Request

javascript

const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
  "Content-Type": "application/json",
};

const body = JSON.stringify({
  name: "Jane Smith",
  firstname: "Jane",
  lastname: "Smith",
  websiteID: 67890,
  email: {
    agency: "jane.smith@agency.com",
    crm: "jane.smith@crm.com",
  },
  telephone: [
    {
      number: "9600 0000",
      type: "BH",
    },
    {
      number: "0411 000 000",
      type: "mobile",
    },
  ],
  departments: ["sales", "rentals"],
  profileImage: "https://assets-agencyhub.stepps.net/realestatewebsite/johndoe.jpg",
  biography: "string content about the agent",
  socialMedia: {
    facebook: "https://facebook.com/john-doe",
    twitter: "",
    instagram: "https://www.instagram.com/john-doe",
    linkedIn: "",
    youtube: "",
  },
});

fetch("https://agencyhubapi.stepps.net/api/v1/agents", {
  method: "POST",
  headers: headers,
  body: body,
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response

json

{
  "name": "Jane Smith",
  "firstname": "Jane",
  "lastname": "Smith",
  "websiteID": 67890,
  "email": {
    "agency": "jane.smith@agency.com",
    "crm": "jane.smith@crm.com"
  },
  "telephone": [
    {
      "number": "9600 0000",
      "type": "BH"
    },
    {
      "number": "0411 000 000",
      "type": "mobile"
    }
  ],
  "departments": ["sales", "rentals"],
  "profileImage": "https://assets-agencyhub.stepps.net/realestatewebsite/johndoe.jpg",
  "biography": "string content about the agent",
  "socialMedia": {
    "facebook": "https://facebook.com/john-doe",
    "twitter": "",
    "instagram": "https://www.instagram.com/john-doe",
    "linkedIn": "",
    "youtube": ""
  }
}

Update an Agent

PUT /api/v1/agents/{id}

Update an existing agent's information.

Path Parameters

Parameter	Type	Description
id	String	Unique identifier of the agent (can be MongoDB ObjectId or numeric ID)

Request Body

Include any fields from the IAgent interface that you want to update.

Example Request

javascript

const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
  "Content-Type": "application/json",
};

const body = JSON.stringify({
  biography: "Jane has been in real estate for 15 years...",
  departments: ["sales", "rentals", "commercial"],
});

fetch("https://agencyhubapi.stepps.net/api/v1/agents/12346", {
  method: "PUT",
  headers: headers,
  body: body,
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response

json

{
  "id": 12345,
  "websiteID": 321,
  "officeID": ["123", "456"],
  "name": "John Doe",
  "firstname": "John",
  "lastname": "Doe",
  "slug": "john-doe",
  "telephone": [
    {
      "number": "9600 0000",
      "type": "BH"
    },
    {
      "number": "0411 000 000",
      "type": "mobile"
    }
  ],
  "email": "johndoe@realestatewebsite.com.au",
  "profileVideo": "",
  "biography": "Jane has been in real estate for 15 years...",
  "departments": ["sales", "rentals", "commercial"],
  "positions": ["Group Principal"],
  "profileImage": "https://images.realestatewebsite.com.au/johndoe.jpg",
  "profileLink": "https://realestatewebsite.com.au/agents/john-doe/",
  "socialMedia": {
    "facebook": "",
    "twitter": "",
    "instagram": "",
    "linkedIn": "",
    "youtube": ""
  },
  "createdAt": "2024-01-29T00:01:04.384Z",
  "updatedAt": "2024-09-09T05:16:23.589Z"
}

Delete an Agent

DELETE /api/v1/agents/{id}

Delete an agent from the system.

Path Parameters

Parameter	Type	Description
id	String	Unique identifier of the agent (can be MongoDB ObjectId or numeric ID)

Example Request

javascript

const headers = {
  "x-access-key": "your_access_key_here",
  "x-secret-key": "your_secret_key_here",
};

fetch("https://agencyhubapi.stepps.net/api/v1/agents/12346", {
  method: "DELETE",
  headers: headers,
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Example Response

json

{
  "id": 12345,
  "websiteID": 321,
  "officeID": ["123", "456"],
  "name": "John Doe",
  "firstname": "John",
  "lastname": "Doe",
  "slug": "john-doe",
  "telephone": [
    {
      "number": "9600 0000",
      "type": "BH"
    },
    {
      "number": "0411 000 000",
      "type": "mobile"
    }
  ],
  "email": "johndoe@realestatewebsite.com.au",
  "profileVideo": "",
  "biography": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.",
  "departments": ["principal", "sales"],
  "positions": ["Group Principal"],
  "profileImage": "https://images.realestatewebsite.com.au/johndoe.jpg",
  "profileLink": "https://realestatewebsite.com.au/agents/john-doe/",
  "socialMedia": {
    "facebook": "",
    "twitter": "",
    "instagram": "",
    "linkedIn": "",
    "youtube": ""
  },
  "createdAt": "2024-01-29T00:01:04.384Z",
  "updatedAt": "2024-09-09T05:16:23.589Z"
}

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with our servers.

Code	Description
200	OK - The request was successful
400	Bad Request - The request was invalid or cannot be served
401	Unauthorized - The request requires authentication
403	Forbidden - The server understood the request but refuses to authorize it
404	Not Found - The requested resource could not be found
500	Internal Server Error - The server encountered an unexpected condition

For more information on using these endpoints, please refer to our Authentication Guide and Quick Start Guide.

Agents API Reference ​

List Agents ​

Query Parameters ​

Example Request ​

Example Response ​

Get a Single Agent ​

Path Parameters ​

Example Request ​

Example Response ​

Create an Agent ​

Request Body ​

Example Request ​

Example Response ​

Update an Agent ​

Path Parameters ​

Request Body ​

Example Request ​

Example Response ​

Delete an Agent ​

Path Parameters ​

Example Request ​

Example Response ​

Error Handling ​

Agents API Reference

List Agents

Query Parameters

Example Request

Example Response

Get a Single Agent

Path Parameters

Example Request

Example Response

Create an Agent

Request Body

Example Request

Example Response

Update an Agent

Path Parameters

Request Body

Example Request

Example Response

Delete an Agent

Path Parameters

Example Request

Example Response

Error Handling