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

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

Query Parameters

Request Body

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

[
    {
        "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.

2. 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

3. 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.