SightMap® REST API (v1.20210219)

Download OpenAPI specification:Download

Introduction

The SightMap® API uses standard HTTP verbs to communicate and HTTP status codes to indicate status and errors. All responses come in standard JSON. The SightMap API is served over HTTPS to ensure data privacy; HTTP is not supported.

Versioning

Versions are communicated as VERSION.RELEASE-DATE, where VERSION denotes the version number of the API and prefixed to all API request paths, such as /v1/assets. RELEASE-DATE denotes backwards-compatible changes to the API.

When any non-backwards compatible additions must be made to the API, the version number will be incremented.

Backwards-compatible changes

We consider the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of object IDs or other opaque strings.
  • You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).

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 with the following JSON:

{
  "message": "No API key found in request"
}

If your API key cannot be validated, a 403 status code is returned with the following JSON:

{
  "message": "Invalid authentication credentials"
}

apiKey

An API key sent via the API-Key header.

curl -i -H "API-Key: 12345" https://api.sightmap.com/v1/assets
Security Scheme Type API Key
Header parameter name: API-Key

Experimental features

We provide new API features via experimental flags. This allows users to opt-in for new functionally and provide feedback prior to a feature becoming generally available (GA). We believe in stability without stagnation. This ability allows our team to build and ship best-in-class APIs faster while upholding backwards-compatibility on GA features.

Experimental features are subject to change while undergoing development and feedback. Therefore, they are exempt from any backwards-compatibility guarantees until they reach GA. We do not expect nor recommend using experimental features in production environments unless a partnership has been established with our teams working closely together.

Flags are provided via the Experimental-Flags header. A comma-separated list is expected in order to pass multiple flags on a single request.

curl -i https://api.sightmap.com/v1/assets \
  -H "API-Key: 12345" \
  -H "Experimental-Flags: flag-1,flag-2"

Errors

The SightMap API uses standard HTTP status codes to indicate the success or failure of the API request. The body of the response will be JSON in the following format:

{
  "message": "Not found"
}

Assets

List assets

Returns a list of assets.

Authorizations:
query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    },
  • "data": [
    ]
}

View an asset

Returns a asset.

Authorizations:
path Parameters
asset
required
string

An asset ID

Responses

Response samples

Content type
application/json
{
  • "id": "1323",
  • "uuid": "d5779fbb-43fe-4d54-b642-266ce815a3f3",
  • "market": "multifamily",
  • "name": "The Lofts at New Main",
  • "display_name": "The Lofts at New Main",
  • "description": null,
  • "unit_count": 138,
  • "address_line1": "100 New Main St",
  • "address_line2": null,
  • "address_city": "Cleveland",
  • "address_state": "OH",
  • "address_country": "USA",
  • "address_postal_code": "91801",
  • "address_latitude": 41.433243,
  • "address_longitude": -81.3941872,
  • "created_at": "2017-09-11T17:08:59+00:00",
  • "updated_at": "2019-10-10T04:25:58+00:00"
}

Units

List units

Returns a list of units for an asset.

Authorizations:
path Parameters
asset
required
string

An asset ID.

query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

unit-number
string

A unit number to filter the list on.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    },
  • "data": [
    ]
}

View a unit

Returns a specific unit.

Authorizations:
path Parameters
asset
required
string

An asset ID.

unit
required
string

A unit ID.

Responses

Response samples

Content type
application/json
{
  • "id": "258670",
  • "asset_id": "1323",
  • "building_id": "8265",
  • "floor_id": "4730",
  • "floor_plan_id": "14641",
  • "map_id": "258670",
  • "unit_number": "E13",
  • "area": 700,
  • "view_image_url": null,
  • "created_at": "2017-09-11T17:09:18+00:00",
  • "updated_at": "2018-01-20T03:44:39+00:00"
}

Buildings

List buildings

Returns a list of buildings for an asset.

Authorizations:
path Parameters
asset
required
string

An asset ID.

query Parameters
page
integer <int32>

Request a specific page of resources.

per-page
integer <int32>

Limit the number of returned resources.

Responses

Response samples

Content type
application/json
{
  • "paging": {
    },
  • "data": [