Website API

The Website API allows real estate agencies to build their own custom website around property data that is stored and managed in SweepBright. This documentation explains:

• How properties in SweepBright can be published to a custom website.

• How updates to a property in SweepBright can be synced with the corresponding publication on the custom website. This is useful, e.g. when the price is updated.

• How publications on the custom website can be removed by unpublishing the property in SweepBright. This is useful, e.g. when the property is sold or rented.

• How the above three actions can be done for a project, which is a collection of properties.

• How the custom website can store general leads inside SweepBright. General leads are contacts interested in buying or renting a property but without a specific interest in a particular property.

• How the custom website can store specific leads inside SweepBright. Specific leads are contacts interested in buying or renting a specific property that they found on the custom website.

This documentation is intended for both product managers trying to understand the capabilities of the website API, as well as for developers that are building the custom website that integrates with this website API.

Every feature will be explained from a product perspective (a testing flow that verifies that the experience for the end user is correct) and a technical perspective (what the communication flow between SweepBright and the custom website is) so developers understand how to implement the behavior.

Before continuing, please read the Legal section at the bottom of this page.

Subscribe to our mailing list to stay up to date about the latest changes to the website API:

URL

The API is available at https://website.sweepbright.com/api.

Data Handling

All interactions with the website API happen through a REST API that returns JSON-formatted responses. All API requests must be made over HTTPS and with an access_token provided via an OAuth 2.0 authorization flow.

Rate Limiting

Our API is not build nor intended to be actively used in your application. You are required to download and store any data and files on your own infrastructure. Our API is rate limited and should only be accessed after receiving a webhook.

Image Handling

Images and files can be downloaded via a temporary URL that is outputted in the API responses. The time until the URL expires is also provided in the API response.

URL Structure

We strongly recommend using SweepBrights property id's within the URLs of your custom website, especially for the properties detail page. Good examples are:

• https://full-url-to-websi.te/<property_id>

• https://full-url-to-websi.te/<zipcode>/<property_id>

Development Process

Getting access

Currently, it is not possible to activate and configure the website API from inside SweepBright. Instead, you should follow the steps outlined in this help article to get access. We will first give you access to a testing account.

Development

After you're set up with your testing account, you implement the custom website so it satisfies all Basic Requirements.

Final approval

When you are done developing, please inform us. SweepBright will check if your website satisfies all basic requirements according to the test cases included in each of them. After a positive evaluation, we shall send your credentials for your production account.

When planning your go-live, please account for a week of verification time by SweepBright and for possible adjustments you might need to implement.

1. Publish a property to the custom website

From the user's perspective the following flow should work (through the iOS or web application):

1. Create a new property, with an address, price, description and at least one image.

2. In the Publish section, publish the property to Public API.

3. The status of the publication to Public API changes to Publishing...

4. After maximum 1 hour, the status of the publication changes to Published.

5. In the Public API section a link to the publication on the custom website is available.

6. The link on the custom website shows the property, with address, price, description and image.

Notice that the time it takes for a publication to switch from Publishing to Published depends on the speed with which the website API processes the publish requests and how quickly the link to the custom website is returned.

Technically, this the flow between SweepBright and Public API:

1. When a user publishes a property to the public API channel, this will trigger a webhook. It is important that you immediately respond when this webhook is called, not after fetching the property info and returning the URL.

2. The custom website can fetch the property information by calling the estates endpoint. After storing this data, you can use it to publish the property on the custom website.

3. Once the custom website has created the property and knows the URL of the property on the custom website, the custom website sends back the estates URL endpoint. Note that if the custom website did not send back the URL within 1 hour, the publication will be considered failed.

4. As soon as SweepBright receives the URL of the property on the custom website, the property is considered Published inside SweepBright.

Some additional notes regarding the implementation:

• Notice that the API uses the term estate to refer to a property. Property and estate can be used interchangeably.

• The custom website can only fetch property information after a user has published the property to the website API in SweepBright and the webhook is called. After that, the data is available for fetching for 60 minutes.

• There is no endpoint to fetch all published properties for an agency.

• The publish flow is not completed as long as the URL is not returned. In the meanwhile, the property will remain in a Publishing state. Only when the URL is received do we consider the property as Published. It's important to complete the publish flow: without URL the property cannot be used in several of SweepBright's features.

2. Sync property updates with custom website

From the user's perspective the following flow should work (through the iOS or web application):

1. Follow the steps above to create and publish a property to the website API.

2. Update some information of the property, such as the price.

3. The status of the website API publication is 'Changes not yet published.'

4. Publish the property to the Public API again.

5. The status of the publication to Public API changes to Publishing...

6. After maximum 1 hour, the status of the publication changes to Published.

7. In the Public API section a visitable link to the publication on the custom website is available.

