Find Properties

This endpoint finds units with the list of body attributes passed to it.

POST /units/find

Example Request

curl --location --request POST 'https://api.travtus.com/units/find/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
  "address": {
    "country": "United States"
  },
  "group_ids": ["group-1"],
  "after-id": 1
}'

Response

{
  "last_id": 5,
  "units": [
    {
      "identifier": "internal-unit-id-1",
      "unit_number": "1",
      "is_flex": false,
      "full_bathrooms": 1,
      "half_bathrooms": 1,
      "number_of_bedrooms": 2,
      "sqft": 40,
      "address": {
        "building_name": "Building 1",
        "address_line_1": "Blvd Street",
        "address_line_2": "Appartment 12",
        "city": "New York",
        "country": "United States",
        "state": "New York",
        "postal_code": "10001",
        "latitude": 40.730610,
        "longitude": -73.935242
    },
    {
      "identifier": "internal-unit-id-2",
      "unit_number": "2",
      "is_flex": false,
      "full_bathrooms": 1,
      "half_bathrooms": 0,
      "number_of_bedrooms": 1,
      "sqft": 30,
      "address": {
        "building_name": "Building 1",
        "address_line_1": "Blvd Street",
        "address_line_2": "Appartment 10",
        "city": "New York",
        "country": "United States",
        "state": "New York",
        "postal_code": "10001",
        "latitude": 40.730610,
        "longitude": -73.935242
      }
    },
  ]
}

You need to provide exact matches in the body of the request for the attributes of the units you are looking for.

You can provide either a list of group ids through the group_ids parameter or a list of group external references through the groups_external_refs attribute to filter the list of retrieved units down.

Do not provide both, as this will result in the request failing.

If no group_ids or group_external_refs are specified in the request body, the authenticated user will retrieve unit records for all groups they have access to.

Header

Authorization · string · default: "none" · required

The authentication token for your request.

Body

group_ids · [string] · default: "none"

The list of group ids for filtering the retrieved list.

groups_external_refs · [string] · default: "none"

The list of group external references for filtering the retrieved list.

external_ref · string · default: "none"

An external reference for the unit you want to find.

This is typically an identifier you may use for unit records in your own system.

identifier · string · default: "none"

The internal reference for the units you want to find.

has_flex_wall · boolean · default: "none"

Whether the units you want to retrieve are flex apartments or not.

number_of_bathrooms · integer · default: "none"

The number of bathrooms the units you want to find have.

number_of_bedrooms · integer · default: "none"

The number of bedrooms the units you want to find have.

sqft · integer · default: "none"

The square feet surface for the units you want to find.

unit_number · string · default: "none"

The number of the units you want to find.

address · object · default: "none"

Address information for the units you want to find.

Show child attributes

building_name · string

The name of the building for the unit you want to find.

address_line_1 · string

The first line of the address for the unit you want to find.

address_line_2 · string

The second line of the address for the unit you want to find.

city · string

The address’ city for the unit you want to find.

country · string

The address’ country for the unit you want to find.

state · string

The address’ state for the unit you want to find.

postal_code · string

The address’ postal code for the unit you want to find.

latitude · float

The address’ latitude for the unit you want to find.

longitude · float

The address’ longitude for the unit you want to find.

after-id · string · default: "1"

The API returns a maximum of 100 records per call.

You can use this parameter to load the next set of records by passing in the value returned in the response, under last_id.

Response

last_id · integer

The last id in the set of results returned for this API call.

You can use this value in the after-id parameter to load the next set of results.

If there are no more results to load, this value will be -1.

units · [object]

The list of units retrieved by the endpoint

Show unit

identifier · string

The internal identifier for the retrieved unit.

external_ref · string

The external reference for the retrieved unit.

unit_number · string

The number of the retrieved unit.

is_flex · boolean

True if the retrieved unit is a flex apartment, false if it is not.

full_bathrooms · integer

The number of full bathrooms for the retrieved unit.

half_bathrooms · integer

The number of half bathrooms for the retrieved unit.

number_of_bedrooms · integer

The number of bedrooms for the retrieved unit.

sqft · integer

The square feet surface for the retrieved unit.

address · object

The unit’s address.

Show address

building_name · string

The name of the building.

address_line_1 · string · required

The first line of the unit’s address.

address_line_2 · string

The second line of the unit’s address.

city · string

The city of the unit’s address.

country · string

The country in which the unit’s address is located.

state · string · required

The state in which the unit’s address is located.

postal_code · string · required

The postal code for the unit’s address.

latitude · string

The latitude of the unit’s address.

longitude · string

The longitude of the unit’s address.

Errors

Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.

Status Code - 400

Missing Authorization header

{
   "error": {
    "type": "missing_authorization",
    "message": "Your request does not include an 'Authorization' header with a bearer token for your account."
  }
}

Status Code - 401

Expired Authorization header bearer token value

{
   "error": {
    "type": "expired_token",
    "message": "The bearer token you have provided in the 'Authorization' header has expired. Please obtain a new one."
  }
}

Status Code - 401

Invalid Authorization header bearer token value

{
   "error": {
    "type": "invalid_authorization",
    "message": "The bearer token you have provided in the 'Authorization' header is invalid."
  }
}

Status Code - 400

Returned if both of the group_ids and groups_external_refs attributes are provided

Both group ids and external refs provided for the unit find operation

{
   "error": {
    "type": "both_group_identifiers_provided",
    "message": "You have provided both group ids and group external references for the find units operation. Please only provide one of the two."
  }
}

Status Code - 404

Returned if no unit records can be found matching the provided information.

No unit records found for the provided parameters

{
   "error": {
    "type": "not_found",
    "message": "There are no unit records matching the information provided."
  }
}

Example Request

curl --location --request POST 'https://api.travtus.com/units/find/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
  "address": {
    "country": "United States"
  },
  "group_ids": ["group-1"],
  "after-id": 1
}'

Response

{
  "last_id": 5,
  "units": [
    {
      "identifier": "internal-unit-id-1",
      "unit_number": "1",
      "is_flex": false,
      "full_bathrooms": 1,
      "half_bathrooms": 1,
      "number_of_bedrooms": 2,
      "sqft": 40,
      "address": {
        "building_name": "Building 1",
        "address_line_1": "Blvd Street",
        "address_line_2": "Appartment 12",
        "city": "New York",
        "country": "United States",
        "state": "New York",
        "postal_code": "10001",
        "latitude": 40.730610,
        "longitude": -73.935242
    },
    {
      "identifier": "internal-unit-id-2",
      "unit_number": "2",
      "is_flex": false,
      "full_bathrooms": 1,
      "half_bathrooms": 0,
      "number_of_bedrooms": 1,
      "sqft": 30,
      "address": {
        "building_name": "Building 1",
        "address_line_1": "Blvd Street",
        "address_line_2": "Appartment 10",
        "city": "New York",
        "country": "United States",
        "state": "New York",
        "postal_code": "10001",
        "latitude": 40.730610,
        "longitude": -73.935242
      }
    },
  ]
}