Pushing Pricing Data to SightMap

🚧

Under Construction

This documentation page is a work in progress. Therefore, it is subject to change.

🚧

Experimental Feature

The Pricing Push API is currently an experimental feature. Therefore, the API and this documentation is subject to change. If you have any questions, please email Courtney Hall.

Overview

Engrain provides an open API for customers and third parties to interact with the SightMap® REST API.

Pushing pricing pricing data to SightMap is an experimental feature and is not documented in the OpenAPI specification. Unlike some features, an experimental flag header is not required for pushing pricing data.

Definitions

Term

Definition

Assets

Assets represent the real estate. E.g., An apartment complex or senior living community.

Units

Units represent the individual, indivisible spaces the asset has. For example, a multifamily asset’s unit is an apartment. Pricing and availability information is expected to be associated per unit.

Process

A pricing Process is an information space which holds and associates pricing and availability information to an asset’s units.

Entry

A pricing Entry is single record of pricing & availability data. A unit may have zero, one, or many pricing entries on a given pricing process.

Transaction

Transactions are short-lived resources, which allow for the one-time passing of pricing and availability data from one system to another. Only a single transaction can be open on a pricing process at a time.

Create Pricing Transaction

POST https://api.sightmap.com/v1/assets/{asset}/multifamily/pricing/{process}/ingest

Authentication

For requests which require Authentication, an API Key can be provided by either the api-key query parameter or API-Key header. We recommend the header over the query parameter as it avoids your API key from being stored in browser history and most server logs. If neither query parameter or header is provided, a 401 status code is returned.

Path Parameters

Key

Description

Value type

Required?

asset

An asset id.

String

Required

pricing process

A process id.

String

Required

Query Parameters

Key

Description

Value type

Default Value

Commit

Determines whether or not to keep the transaction open.

0 keeps the transaction open.

1 commits the transaction.

Boolean

0

Request Body

When sending data to SightMap, use the JSON format below.

Key

Description

Value type

Required?

Example value

unit_number

The unit name.

String

Required

4091

provider_id

The unique identifier used to identify a unit in third party system. If another unique identifier does not exist, the unit number can be sent.

String

Required

4931598

price

Price of unit.0 or negative values will be considered unavailable.

Integer

Required

1619

available_on

The date a unit will appear as available. If no date exists but the unit is available, today() can always be used.

Dates should be sent as a date string in ISO-8601 format (YYYY-MM-DD).

String

Required

2022-12-07

lease_term

Length, in months, of a lease — nullable.

Integer

Optional

11

lease_starts on

Date a lease would start — nullable. If no date is available, null should be used.

Dates should be sent as a date string in ISO-8601 format (YYYY-MM-DD).

String

Optional

2021-12-07

leasing_fields

Leasing field nodes can be used to include extra information about a unit. They are intended to help create online leasing urls, so an end-user may apply or take action to reserving a unit. Keys are not dictated by SightMap; any key name can be created.

Array

Optional


"leasing_fields": { 
      "floorplan_id": "1040185",
      "unit_space_id": "4931598",
      "apply_url": "https://example.com"
    }

[
    {
        "unit_number": "E13",
        "provider_id": "4931598",
        "price": 1619,
        "lease_term": 11,
        "available_on": "2020-12-05",
        "lease_starts_on": "2021-12-07",
        "leasing_fields": {
            "floorplan_id": "1040185",
            "unit_space_id": "4931598",
            "apply_url": "https://example.com"
        }
    },
    {
        "unit_number": "W13",
        "provider_id": "4931598",
        "price": 1619,
        "lease_term": 10,
        "available_on": "2020-12-05",
        "lease_starts_on": "2021-12-07",
        "leasing_fields": {
            "floorplan_id": "1040185",
            "unit_space_id": "4931598",
            "apply_url": "https://example.com"
        }
    }
]

Making a Request

Data must be sent as JSON via the POST method to the process ingest url.

Transactions

SightMap allows multiple POST requests to be sent during the course of a single transaction. This is helpful if large quantities of data are being sent, commonly seen with revenue management data.

A transaction will time out after 30 minutes, if not committed. Timed-out transactions have the status “expired.”

If sending a complete data set, set the commit query parameter to true, e.g., commit=1.

https://api.sightmap.com/v1/assets/{asset}/multifamily/pricing/{process}/ingest?commit=1

If sending multiple requests, one may keep the transaction open by setting commit to false, e..g, commit=0.

To make multiple requests for one transactions

  1. POST to the ingest URL to open the transaction, using commit=0.
    https://api.sightmap.com/v1/assets/{asset}/multifamily/pricing/{process}/ingest?commit=0.

The 200 response will return a node titled transaction_ingest_url. It will contain a transaction id. If there was another error, the transaction id will be included in the header response.

Header Key

Value

Example Value

Link

url,relation

<https://api.sightmap.com/v1/assets/1323/multifamily/pricing/5803/transactions/15176880>; rel="transaction"

  1. Additional POST requests must be sent to the respective transaction. Attempting to open another transaction will return 409.
    https://api.sightmap.com/v1/assets/{asset}/multifamily/pricing/{process}/transactions/{transaction}/ingest?commit=0

  2. To commit the transaction, the last request must be sent with commit=1.
    https://api.sightmap.com/v1/assets/{asset}/multifamily/pricing/{process}/transactions/{transaction}/ingest?commit=1

Testing and Troubleshooting

To see the status of a transaction, make a GET request to
https://api.sightmap.com/v1/assets/{asset}/multifamily/pricing/{process}/transactions/{transaction}

The status value will indicate if the transaction has been completed, has expired, or is pending. The source_count will represent the number of files sent during the transaction.

{
    "id": "15196498",
    "uuid": "44daf2ca-ba0a-4fe8-8ce6-141b23dd2185",
    "asset_id": "1323",
    "process_id": "5803",
    "pricing_strategy": "flat_pricing",
    "status": "finished",
    "source_count": 1,
    "expires_in": null,
    "created_at": "2022-04-21T19:02:51+00:00",
    "queued_at": "2022-04-21T19:02:51+00:00",
    "started_at": "2022-04-21T19:02:58+00:00",
    "ended_at": "2022-04-21T19:02:58+00:00"
}

To view sent pricing entries, use List Pricing Entries for the respective process. The created_at value will show when the data was received.

To view units, use List Pricing Units for the respective process.

If the transactions appear successful, but prices are not displaying for units, make sure you have included all of the required fields in your POST requests.

If a unit is still not displaying as expected, further mapping with the provider id may be useful. In the example below, we see null for the price and null for the provider id. Mapping the provider ids may resolve the issue.

{
    "id": "966828",
    "pricing_id": "3580",
    "provider_id": null,
    "unit_number": "010124",
    "status": null,
    "price": null,
    "full_price": null,
    "specials_description": null,
    "available_on": null,
    "updated_at": "2020-04-29T18:53:49+00:00",
    "created_at": "2020-04-29T18:53:49+00:00"
}

To map provider IDs, use Update Pricing Units. In the request body, include the unit id and the desired provider id.

After updating the unit, the List Pricing Units response will contain a mapped provider ID.


What’s Next