Technically, the flow is exactly the same as for publishing a property to the website API for the first time, with one difference: the request that SweepBright sends to the webhook contains "event": "estate-updated" instead of "event": "estate-added".

3. Remove publication from custom website

From the user's perspective the following flow should work (through the iOS or web application):

1. Follow the steps to create and publish a property to the website API.

2. In the Publish section of the property, unpublish the property from the website API.

3. The status of the publication to Public API changes to Not Published.

Technically, this the flow between SweepBright and Public API:

• When a property is unpublished, the request that SweepBright sends to the webhook contains "event": "estate-deleted".

• After the webhook is sent, SweepBright considers the property as unpublished.

• The custom website is responsible for taking the necessary actions to remove the publication from the website. No additional communication is necessary.

4. Publish, update and unpublish projects

In addition to standalone properties, like a standalone house or a single apartment, SweepBright also supports the concept of projects. A project is a collection of multiple properties (called units in the SweepBright platform).

From the user's perspective, the experience when publishing, updating and unpublishing projects and units depends on the way it is implemented technically. There are two options:

• One-on-one

  • When users publish the project through SweepBright, the custom websites publishes the overall project info on your website. The units data, even though it's available from the estates endpoint, is not used at all.
  • When users publish a single unit through SweepBright, the custom website publishes the unit as a part of the project that was already published on your website.
  • This approach allows for maximum flexibility for agents in (un)publishing units to/from your website.
  • Things to take into account for this approach:
    • Before publishing a unit, users should first publish the project.
    • Before unpublishing a project, users should first unpublish all the units.

