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
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
- 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" |
-
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
-
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.
Updated almost 2 years ago