Pushing Pricing Data to SightMap

🚧

Under Construction

This documentation page is a work in progress.

🚧

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 Ralph Legge.

Overview

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

Pushing 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

TermDefinition
AssetsAssets represent the real estate. E.g., An apartment complex or senior living community.
UnitsUnits 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.
ProcessA pricing Process is an information space which holds and associates pricing and availability information to an asset’s units.
EntryA pricing Entry is single record of pricing & availability data. A unit may have zero, one, or many pricing entries on a given pricing process.
TransactionTransactions 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

KeyDescriptionValue typeRequired?
assetAn asset id.StringRequired
pricing processA process id.StringRequired

Query Parameters

KeyDescriptionValue typeDefault Value
CommitDetermines whether or not to keep the transaction open.

0 keeps the transaction open.

1 commits the transaction.
Boolean0

Request Body

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

KeyDescriptionValue typeRequired?Example value
unit_numberThe unit name.StringRequired4091
provider_idThe unique identifier used to identify a unit in third party system. If another unique identifier does not exist, the unit number can be sent.StringRequired4931598
pricePrice of unit.0 or negative values will be considered unavailable.IntegerRequired1619
available_onThe 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).
StringRequired2022-12-07
lease_termLength, in months, of a lease — nullable.IntegerOptional11
lease_starts onDate 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).
StringOptional2021-12-07
leasing_fieldsLeasing 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.ArrayOptional "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 KeyValueExample Value
Linkurl,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