• Publish project = publish project + all units

  • When users publish the project through SweepBright, the custom website publishes the overall project info on your website, as well as all the units.
  • This approach is fast, but less flexible (you can't manage publications on the unit level)
  • Things to take into account for this approach:
    • Users should never separately publish units.
    • Publishing or unpublishing units will become tricky, because the publication status on your website and the publication status of units in the Publish section of SweepBright will not be in sync.

We recommend that the custom website follows the second approach. Although this approach is slightly less flexible, it leads to a better user experience. More specifically, if there is a project with 30 units, the agent only has to publish the project and doesn't have to publish all 30 units separately anymore.

As you can see from in the estates endpoint documentation documentation, some fields in the payload will be different depending on the type of property that you are fetching information for. You can use this to determine which type of property the custom website is dealing with.

5. Create a general lead in SweepBright

General leads are contacts interested in buying or renting a property but without a specific interest in a particular property.

From the user's perspective the following flow should work:

• Visit the custom website.

• Click a button to express general interest.

• Pass first name, last name, email and telephone number. Additionally, pass the locale and preferences. Submit the info.

• If the company consists of multiple teams, an unassigned lead (the lead is not assigned to a team) is created under Company & Teams > Unassigned leads in the SweepBright web application. When a Company only has one team, the lead is immediately assigned to this team.

• The contact's details are filled in according to the information that was passed earlier.

• The contact's preferences are filled in according to the information that was passed earlier.

Technically, the custom website should call the general contact request endpoint.

6. Create a specific lead in SweepBright

Specific leads are contacts interested in buying or renting a specific property that they found on the custom website.

From the user's perspective, the following flow should work:

• Visit a property on the custom website.

• Click a button to express interest in this property and ask for more information.

• Pass first name, last name, email, telephone number. Additionally, pass the locale.

• In SweepBright's web application, a lead is created in the contacts list of the team to which the property belongs. In addition, an 'expressed interest' interaction is logged between this lead and the property.

• The contact's details are filled in according to the information that was passed earlier.

• The contact’s preferences are filled in based on the property that he or she expressed interest in. For example, the lead's location preference is set to the postal code of the property and the maximum price is the property’s maximum price times 1.05.

Technically, the custom website should call the the contract request for an estate endpoint. Currently, SweepBright automatically infers the contact's preferences from the property that the contact expressed interest in. Additional preferences that may be passed in the body of the request are ignored.

In the description of the different API endpoints, you will see that you have to specify an Accept header in your request, formatted as application/vnd.sweepbright.v{version}+json, where version specifies the API version. Since the default version (1) we have done improvements and additions to the API, so it's a good idea to regularly check if you can upgrade the version and make the corresponding code changes in your website API client. We will also notify you when a significant update was done that you should be aware of. As a rule, we will always ensure backwards compatibility with older versions unless explicitly communicated otherwise. Our documentation will only include request body examples for the last supported version. Below you can find an overview of changes between versions, so you can easily figure out what changed. If you are building a website API client from scratch, you can safely skip this section.

1 -> 20190920

In version 1, when getting the estates data with GET estates/{id}, the JSON structure of the description, description_title, price_costs, price_taxes, and legal_mentions fields in different locales was inconsistent between standalone properties, projects, and units data inside a project payload. Version 20190920 makes this consistent. Regardless of the type of property (standalone, unit, project), this localized data will always be formatted as follows:

"description_title": {
    "en": "english_title",
    "fr": "french_title",
    "nl": "dutch_title"
},
"description": {
    "en": "english_desc",
    "fr": "french_desc",
    "nl": "dutch_desc"
},
"price_costs": {
    "en": "english_price_costs",
    "fr": "french_price_costs",
    "nl": "dutch_price_costs"
},
"price_taxes": {
    "en": "english_price_taxes",
    "fr": "french_price_taxes",
    "nl": "dutch_price_taxes"
}
"legal_mentions": {
    "en": "english_legal_mentions",
    "fr": "french_legal_mentions",
    "nl": "dutch_legal_mentions"
}

20190920 -> 20191121

Version 20190920 still includes the publish_status when calling GET estates/{id}. However, this feature is not actively supported anymore, so to avoid confusion it was dropped in version 20191121.

20191121 -> 20191206

With 20191206 we're exposing much more legal fields, and we're exposing them in a more sensible format.

When calling GET estates/{id} with Accept: application/vnd.sweepbright.v20191121+json, you'll get:

{
    "id": "4e7b24e6-6d37-48a9-9249-0880bda99ba0",
    ...
    "epc_value": 123,
    "epc_category": "A+",
    "epc_reference": "this-is-the-epc-ref",
    "regulations": {
        "building_permit": true,
        "urban_planning_breach": true,
        "subdivision_authorisation": true,
        "preemptive_right": true,
        "flood_risk_area": true
    },
    "cadastral_income": 785,
    "legal_mentions": {
        "en": "English legal mentions",
        "fr": "Mentions legales francaises",
        "nl": "Nederlandstalige legale vermeldingen"
    },
    ...
}

When calling GET estates/{id} with Accept: application/vnd.sweepbright.v20191206+json, you'll get:

{
    "id": "4e7b24e6-6d37-48a9-9249-0880bda99ba0",
    ...
    "legal": {
        "energy": {
            "e_level": "E90",
            "epc_value": 123,
            "epc_category": "A+",
            "co2_emissions": 999,
            "epc_reference": "this-is-the-epc-ref",
            "total_epc_value": 1000,
            "report_fuel_tank": "conform",
            "report_electricity_gas": "conform"
        },
        "regulations": {
            "heritage_list": true,
            "as_built_report": true,
            "building_permit": true,
            "expropriation_plan": true,
            "registered_building": true,
            "urban_planning_breach": true,
            "site_untapped_activity": true,
            "priority_purchase_right": true,
            "pending_legal_proceedings": true,
            "subdivision_authorisation": true,
            "urban_planning_certificate": true
        },
        "legal_mentions": {
            "en": "English legal mentions",
            "fr": "Mentions legales francaises",
            "nl": "Nederlandstalige legale vermeldingen"
        },
        "property_and_land": {
            "flood_risk": "effective_flood_sensitive_area",
            "purchased_year": 1987,
            "cadastral_income": 785,
            "land_use_designation": "natural_reserve"
        }
    },
    ...
}

As you can see, you can tap into much more legal fields. They are structured differently, and some have also changed:

• premptive_right has been renamed to priority_purchase_right.

• flood_risk is an enum instead of a boolean.

For all the different values that these fields can have, please refer to the schemas in the documentation.

20191206 -> 20210723

Version 20210723 solves some inconsistencies between the JSON Schema described in the documentation and the actual property data structure.

When calling GET estates/{id} with Accept: application/vnd.sweepbright.v20210723+json, you'll get:

{
    "id": "4e7b24e6-6d37-48a9-9249-0880bda99ba0",
    ...
    "legal": {
        "energy": {},
        "regulations": {},
        "legal_mentions": {},
        "property_and_land": {}
    },
    "description": {}
    ...
}

when energy, regulations, legal_mentions, property_and_land and description sections are not set.

Before version 20210723 the above structure was returning empty array, causing errors when using the JSON Schema to validate the property data.

20210723 -> 20221213

Version 20221213 introduces some changes to the property data and a couple of new fields to align SweepBright to the recent legal state directives.

Changes:

• E-Level changes from a string prefixed with E to a number between -999 and 999 (path: legal.energy.e_level).

• Energy Score supports values between -999 and 999 (path: legal.energy.epc_score).

• DPE supports two new values: empty and not_applicable (path: legal.energy.dpe).

• GES supports two new values: empty and not_applicable (path: legal.energy.greenhouse_emissions).

• Units in Building is now allowed for any property type (path: building.units_of_building).

New fields, both in the regulation section for houses, apartments, commercial and office properties:

• Asbestos Certificate as a flag to specify when the property has a Asbestos certificate (path: legal.regulations.asbestos_certificate).

• Asbestos Certificate Number to expose the certificate number (path: legal.regulations.asbestos_certificate_reference).

20221213 -> 20241030

Version 20241030 fixes residential_lots mappings.

Changes:

• Residencial Lots field building.residential_lots field which was incorrectly showing always as null was removed. Use building.construction.residential_lots which has the correct value for the field.

A webhook URL can be defined per company, which will be called everytime a change of an estate is published. We will send a POST request with some JSON metadata to your configured URL. We expect a 200 response.

Confirming hook authenticity

You can confirm the webhook authenticity by calculating a HMAC hash using the SHA-1 hashing algorithm, the JSON payload of the webhook and your OAuth secret key. The calculated hash should be the same as the one found in the X-Hook-Signature header we sent along with the webhook.

Webhook during development

When you are starting to build the integration, SweepBright will ask you to provide a test webhook to set up your test company. Make sure that the webhook you provide us is available on the internet and is not a local webhook. If you want to ease local development, you can use a tool like ngrok to tunnel a publicly available link to your localhost.

Webhook body [POST]

• Request

  • Headers

    Content-Type: application/json
    X-Hook-Signature: "a9e7db538d4592fa5e7098bfa86d0630651435d3"
    

  • Body

          {
              "event": "estate-added|estate-updated|estate-deleted",
              "estate_id": "<estate-id>",
              "happened_at": "2017-01-01T10:10:10",
              "company_id": "3186772c-5ab7-42fe-a8cc-ea1ef8c368d3",
          }
    

• Response 200

These additional terms and conditions (“Additional Terms”) are applicable to the Website Application Programming Interface (“Website API”), together with the General Terms and Conditions of Service (the “GTCS”) and the SweepBright Terms of Use and Privacy Policy (collectively the “Agreement”).

By downloading the Website API documentation or by using the Website API documentation, you (the Customer) accept that such download and/or use is subject to the Agreement, including but not limited to the limitations of liability provisions.

The Website API constitutes an Additional Service provided to the Customer to link its Customer Account to its own website, pursuant to Clause 9.2 of the GTCS.

All defined terms used in these Additional Terms shall have the meaning set forth in the GTCS.

Precedence

In the event of a conflict between these Additional Terms and the GTCS if any, the conflict shall be solved according to the following priority order: (a) Additional Terms, (b) GTCS. For the purpose of the foregoing, an omission shall not of itself be considered to give rise to any conflict or inconsistency.

License

Subject to the terms and conditions of the Agreement, the Supplier (SweepBright NV) grants to the Customer a non-exclusive, personal, non-transferable, revocable right and license to use the Website API, solely to integrate with the Customer’s website by linking the Customer Account to the Customer’s website, which will enable those services to interface and work with the Services, for the duration of the Agreement and solely for the Customer’s internal business operations (the “License”).

Use Restrictions

The Website API is licensed to the Customer for internal business operations only. The Customer acknowledges that the scope of the License granted does not permit the Customer (and the Customer may not allow any third party) to: (i) decompile, disassemble, reverse engineer or attempt to reconstruct, identify or discover any source code, underlying ideas, underlying user interface techniques or algorithms of the Website API by any means whatsoever, or disclose any of the foregoing; or (ii) sublicense, distribute, sell, lend, rent, lease or grant any rights in or to all or any portion of the Website API.

The Customer must comply with all restrictions and terms set forth in the Agreement, including the payment of Subscription Fees. If the Supplier believes, in its sole discretion, that the Customer violated or attempted to violate any term, condition or the spirit of the Agreement, the Supplier may temporarily or permanently revoke the License and the corresponding Additional Service. The License shall be automatically revoked if the Customer unsubscribes from all User Subscriptions.

Personal Data

Where the use of our API involves processing of Data (as defined in the General Terms and Conditions of Service), you acknowledge that you are the Data Controller and warrant that the Data were collected in compliance with the Data Protection Legislation and that you are entitled under the Data Protection Legislation to permit us to process the Data in accordance with the GTCS.

If you use our API to send Data to a third party service, you are responsible to ensure that such third party service is compliant with Data Protection Legislation.

Limitation of liability

In addition to the provisions contained in Clause 16 of the GTCS, the Supplier’s total aggregate liability in contract, tort (including negligence or breach of statutory duty), misrepresentation, restitution or otherwise, arising out of or in connection with the performance, non-performance or contemplated performance of its obligations under these Additional Terms and/or the provision of the Additional Service of Website API shall not exceed an amount corresponding to the total amount of fees, if any, paid by the Customer under these Additional Terms for the License.

Copyright © 2019 SweepBright NV - Last update: August 23, 2019.