ButterflyMX API V3

API Endpoint

OAuth2 Authentication

The ButterflyMX API V3 implements the Authorization Grant Type Flow and issues an access_token along with a refresh_token. The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token.

Obtaining an authorization code (Authentication)

To begin the authorization flow, your application will need to construct a URL like the following and open a browser to that URL: https://accountssandbox.butterflymx.com/oauth/authorize?client_id=$CLIENT_ID&redirect_uri=https://usersandbox.butterflymx.com/oauth/callbacks/butterflymx&response_type=code&client_secret=$CLIENT_SECRET

Obtaining an access_token

To obtain a valid access_token and refresh_token, your application will need to send the $CLIENT_ID, $CLIENT_SECRET and $code to the ButterflyMX token endpoint:

curl --location --request POST 'https://accountssandbox.butterflymx.com/oauth/token' \
--form 'grant_type=authorization_code' \
--form 'code=$code' \
--form 'client_id=$CLIENT_ID' \
--form 'client_secret=$CLIENT_SECRET' \
--form 'redirect_uri=https://usersandbox.butterflymx.com/oauth/callbacks/butterflymx'

Response sample in case of success:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi...TcV3Q",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "6d8cd1d...9f75",
    "created_at": 1506068201
}

Response sample in case that your $CLIENT_ID doesn’t exist, or you didn’t include your $CLIENT_SECRET in the request:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method."
}

Renewal of the access_token

After access_token expiration, an app can call the same API authentication endpoint to exchange the refresh_token for a new, valid access_token:

curl -X POST "https://accountssandbox.butterflymx.com/oauth/token" \
  -d grant_type=refresh_token \
  -d refresh_token=6d8cd1d...9f75 \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Response sample in case of success:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJ0eXAi...",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "6d8cd1d...",
    "created_at": 1506068601
}

Note: After successful refresh action, the mobile app has to store new access_token and refresh_token (both are changed)!

Last issued refresh_token doesn’t expire (it is valid indefinitely) but is still subject to invalidation for other reasons. In case that on the renewal request server responds with HTTP status 401, the app should immediately log-off user.

Response status 401, in this case, means that this refresh_token is invalid and refresh operation will not be possible. For example, if the mobile phone is stolen or compromised, the refresh_token can be invalidated on the server side.


User Password Change

Users can change their password by sending a PUT or PATCH request to the ButterflyMX Accounts API. All password change requests need to include the access_token in the Authorization header like this:

curl -X PUT 'https://accounts.butterflymx.com/api/v1/password' \
  -H 'Authorization:Bearer eyJ0eXAi...TcV3Q' \
  --data-urlencode 'account[current_password]=password' \
  --data-urlencode 'account[password]=new_password' \
  --data-urlencode 'account[password_confirmation]=new_password'

In case of the successful password change, the server will return HTTP status 204 No Content.

In case that current password was not correct, the server will respond with a ‘Wrong password’ message in the errors key, like this:

HTTP/1.1 422 Unprocessable Entity
  Content-Type: application/json

  { "errors" : "Wrong password" }

In case of any other errors while updating password, full error messages will be returned. The most common (and probably only) case where this could happen is when there is a password and password_confirmation values mismatch, like this:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{ "errors" : ["Password confirmation doesn't match Password"] }

User Roles

Authenticated user can have any of the following roles (authorizations):

  • Tenant

  • Unit Admin

  • Zone Admin

  • Building Admin

Data Models

ButterflyMX Building model is divided into zones (e.g., residential, business, etc.). Zones can’t overlap. Each zone can contain many units. A unit can be apartment, office, garage, etc.

  • building has many zones

  • zone belongs to only one building

  • zone has many units

  • unit belongs to only one zone

  • user can be a tenant in many units

  • unit can have many tenants (users)

Building Data Model


JSON API Specification

ButterflyMX API V3 implements latest JSON API Specification (v1.0) published at: http://jsonapi.org/format/

Pagination

Pagination use query parameters such as page[number] and page[size].

For example:

GET https://apisandbox.butterflymx.com/v3/door_releases?page[size]=10&?page[number]=2
Accept: application/vnd.api+json

Sorting

Note: Examples are not url-encoded for a better readability

Example:

GET https://apisandbox.butterflymx.com/v3/door_releases?sort=name,created_at
Accept: application/vnd.api+json

Multiple Sort You can sort on multiple fields like this:

GET https://apisandbox.butterflymx.com/v3/door_releases?sort=name,created_at
Accept: application/vnd.api+json

Descendant Sort Note: The sort order for each attribute is ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, -), in which case it is descending.

You can make desc sort with the character - like this:

GET https://apisandbox.butterflymx.com/v3/door_releases?sort=-created_at
Accept: application/vnd.api+json

Multiple Sort with Descendant Sort

GET https://apisandbox.butterflymx.com/v3/door_releases?sort=-created_at,name
Accept: application/vnd.api+json

The above example should return the newest door releases first. Any door release created on the same moment then be sorted by their name in ascending alphabetical order.

Filtering

Examples:

GET https://apisandbox.butterflymx.com/v3/door_releases?filter[unit]=11
Accept: application/vnd.api+json

or

GET https://apisandbox.butterflymx.com/v3/door_releases?filter[unit]=11&filter[user]=22
Accept: application/vnd.api+json

Check each resource to see which fields can be filtered.

Some endpoints can have other resources included, check the endpoint documentation to see which resources can be included for that endpoint.

Example:

GET https://apisandbox.butterflymx.com/v3/me?include=buildings,units
Accept: application/vnd.api+json

You can read more about includes here

Buildings

Buildings

Note: symbol ✓ marks permission on all entries in the authorized scope (e.g. all buildings where the Building Admin is authorized for administration* etc.)

List / Show Change Create Delete
Tenant - - - -
Unit Admin - - - -
Zone Admin - - - -
Building Admin - -

Fields that can be changed by the building admin:

  • name (String)

  • time_zone (String)

  • building_type (String)

  • display_name_strategy (String), one of the allowed values:

    • building
    • custom
    • first_name_and_last_name
    • first_name_initial_and_last_name
    • anonymous
    • first_name_and_last_name_initial
  • send_panel_status_report (Boolean)

  • panel_logo (File)

  • mobile_logo (File)

  • remove_panel_logo (Boolean)

  • remove_mobile_logo (Boolean)

  • qr_key_enabled (Boolean)

  • door_release_pin (String)

  • in_unit_phone_number (String)

  • address_1 (String)

  • address_2 (String)

  • city (String)

  • state (String)

  • zip_code (String)

  • phone_number (String)

  • country (String)

GET /v3/buildings
Requestsreturns the list of the buildings

GET  /v3/buildings

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "577696285",
      "type": "buildings",
      "attributes": {
        "name": "Bruen-Collins-13",
        "building_type": "multi_family",
        "display_name_strategy": "first_name_initial_and_last_name",
        "nfc_enabled": false,
        "send_panel_status_report": false,
        "mobile_logo_picture": {
          "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
          "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
        },
        "panel_logo_picture": {
          "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
          "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
        },
        "address_1": "4998 Emmerich Land",
        "address_2": "East Isiahtown, KS 26004",
        "city": "East Isiahtown",
        "state": "Kansas",
        "zip_code": "26004",
        "phone_number": "951-071-3650 x291",
        "country": "us",
        "qr_key_enabled": true,
        "time_zone": "Etc/UTC",
        "time_zone_offset": "+00:00",
        "delivery_pass_enabled": true,
        "door_release_pin": true,
        "open_door_button_enabled": true
      },
      "relationships": {
        "panels": {
          "data": [
            {
              "id": "708353664",
              "type": "panels"
            }
          ]
        },
        "key_lockers": {
          "data": []
        }
      }
    }
  ],
  "included": [
    {
      "id": "708353664",
      "type": "panels",
      "attributes": {
        "name": "Edric 4",
        "nfc": {
          "uuid": "b88a1c2a-1e57-4081-9b98-6854ff137fd8"
        }
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696285",
            "type": "buildings"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/buildings


GET /v3/buildings/577696288
Requestsreturns the building datareturns the associated KeyLockers

GET  /v3/buildings/577696288

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "577696288",
    "type": "buildings",
    "attributes": {
      "name": "Kovacek, Tillman and Renner-16",
      "building_type": "multi_family",
      "display_name_strategy": "last_name_and_first_name_initial",
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "address_1": "4209 Eric Streets",
      "address_2": "North Raestad, GA 60840",
      "city": "North Raestad",
      "state": "Georgia",
      "zip_code": "60840",
      "phone_number": "1-200-336-5925 x08198",
      "country": "us",
      "qr_key_enabled": true,
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00",
      "delivery_pass_enabled": true,
      "door_release_pin": true,
      "open_door_button_enabled": true
    },
    "relationships": {
      "panels": {
        "data": [
          {
            "id": "708353665",
            "type": "panels"
          }
        ]
      },
      "key_lockers": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "708353665",
      "type": "panels",
      "attributes": {
        "name": "Nayla 5",
        "nfc": {
          "uuid": "8dc3ce6b-1e01-481b-9c09-921e090ac323"
        }
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696288",
            "type": "buildings"
          }
        }
      }
    }
  ]
}

GET  /v3/buildings/577696291?include[]=key_lockers

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "577696291",
    "type": "buildings",
    "attributes": {
      "name": "Cummerata-Hayes-19",
      "building_type": "multi_family",
      "display_name_strategy": "first_name_initial_and_last_name",
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "address_1": "34540 Tanner Lane",
      "address_2": "New Lennychester, PA 69498-3142",
      "city": "New Lennychester",
      "state": "Pennsylvania",
      "zip_code": "69498-3142",
      "phone_number": "(518) 383-2557 x6771",
      "country": "us",
      "qr_key_enabled": true,
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00",
      "delivery_pass_enabled": true,
      "door_release_pin": true,
      "open_door_button_enabled": true
    },
    "relationships": {
      "panels": {
        "data": [
          {
            "id": "708353666",
            "type": "panels"
          }
        ]
      },
      "key_lockers": {
        "data": [
          {
            "id": "1",
            "type": "key_lockers"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "708353666",
      "type": "panels",
      "attributes": {
        "name": "Shadout Mapes 6",
        "nfc": {
          "uuid": "2ded2f2f-6ec5-4460-80eb-b8d9a8d10251"
        }
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696291",
            "type": "buildings"
          }
        }
      }
    },
    {
      "id": "1",
      "type": "key_lockers",
      "attributes": {
        "name": "Chani 7"
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696291",
            "type": "buildings"
          }
        },
        "compartments": {
          "data": [
            {
              "id": "1",
              "type": "key_locker_compartments"
            },
            {
              "id": "2",
              "type": "key_locker_compartments"
            },
            {
              "id": "3",
              "type": "key_locker_compartments"
            },
            {
              "id": "4",
              "type": "key_locker_compartments"
            },
            {
              "id": "5",
              "type": "key_locker_compartments"
            },
            {
              "id": "6",
              "type": "key_locker_compartments"
            },
            {
              "id": "7",
              "type": "key_locker_compartments"
            },
            {
              "id": "8",
              "type": "key_locker_compartments"
            },
            {
              "id": "9",
              "type": "key_locker_compartments"
            },
            {
              "id": "10",
              "type": "key_locker_compartments"
            },
            {
              "id": "11",
              "type": "key_locker_compartments"
            },
            {
              "id": "12",
              "type": "key_locker_compartments"
            },
            {
              "id": "13",
              "type": "key_locker_compartments"
            },
            {
              "id": "14",
              "type": "key_locker_compartments"
            },
            {
              "id": "15",
              "type": "key_locker_compartments"
            },
            {
              "id": "16",
              "type": "key_locker_compartments"
            },
            {
              "id": "17",
              "type": "key_locker_compartments"
            },
            {
              "id": "18",
              "type": "key_locker_compartments"
            },
            {
              "id": "19",
              "type": "key_locker_compartments"
            },
            {
              "id": "20",
              "type": "key_locker_compartments"
            },
            {
              "id": "21",
              "type": "key_locker_compartments"
            },
            {
              "id": "22",
              "type": "key_locker_compartments"
            },
            {
              "id": "23",
              "type": "key_locker_compartments"
            },
            {
              "id": "24",
              "type": "key_locker_compartments"
            },
            {
              "id": "25",
              "type": "key_locker_compartments"
            },
            {
              "id": "26",
              "type": "key_locker_compartments"
            },
            {
              "id": "27",
              "type": "key_locker_compartments"
            },
            {
              "id": "28",
              "type": "key_locker_compartments"
            },
            {
              "id": "29",
              "type": "key_locker_compartments"
            },
            {
              "id": "30",
              "type": "key_locker_compartments"
            },
            {
              "id": "31",
              "type": "key_locker_compartments"
            },
            {
              "id": "32",
              "type": "key_locker_compartments"
            },
            {
              "id": "33",
              "type": "key_locker_compartments"
            },
            {
              "id": "34",
              "type": "key_locker_compartments"
            }
          ]
        }
      }
    },
    {
      "id": "1",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "A1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "2",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "B1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "3",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "C1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "4",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "D1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "5",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "E1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "6",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "F1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "7",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "G1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "8",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "H1",
        "open": false,
        "full": false
      }
    },
    {
      "id": "9",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "A2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "10",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "B2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "11",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "C2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "12",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "D2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "13",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "E2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "14",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "F2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "15",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "G2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "16",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "H2",
        "open": false,
        "full": false
      }
    },
    {
      "id": "17",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "A3",
        "open": false,
        "full": false
      }
    },
    {
      "id": "18",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "B3",
        "open": false,
        "full": false
      }
    },
    {
      "id": "19",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "C3",
        "open": false,
        "full": false
      }
    },
    {
      "id": "20",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "F3",
        "open": false,
        "full": false
      }
    },
    {
      "id": "21",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "G3",
        "open": false,
        "full": false
      }
    },
    {
      "id": "22",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "H3",
        "open": false,
        "full": false
      }
    },
    {
      "id": "23",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "A4",
        "open": false,
        "full": false
      }
    },
    {
      "id": "24",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "B4",
        "open": false,
        "full": false
      }
    },
    {
      "id": "25",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "C4",
        "open": false,
        "full": false
      }
    },
    {
      "id": "26",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "F4",
        "open": false,
        "full": false
      }
    },
    {
      "id": "27",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "G4",
        "open": false,
        "full": false
      }
    },
    {
      "id": "28",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "H4",
        "open": false,
        "full": false
      }
    },
    {
      "id": "29",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "A5",
        "open": false,
        "full": false
      }
    },
    {
      "id": "30",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "B5",
        "open": false,
        "full": false
      }
    },
    {
      "id": "31",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "C5",
        "open": false,
        "full": false
      }
    },
    {
      "id": "32",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "F5",
        "open": false,
        "full": false
      }
    },
    {
      "id": "33",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "G5",
        "open": false,
        "full": false
      }
    },
    {
      "id": "34",
      "type": "key_locker_compartments",
      "attributes": {
        "cell": "H5",
        "open": false,
        "full": false
      }
    }
  ]
}

Show
GET/v3/buildings/{id}

URI Parameters
HideShow
id
number (required) Example: 577696288

PATCH /v3/buildings/577696295
Requestsupdates the building dataupdates the building addressdoes not update the building addressremoves the panel_logo

PATCH  /v3/buildings/577696295

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "buildings",
    "id": "577696295",
    "attributes": {
      "name": "My Building",
      "building_type": "commercial_office",
      "display_name_strategy": "first_name_and_last_name",
      "door_release_pin": false,
      "qr_key_enabled": false,
      "send_panel_status_report": true,
      "time_zone": "Eastern Time (US & Canada)"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "577696295",
    "type": "buildings",
    "attributes": {
      "name": "My Building",
      "building_type": "commercial_office",
      "display_name_strategy": "first_name_and_last_name",
      "nfc_enabled": false,
      "send_panel_status_report": true,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "address_1": "99237 Bradtke Canyon",
      "address_2": "Lonborough, SC 14873-3549",
      "city": "Lonborough",
      "state": "South Carolina",
      "zip_code": "14873-3549",
      "phone_number": "1-193-674-8250 x82170",
      "country": "us",
      "qr_key_enabled": false,
      "time_zone": "Eastern Time (US & Canada)",
      "time_zone_offset": "-04:00",
      "delivery_pass_enabled": true,
      "door_release_pin": false,
      "open_door_button_enabled": true
    },
    "relationships": {
      "panels": {
        "data": [
          {
            "id": "708353667",
            "type": "panels"
          }
        ]
      },
      "key_lockers": {
        "data": []
      }
    }
  }
}

PATCH  /v3/buildings/577696298

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "buildings",
    "id": "577696298",
    "attributes": {
      "address_1": "New Building Address"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "577696298",
    "type": "buildings",
    "attributes": {
      "name": "Howe-Cremin-26",
      "building_type": "multi_family",
      "display_name_strategy": "last_name_and_first_name",
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "address_1": "New Building Address",
      "address_2": "North Sherlene, NY 05889-5889",
      "city": "North Sherlene",
      "state": "New York",
      "zip_code": "05889-5889",
      "phone_number": "505-024-6212",
      "country": "us",
      "qr_key_enabled": true,
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00",
      "delivery_pass_enabled": true,
      "door_release_pin": true,
      "open_door_button_enabled": true
    },
    "relationships": {
      "panels": {
        "data": [
          {
            "id": "708353668",
            "type": "panels"
          }
        ]
      },
      "key_lockers": {
        "data": []
      }
    }
  }
}

PATCH  /v3/buildings/577696301

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "buildings",
    "id": "577696301",
    "attributes": {
      "address_1": ""
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/address.address_1"
      },
      "detail": "can't be blank"
    }
  ]
}

PATCH  /v3/buildings/577696304

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "remove_panel_logo": true
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "577696304",
    "type": "buildings",
    "attributes": {
      "name": "Pollich, Boyle and Quigley-32",
      "building_type": "multi_family",
      "display_name_strategy": "anonymous",
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
        "medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
      },
      "address_1": "722 Leif Lake",
      "address_2": "Tienton, CT 68210",
      "city": "Tienton",
      "state": "Connecticut",
      "zip_code": "68210",
      "phone_number": "1-611-992-3131 x5246",
      "country": "us",
      "qr_key_enabled": true,
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00",
      "delivery_pass_enabled": true,
      "door_release_pin": true,
      "open_door_button_enabled": true
    },
    "relationships": {
      "panels": {
        "data": [
          {
            "id": "708353670",
            "type": "panels"
          }
        ]
      },
      "key_lockers": {
        "data": []
      }
    }
  }
}

Update
PATCH/v3/buildings/{id}

URI Parameters
HideShow
id
number (required) Example: 577696295

Integrations

Integrations

Allowed integrators:

  • webhook

Allowed config attributes for integrators:

  • webhook
    • url (String)
    • method (String get or post)

Allowed binding resource types:

  • call

  • door_release

GET /v3/buildings/1337/integrations
Requestsreturns a list of all the building's integrations

GET  /v3/buildings/1337/integrations

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "79c9dc15-1bef-4ecc-956e-824be46901ce",
      "type": "integrations",
      "attributes": {
        "integrator": "webhook",
        "config": {
          "method": "get",
          "url": "http://localhost:999"
        },
        "bindings": [
          {
            "resource_type": "door_release",
            "resource_id": "7",
            "actions": [
              "update",
              "destroy"
            ]
          }
        ]
      },
      "relationships": {
        "bindings": {
          "data": [
            {
              "resource_type": "door_release",
              "resource_id": "7",
              "actions": [
                "update",
                "destroy"
              ]
            }
          ]
        },
        "building": {
          "data": {
            "id": "1337",
            "type": "buildings"
          }
        },
        "tenant": {
          "data": null
        }
      },
      "links": {
        "self": "http://api.butterflymx.com/v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce"
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/buildings/1337/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "first": "http://api.butterflymx.com/v3/buildings/1337/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/buildings/1337/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

List
GET/v3/buildings/{building_id}/integrations

URI Parameters
HideShow
building_id
number (required) Example: 1337

GET /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Requestsreturns a single integration for the building

GET  /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "79c9dc15-1bef-4ecc-956e-824be46901ce",
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "config": {
        "method": "get",
        "url": "http://localhost:999"
      },
      "bindings": [
        {
          "resource_type": "door_release",
          "resource_id": "7",
          "actions": [
            "update",
            "destroy"
          ]
        }
      ]
    },
    "relationships": {
      "bindings": {
        "data": [
          {
            "resource_type": "door_release",
            "resource_id": "7",
            "actions": [
              "update",
              "destroy"
            ]
          }
        ]
      },
      "building": {
        "data": {
          "id": "1337",
          "type": "buildings"
        }
      },
      "tenant": {
        "data": null
      }
    },
    "links": {
      "self": "http://api.butterflymx.com/v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce"
    }
  }
}

Show
GET/v3/buildings/{building_id}/integrations/{id}

URI Parameters
HideShow
building_id
number (required) Example: 1337
id
string (required) Example: 79c9dc15-1bef-4ecc-956e-824be46901ce

POST /v3/buildings/1337/integrations
Requestscreates an integration for the building

POST  /v3/buildings/1337/integrations

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Body
{
  "data": {
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "configuration": {
        "url": "http://localhost:666",
        "method": "post"
      },
      "bindings": [
        {
          "actions": [
            "create"
          ],
          "resource_type": "call",
          "resource_id": null
        }
      ]
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "79c9dc15-1bef-4ecc-956e-824be46901ce",
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "config": {
        "method": "post",
        "url": "http://localhost:666"
      },
      "bindings": [
        {
          "resource_type": "call",
          "resource_id": null,
          "actions": [
            "create"
          ]
        }
      ]
    },
    "relationships": {
      "bindings": {
        "data": [
          {
            "resource_type": "call",
            "resource_id": null,
            "actions": [
              "create"
            ]
          }
        ]
      },
      "building": {
        "data": {
          "id": "1337",
          "type": "buildings"
        }
      },
      "tenant": {
        "data": null
      }
    },
    "links": {
      "self": "http://api.butterflymx.com/v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce"
    }
  }
}

Create
POST/v3/buildings/{building_id}/integrations

URI Parameters
HideShow
building_id
number (required) Example: 1337

PATCH /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Requestsupdates a building's integration

PATCH  /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Body
{
  "data": {
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "configuration": {
        "url": "http://localhost:999",
        "method": "get"
      },
      "bindings": [
        {
          "actions": [
            "update",
            "destroy"
          ],
          "resource_type": "door_release",
          "resource_id": "7"
        }
      ]
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "79c9dc15-1bef-4ecc-956e-824be46901ce",
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "config": {
        "method": "get",
        "url": "http://localhost:999"
      },
      "bindings": [
        {
          "resource_type": "door_release",
          "resource_id": "7",
          "actions": [
            "update",
            "destroy"
          ]
        }
      ]
    },
    "relationships": {
      "bindings": {
        "data": [
          {
            "resource_type": "door_release",
            "resource_id": "7",
            "actions": [
              "update",
              "destroy"
            ]
          }
        ]
      },
      "building": {
        "data": {
          "id": "1337",
          "type": "buildings"
        }
      },
      "tenant": {
        "data": null
      }
    },
    "links": {
      "self": "http://api.butterflymx.com/v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce"
    }
  }
}

Update
PATCH/v3/buildings/{building_id}/integrations/{id}

URI Parameters
HideShow
building_id
number (required) Example: 1337
id
string (required) Example: 79c9dc15-1bef-4ecc-956e-824be46901ce

DELETE /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Requestsdeletes a building's integration

DELETE  /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Responses204
This response has no content.

Delete
DELETE/v3/buildings/{building_id}/integrations/{id}

URI Parameters
HideShow
building_id
number (required) Example: 1337
id
string (required) Example: 79c9dc15-1bef-4ecc-956e-824be46901ce

Current User

Status

Possible status values:

When call is VOIP:

  • initializing

  • canceled

  • timeout_online_signal

  • voip_connected

When call is mobile:

  • initializing

  • canceled

  • timeout_online_signal

  • connecting_sip

  • voip_rollover

  • rejected

GET /v3/me/calls/f4e25234-586f-4db6-a483-c56d48252946/status
Requestsreturns status of the callreturns not found

GET  /v3/me/calls/f4e25234-586f-4db6-a483-c56d48252946/status

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "2",
    "type": "call_statuses",
    "attributes": {
      "status": "initializing",
      "multiple_devices": false,
      "created_at": "2023-03-22T11:49:02Z"
    },
    "relationships": {
      "call": {
        "data": {
          "id": "1",
          "type": "calls"
        }
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "calls",
      "attributes": {
        "guid": "f4e25234-586f-4db6-a483-c56d48252946",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "status": "initializing",
        "display_status": "Initializing",
        "panel_id": 708353671,
        "panel_name": "Scytale 12",
        "panel_sip": "panel_708353671",
        "provider": "internal"
      }
    }
  ]
}

GET  /v3/me/calls/DOES_NOT_EXIST/status

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses404
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "title": "Record not found",
      "detail": "Requested record could not be found"
    }
  ]
}

Call Status
GET/v3/me/calls/{call_guid}/status

URI Parameters
HideShow
call_guid
string (required) Example: f4e25234-586f-4db6-a483-c56d48252946

Calls

Sortable fields:

  • created_at

  • logged_at

  • notification_type

  • call_type

Filterable fields:

  • unit -> integer

  • notification_type -> enum(string)

  • call_type -> enum(string)

  • guid -> string

Enumerations:

  • call_type:

    • voip
    • mobile
  • notification_type:

    • visitor
    • delivery
GET /v3/me/calls
Requestsreturns a list of calls

GET  /v3/me/calls

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "5",
      "type": "calls",
      "attributes": {
        "guid": "8f48eeb0-7619-4247-9739-4ecbdbe9cca1",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "status": "initializing",
        "display_status": "Initializing",
        "initial": true,
        "provider": "internal"
      },
      "relationships": {
        "rollover_calls": {
          "data": []
        },
        "panel": {
          "data": {
            "id": "708353673",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "4",
      "type": "calls",
      "attributes": {
        "guid": "31830e29-b8c7-46e3-83ee-2b93f583deb8",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "status": "initializing",
        "display_status": "Initializing",
        "initial": true,
        "provider": "internal"
      },
      "relationships": {
        "rollover_calls": {
          "data": []
        },
        "panel": {
          "data": {
            "id": "708353673",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "calls",
      "attributes": {
        "guid": "75ddb8d6-03cf-4909-a3c8-ff64a98f3b32",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "status": "initializing",
        "display_status": "Initializing",
        "initial": true,
        "provider": "internal"
      },
      "relationships": {
        "rollover_calls": {
          "data": []
        },
        "panel": {
          "data": {
            "id": "708353673",
            "type": "panels"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

Calls
GET/v3/me/calls


Door Releases

Sortable fields:

  • created_at

  • logged_at

  • notification_type

  • call_type

Filterable fields:

  • unit -> integer

  • release_method -> enum

  • door_release_type -> enum

  • name -> string

  • call_guid -> string

Enumerations:

  • release_method:

    • mobile
    • panel
    • qr_key
    • nfc
    • voip
    • bluetooth
    • front_door_view
    • rfid
  • door_release_type:

    • visitor
    • delivery
GET /v3/me/door_releases
Requestsreturns a list of door releases

GET  /v3/me/door_releases

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "6",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "call_guid": "c08a1434-f8d4-4877-97a1-b121e5308684",
        "delivery_guid": "3ae99e37-8d50-4010-bec7-0625189edca7",
        "name": "Jong Block",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb/small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/small_picture.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107278",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166931",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353674",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353677",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "5",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "call_guid": "9dfaee4c-da80-41e0-b635-abcb19f1e1cb",
        "delivery_guid": "3969b699-321b-469f-9564-292cf0b59dc6",
        "name": "Miss Ashton Pacocha",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb/small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/small_picture.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107278",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166931",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353674",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353676",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "4",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "call_guid": "767748e1-165f-4c8c-bc95-95b261b77c1b",
        "delivery_guid": "3995bffc-4080-4e03-bf6e-feda8a2eaf72",
        "name": "Nohemi Dickens",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb/small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/small_picture.jpg",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107278",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166931",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353674",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353675",
            "type": "panels"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

Door Releases
GET/v3/me/door_releases


Messages

Sortable fields:

  • message_type

  • created_at

Filterable fields:

  • message_type -> enum

Enumerations:

  • message_type:
    • text
    • voice
GET /v3/me/messages
Requestsreturns a list of messages

GET  /v3/me/messages

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "3",
      "type": "messages",
      "attributes": {
        "message": null,
        "voice": {
          "url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/voice_message.mp3"
        },
        "message_type": "voice"
      }
    },
    {
      "id": "2",
      "type": "messages",
      "attributes": {
        "message": null,
        "voice": {
          "url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/voice_message.mp3"
        },
        "message_type": "voice"
      }
    },
    {
      "id": "1",
      "type": "messages",
      "attributes": {
        "message": null,
        "voice": {
          "url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/voice_message.mp3"
        },
        "message_type": "voice"
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/me/messages?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/me/messages?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/me/messages?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

Messages
GET/v3/me/messages


Open Door

POST /v3/me/open_door
Requestssends a request to open the doorsends a request to open the door connected to a keypadreturns bad request

POST  /v3/me/open_door

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {},
    "type": "open_door",
    "relationships": {
      "panel": {
        "data": {
          "type": "panel",
          "id": 708353678
        }
      },
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107288
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "1",
    "type": "door_release_requests",
    "attributes": {
      "guid": "c9b77456-0649-4abf-80f7-8a02ab9519c5",
      "created_at": "2023-03-22T11:49:07Z"
    }
  }
}

POST  /v3/me/open_door

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {},
    "type": "open_door",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107290
        }
      },
      "device": {
        "data": {
          "type": "keypads",
          "id": 106694917
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "2",
    "type": "door_release_requests",
    "attributes": {
      "guid": "874d3de9-0f1a-4e0c-8b45-4e1017934f2b",
      "created_at": "2023-03-22T11:49:08Z"
    }
  }
}

POST  /v3/me/open_door

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {},
    "type": "open_doors",
    "relationships": {
      "panels": {
        "data": {
          "type": "panels",
          "id": "DOES_NOT_EXIST"
        }
      },
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107293
        }
      }
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/building_open_door_button"
      },
      "detail": "Building open door feature has not been enabled"
    },
    {
      "source": {
        "pointer": "/data/attributes/access_point"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/device"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/panel"
      },
      "detail": "can't be blank"
    }
  ]
}

Open Door
POST/v3/me/open_door


Tokens

POST /v3/me/calls/twiliotest/token
Requestsreturns successgenerates_tokenreturns error

POST  /v3/me/calls/twiliotest/token

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "device_uuid": "test-123-test"
    },
    "type": "token",
    "relationships": null
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "tokens": {
    "twilio": "token-12345679-token"
  }
}

POST  /v3/me/calls/twiliotest/token

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "device_uuid": "test-123-test"
    },
    "type": "token",
    "relationships": null
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "tokens": {
    "twilio": "token-12345679-token"
  }
}

POST  /v3/me/calls/voiptest/token

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "device_uuid": "test-123-test"
    },
    "type": "token",
    "relationships": null
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "error": "Bad Request",
  "error_description": "Token was not generated"
}

Create
POST/v3/me/calls/{call_guid}/token

URI Parameters
HideShow
call_guid
string (required) Example: twiliotest

User

Resources that can be included:

  • tenants

Nested resources that can be included:

  • tenants.building

  • tenants.unit

  • tenants.panels

GET /v3/me
Requestsshows current user informationshows current user information with included resources

GET  /v3/me

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166939",
    "type": "users",
    "attributes": {
      "name": "Isiah Fisher",
      "first_name": "Isiah",
      "last_name": "Fisher",
      "contact_preference": "phone_call",
      "thumb_url": null,
      "medium_url": null,
      "sip_username": "40",
      "email": "derrick_schmidt@jerde.info",
      "sms_phone_number": null,
      "phone_number": null
    },
    "relationships": {
      "tenants": {
        "data": [
          {
            "id": "636166938",
            "type": "tenants"
          }
        ]
      }
    }
  }
}

GET  /v3/me?include=tenants.building,tenants.panels,tenants.unit

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166940",
    "type": "users",
    "attributes": {
      "name": "Neta Hessel",
      "first_name": "Neta",
      "last_name": "Hessel",
      "contact_preference": "phone_call",
      "thumb_url": null,
      "medium_url": null,
      "sip_username": "41",
      "email": "jarrod.labadie@bednar.info",
      "sms_phone_number": null,
      "phone_number": null
    },
    "relationships": {
      "tenants": {
        "data": [
          {
            "id": "636166939",
            "type": "tenants"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "636166939",
      "type": "tenants",
      "attributes": {
        "unit_id": 843107312,
        "inactive_at": null
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696343",
            "type": "buildings"
          }
        },
        "unit": {
          "data": {
            "id": "843107312",
            "type": "units"
          }
        },
        "panels": {
          "data": [
            {
              "id": "708353688",
              "type": "panels"
            }
          ]
        },
        "devices": {
          "data": []
        }
      }
    },
    {
      "id": "577696343",
      "type": "buildings",
      "attributes": {
        "name": "Hudson-Pacocha-71",
        "building_type": "multi_family",
        "mobile_logo_picture": {
          "thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
          "medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
        },
        "panel_logo_picture": {
          "thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
          "medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
        },
        "address_1": "603 Mills Parkways",
        "address_2": "South Deaneside, LA 18623",
        "city": "South Deaneside",
        "state": "Louisiana",
        "zip_code": "18623",
        "phone_number": "(936) 868-7856 x776",
        "country": "us",
        "time_zone": "Etc/UTC",
        "open_door_button_enabled": true
      }
    },
    {
      "id": "843107312",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "00",
        "floor_number": 0
      }
    },
    {
      "id": "708353688",
      "type": "panels",
      "attributes": {
        "name": "Gurney Halleck 30",
        "nfc": {
          "uuid": "fd177e15-3a02-47f9-9e8d-81b3da7f0fcc"
        }
      }
    }
  ]
}

Show
GET/v3/me


PUT /v3/me
Requestsupdates the current userreturns bad request

PUT  /v3/me

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "tenants",
    "id": "636166941",
    "attributes": {
      "last_name": "Baker"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166941",
    "type": "users",
    "attributes": {
      "name": "Marianne Baker",
      "first_name": "Marianne",
      "last_name": "Baker",
      "contact_preference": "phone_call",
      "thumb_url": null,
      "medium_url": null,
      "sip_username": "42",
      "email": "billie@leannon.info",
      "sms_phone_number": null,
      "phone_number": null
    },
    "relationships": {
      "tenants": {
        "data": [
          {
            "id": "636166940",
            "type": "tenants"
          }
        ]
      }
    }
  }
}

PUT  /v3/me

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "tenants",
    "id": "636166942",
    "attributes": {
      "last_name": ""
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "error": "Bad Request",
  "error_description": "Last name can't be blank"
}

Update
PUT/v3/me


Devices

Devices

Fetch a list of devices that the authorized user has access to.

  • If a user is a tenant, only door devices that are installed, enabled and where he has access to are included.

  • If a user is an admin, a list of all devices from all buildings the user has access will be included.

Building id is included in relationships, and detailed building info can be requested with ?include=building parameter

GET /v3/devices
Requestsshows a list of devices with included resources

GET  /v3/devices?include=building

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": []
}

List
GET/v3/devices


Door Releases

Door Releases

Note: symbol ✓ marks permission on all entries in the authorized scope (e.g. all buildings where the Building Admin is authorized for administration* etc.)

List / Show Change Create Delete
Tenant - - -
Unit Admin - - -
Zone Admin - - -
Building Admin - - -

Request Samples with Filter:

GET /v3/door_releases?unit_id=11

GET /v3/door_releases?user_id=22

GET /v3/door_releases?unit_id=11&user_id=22

GET /v3/door_releases?door_release_type=delivery


Request Samples with Sort:

GET /v3/door_releases?sort=created

GET /v3/door_releases?sort=-created,name

The sort order for each attribute is ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“), in which case it is descending.


Allowed values for:

  • release_method:

    • mobile
    • panel
    • qr_key
    • nfc
    • voip
  • door_release_type:

    • visitor
    • delivery
  • panel_user_type:

    • default
    • doorman
GET /v3/door_releases
Requestsreturns recent door releases of the tenant's unit

GET  /v3/door_releases

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "32",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "doorman",
        "call_guid": "53f8c18d-4113-4fbb-8ae7-1f2585528747",
        "delivery_guid": "77eca416-616b-4a60-822e-db0cf6655adf",
        "name": "Serena Heaney",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "31",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "doorman",
        "call_guid": "d7e87174-cc3e-4280-bb33-965f3709073f",
        "delivery_guid": "46556694-be18-47a2-aadb-1e08e9782a7e",
        "name": "Cody West",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "30",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "b8886aa3-7a1e-4f51-b76a-d69596fbe0aa",
        "delivery_guid": "fb0d1908-e262-4297-8dc7-67310565949a",
        "name": "Wilfredo Tromp",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "29",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "e5784825-8509-4268-a753-ee09a7427c34",
        "delivery_guid": "eed65b48-7980-44a4-bf45-30aa98745ecd",
        "name": "Dr. Lane Kunde",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "28",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "delivery",
        "panel_user_type": "default",
        "call_guid": "5ec9faa2-3942-4677-809c-17685a1c00fb",
        "delivery_guid": "91c0e654-b398-4d84-bf0a-731e819fbdd5",
        "name": "Marylee Reichel",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "27",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "delivery",
        "panel_user_type": "default",
        "call_guid": "4857a6a8-3a0b-4822-95b3-872f4df12123",
        "delivery_guid": "c174dbed-9530-4423-930e-3d664f08bd36",
        "name": "Trevor Mitchell PhD",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "26",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "ff22c206-5183-4c8c-a5be-e919e91dd608",
        "delivery_guid": "53a265aa-7277-4880-9bc7-c91c3d4f50d4",
        "name": "Dr. Chana Pfeffer",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "25",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "7ae6efa8-7b37-4a58-ac0b-313ebc264886",
        "delivery_guid": "f8ad5678-4d06-4cba-810a-1a7914e06d8d",
        "name": "Trenton Legros",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "24",
      "type": "door_releases",
      "attributes": {
        "release_method": "qr_key",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "58c90aff-8032-4d9f-9a44-a5a8b8ffd7b5",
        "delivery_guid": "f13f097f-7924-43f8-aa3f-6902fdcf00bc",
        "name": "Elida Strosin",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "23",
      "type": "door_releases",
      "attributes": {
        "release_method": "qr_key",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "b78e5e93-1c01-4247-96ed-f83061549e06",
        "delivery_guid": "8890db75-8452-427a-a6d4-283e0d8e808d",
        "name": "Blake Hackett",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "22",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "7b744227-42af-4d19-844a-539b58fbe690",
        "delivery_guid": "3eb625eb-e587-4e3e-b229-a2ae4301b86d",
        "name": "Emogene Blick IV",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "21",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "3e4cb91c-a408-4d21-ae2e-fecefef143b2",
        "delivery_guid": "68ead11b-1511-4c8f-832d-61edb9d99df0",
        "name": "Brent D'Amore",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        },
        "device": {
          "data": {
            "id": "708353702",
            "type": "panels"
          }
        }
      }
    },
    {
      "id": "20",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "3cdfb1ed-6570-4bbf-8d27-d9aa8cac68a4",
        "delivery_guid": "8cc8a4ff-ecec-486f-be28-4ceb97df5db0",
        "name": "Mr. Rodrick Spinka",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": null
        },
        "device": {
          "data": {
            "id": "106694919",
            "type": "keypads"
          }
        }
      }
    },
    {
      "id": "19",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "c241d258-4e27-4186-b955-f2b3e909cc77",
        "delivery_guid": "81e15440-02f5-4c08-a4ed-e9a635a65e33",
        "name": "Hilma Greenfelder",
        "created_at": "2023-03-22T11:47:12Z",
        "logged_at": "2023-03-22T11:47:12Z",
        "thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
        "medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107366",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636166955",
            "type": "users"
          }
        },
        "panel": {
          "data": null
        },
        "device": {
          "data": {
            "id": "106694919",
            "type": "keypads"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/door_releases


Keychains

Keychains

How to Create a Keychain with Virtual Keys

We use two concepts when creating a virtual key:

  • Keychain

  • Virtual Key

Keychain

Keychain contains information about the kind of key, what its duration is etc. A keychain can have many virtual keys, so a single keychain can be used to create virtual keys for multiple people. Information from the keychain is used by the panels to verify if the virtual key is still valid. Keychains must be associated with a unit.

Parameters that are always required for all keychains:

name -> string

tenant -> relationship or unit -> relationship

If you wish to have the keychain associated with tenant send the tenant relationship, otherwise send the unit as relationship. The second case is useful if you have large tenant turnover in a unit (e.g short term tourist renals). If you wish to allow your tenants to create and share keys by themselves, tenant association is required.

Custom keychains

Custom keychains have a start and end date when they are valid e.g. a virtual key for a custom keychain will be valid from 01/01/2019 11:50 to 03/03/2019 13:45. Always use the iso8601 format when sending datetime data.

Endpoint examples

Parameters that are required for custom keychains:

starts_at -> datetime (iso8601)

ends_at -> datetime (iso8601)

Recurring keychains

Recurring keychains are valid only on certain weekdays and inside certain time periods e.g. a virtual key for a recurring keychain will be valid only on wednesdays and thursdays between 12:30 and 16:30. Recurring keychains also use the start and end dates to determine when they will completely expired, so if a recurring keychain has an end date on 03/03/2019 the above virtual key will no longer be valid on wendesdays and thursdays. Always use the iso8601 format when sending datetime data, for time data use the hh:mm format (06:21, 11:53, 22:51).

Endpoint examples

Parameters that are required for custom keychains:

weekdays -> array(enum)

start_date -> date (iso8601)

end_date -> date (iso8601)

time_to -> time (hh:mm)

time_from -> time (hh:mm)

Enumerations:

  • weekdays:
    • mon
    • tue
    • wed
    • thu
    • fri
    • sat
    • sun

One time keychains

Virtual keys that belong to one time keychains can be used only once inside a predefined period of tim, which is determined by starts_at and ends_at fields. After they are used or if they’re not inside a predefined period of time they are no longer valid e.g. if a keychain’s validity period is from 01/01/2019 11:50 to 03/03/2019 13:45, it will not be valid if it’s used inside that period or when the time of 03/03/2019 13:45 has passed.

To determine if a particular virtual key for the one time keychain, or delivery pass has been used, check the used_at, one_time_key_used_at field on the virtual key.

Parameters that are required for one time keychains:

starts_at -> datetime (iso8601)

ends_at -> datetime (iso8601)

Virtual Key

Virtual key is used by a single person to open a door, it contains either an e-mail or an sms number of the person who will use it, a url to the qr code of the key which can be scanned to gain access to the building and a name which is used when the key is sent to the user.

Virtual keys are created from an array of recipients (e-mail or a mobile phone number) that is added to keychain parameters or on a separate endpoint.

Parameters that are required to create virtual keys:

recipients -> array(string)

Filterable fields:

  • unit -> integer

  • tenant -> integer

POST /v3/keychains/custom
Requestscreates a new keychain with associated qr keyscreates a keychain, virtual keys for one KeyLocker Compartmentcreates a keychain and virtual keys for a random free KeyLocker Compartmentcreates a keychain and virtual keys for the KeyLocker Compartmentcreates a keychain and virtual keys for the KeyLocker Compartmentcreates a keycahin and virtual keys for the KeyLocker Compartmentcreates a new keychain with associated qr keysreturns bad request

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:24+00:00",
      "ends_at": "2023-03-24T11:49:19+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ]
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107336
        }
      },
      "devices": {
        "data": [
          {
            "type": "keypads",
            "id": 106694918
          }
        ]
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "15",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:24Z",
      "ends_at": "2023-03-24T11:49:19Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "7",
            "type": "virtual_keys"
          },
          {
            "id": "8",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "7",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-7cx557.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "181085",
        "instructions_url": "http://user.butterflymx.test/public/dooley-and-sons-95/virtual_keys/7/4498189154c4312c3550102c4124e800",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "8",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1f8yuoc.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "794804",
        "instructions_url": "http://user.butterflymx.test/public/dooley-and-sons-95/virtual_keys/8/507c8c7c6b6e8ae910260e4cc6ef3661",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:26+00:00",
      "ends_at": "2023-03-24T11:49:21+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "key_locker": {
        "id": 2,
        "compartment": "H3"
      }
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107338
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "16",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:26Z",
      "ends_at": "2023-03-24T11:49:21Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "9",
            "type": "virtual_keys"
          },
          {
            "id": "10",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "9",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1mcp4ll.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "251167",
        "instructions_url": "http://user.butterflymx.test/public/hane-strosin-and-emard-97/virtual_keys/9/a11a5cea35586818e6e6a73a4b65b0e3",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "10",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-w4lgca.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "759572",
        "instructions_url": "http://user.butterflymx.test/public/hane-strosin-and-emard-97/virtual_keys/10/e67e52ee2e8706767baae3becf1b96de",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:28+00:00",
      "ends_at": "2023-03-24T11:49:23+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "key_locker": {
        "id": 3,
        "compartment": "any_when_used"
      }
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107341
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "17",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:28Z",
      "ends_at": "2023-03-24T11:49:23Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "11",
            "type": "virtual_keys"
          },
          {
            "id": "12",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "11",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-q3d4rl.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "833645",
        "instructions_url": "http://user.butterflymx.test/public/gleason-morissette-100/virtual_keys/11/b74c2402925cdcd32cb0c5075c3f5b4e",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "12",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-9oi5bn.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "343529",
        "instructions_url": "http://user.butterflymx.test/public/gleason-morissette-100/virtual_keys/12/213b12021e226150282793269cc49777",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:30+00:00",
      "ends_at": "2023-03-24T11:49:25+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "key_locker": {
        "id": 4,
        "compartment_id": 123
      }
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107344
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "18",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:30Z",
      "ends_at": "2023-03-24T11:49:25Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "13",
            "type": "virtual_keys"
          },
          {
            "id": "14",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "13",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-14blgw6.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "603021",
        "instructions_url": "http://user.butterflymx.test/public/wisozk-group-103/virtual_keys/13/72bc540e413a31138441c2f3003622e4",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "14",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-ac785f.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "590760",
        "instructions_url": "http://user.butterflymx.test/public/wisozk-group-103/virtual_keys/14/b59a68980542601f6a6a79ecd17882b6",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:32+00:00",
      "ends_at": "2023-03-24T11:49:27+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "key_locker": {
        "id": 5,
        "compartment_id": 164,
        "item_return_policy": "return"
      }
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107347
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "19",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:32Z",
      "ends_at": "2023-03-24T11:49:27Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "15",
            "type": "virtual_keys"
          },
          {
            "id": "16",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "15",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-137h6x2.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "395137",
        "instructions_url": "http://user.butterflymx.test/public/carroll-inc-106/virtual_keys/15/0c91c8c7eac2a7527b777a30e3260ad3",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "16",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1o5ynv7.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "161698",
        "instructions_url": "http://user.butterflymx.test/public/carroll-inc-106/virtual_keys/16/e1a73f77e968c61c0f8a82e42c2ba6cb",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:34+00:00",
      "ends_at": "2023-03-24T11:49:29+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "key_locker": {
        "id": 6,
        "compartment_id": 191
      },
      "item_return_policy": "return"
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107350
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "20",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:34Z",
      "ends_at": "2023-03-24T11:49:29Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "17",
            "type": "virtual_keys"
          },
          {
            "id": "18",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "17",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-2q8ir4.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "552663",
        "instructions_url": "http://user.butterflymx.test/public/okuneva-o-kon-109/virtual_keys/17/6ff72116f2740af9a6dc1b1e261f8bc4",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "18",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-enehb3.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "260285",
        "instructions_url": "http://user.butterflymx.test/public/okuneva-o-kon-109/virtual_keys/18/b67a461c981bd4dd94f385995b4792a9",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "starts_at": "2023-03-22T11:49:35+00:00",
      "ends_at": "2023-03-24T11:49:30+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ]
    },
    "relationships": {
      "tenant": {
        "data": {
          "type": "tenant",
          "id": 636166948
        }
      },
      "devices": {
        "data": []
      },
      "access_points": {
        "data": [
          {
            "type": "access_point",
            "id": 842395210
          }
        ]
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "21",
    "type": "keychains",
    "attributes": {
      "name": "Custom Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:35Z",
      "ends_at": "2023-03-24T11:49:30Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "19",
            "type": "virtual_keys"
          },
          {
            "id": "20",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": [
          {
            "id": "708353700",
            "type": "panels"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "19",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-15jytkw.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "796587",
        "instructions_url": "http://user.butterflymx.test/public/stanton-ondricka-112/virtual_keys/19/4745ca3c6520f1274f82253a0d9dde3b",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "20",
      "type": "virtual_keys",
      "attributes": {
        "name": "Custom Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-w6kv4j.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "172435",
        "instructions_url": "http://user.butterflymx.test/public/stanton-ondricka-112/virtual_keys/20/e1406a6d4d4ed24e5eda19a573bb573f",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "708353700",
      "type": "panels",
      "attributes": {
        "name": "Paul \"Muad'Dib\" \"Usul\" Atreides 49",
        "nfc": {
          "uuid": "2798e80a-fda9-4e42-a178-ddb4622661ec"
        }
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696384",
            "type": "buildings"
          }
        }
      }
    }
  ]
}

POST  /v3/keychains/custom

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Custom Key",
      "starts_at": "",
      "ends_at": "2023-03-24T11:49:31+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ]
    },
    "type": "keychains",
    "relationships": {
      "tenant": {
        "data": {
          "type": "tenant",
          "id": 636166949
        }
      }
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/starts_at"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/starts_at"
      },
      "detail": "is not a valid datetime"
    },
    {
      "source": {
        "pointer": "/data/attributes/ends_at"
      },
      "detail": "Error occurred validating ends_at for :after restriction:\ncomparison of ActiveSupport::TimeWithZone with nil failed"
    }
  ]
}

Create Custom Keychain
POST/v3/keychains/custom


GET /v3/keychains
Requestsshows a list of keychainsshows a list of keychains with included resources

GET  /v3/keychains

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "27",
      "type": "keychains",
      "attributes": {
        "name": "Technology Manager 19",
        "weekdays": [],
        "starts_at": "2023-03-22T11:49:40Z",
        "ends_at": "2023-03-22T12:49:40Z",
        "time_from": "11:49",
        "time_to": "12:49",
        "kind": "custom",
        "start_date": "2023-03-22",
        "end_date": "2023-03-22",
        "allow_unit_access": false
      },
      "relationships": {
        "virtual_keys": {
          "data": []
        },
        "devices": {
          "data": []
        }
      }
    },
    {
      "id": "26",
      "type": "keychains",
      "attributes": {
        "name": "Sales Designer 18",
        "weekdays": [],
        "starts_at": "2023-03-22T11:49:40Z",
        "ends_at": "2023-03-22T12:49:40Z",
        "time_from": "11:49",
        "time_to": "12:49",
        "kind": "custom",
        "start_date": "2023-03-22",
        "end_date": "2023-03-22",
        "allow_unit_access": false
      },
      "relationships": {
        "virtual_keys": {
          "data": []
        },
        "devices": {
          "data": []
        }
      }
    },
    {
      "id": "25",
      "type": "keychains",
      "attributes": {
        "name": "Future Officer 17",
        "weekdays": [],
        "starts_at": "2023-03-22T11:49:40Z",
        "ends_at": "2023-03-22T12:49:40Z",
        "time_from": "11:49",
        "time_to": "12:49",
        "kind": "custom",
        "start_date": "2023-03-22",
        "end_date": "2023-03-22",
        "allow_unit_access": false
      },
      "relationships": {
        "virtual_keys": {
          "data": [
            {
              "id": "23",
              "type": "virtual_keys"
            }
          ]
        },
        "devices": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/keychains?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/keychains?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/keychains?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

GET  /v3/keychains?include=virtual_keys,devices

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "30",
      "type": "keychains",
      "attributes": {
        "name": "Retail Assistant 22",
        "weekdays": [],
        "starts_at": "2023-03-22T11:49:40Z",
        "ends_at": "2023-03-22T12:49:40Z",
        "time_from": "11:49",
        "time_to": "12:49",
        "kind": "custom",
        "start_date": "2023-03-22",
        "end_date": "2023-03-22",
        "allow_unit_access": false
      },
      "relationships": {
        "virtual_keys": {
          "data": []
        },
        "devices": {
          "data": []
        }
      }
    },
    {
      "id": "29",
      "type": "keychains",
      "attributes": {
        "name": "Education Director 21",
        "weekdays": [],
        "starts_at": "2023-03-22T11:49:40Z",
        "ends_at": "2023-03-22T12:49:40Z",
        "time_from": "11:49",
        "time_to": "12:49",
        "kind": "custom",
        "start_date": "2023-03-22",
        "end_date": "2023-03-22",
        "allow_unit_access": false
      },
      "relationships": {
        "virtual_keys": {
          "data": []
        },
        "devices": {
          "data": []
        }
      }
    },
    {
      "id": "28",
      "type": "keychains",
      "attributes": {
        "name": "Legal Executive 20",
        "weekdays": [],
        "starts_at": "2023-03-22T11:49:40Z",
        "ends_at": "2023-03-22T12:49:40Z",
        "time_from": "11:49",
        "time_to": "12:49",
        "kind": "custom",
        "start_date": "2023-03-22",
        "end_date": "2023-03-22",
        "allow_unit_access": false
      },
      "relationships": {
        "virtual_keys": {
          "data": [
            {
              "id": "24",
              "type": "virtual_keys"
            }
          ]
        },
        "devices": {
          "data": []
        }
      }
    }
  ],
  "included": [
    {
      "id": "24",
      "type": "virtual_keys",
      "attributes": {
        "name": "Carlton Greenfelder III",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-14y05bs.png",
        "email": "freddie_lesch@example.com",
        "sms_number": "+12546262569",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "807196",
        "instructions_url": "http://user.butterflymx.test/public/reilly-sawayn-135/virtual_keys/24/f141ff446c86469ce45b3a3d2e9c3a8b",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/keychains?include=virtual_keys%2Cdevices&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/keychains?include=virtual_keys%2Cdevices&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/keychains?include=virtual_keys%2Cdevices&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/keychains


GET /v3/keychains/31
Requestsreturns the keychain

GET  /v3/keychains/31

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "31",
    "type": "keychains",
    "attributes": {
      "name": "Product Construction Supervisor 23",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:41Z",
      "ends_at": "2023-03-22T12:49:41Z",
      "time_from": "11:49",
      "time_to": "12:49",
      "kind": "custom",
      "start_date": "2023-03-22",
      "end_date": "2023-03-22",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "25",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  }
}

Show
GET/v3/keychains/{id}

URI Parameters
HideShow
id
number (required) Example: 31

DELETE /v3/keychains/32
Requestsdeletes the keychain and associated qr keys

DELETE  /v3/keychains/32

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses204
This response has no content.

Delete
DELETE/v3/keychains/{id}

URI Parameters
HideShow
id
number (required) Example: 32

POST /v3/keychains/one_time
Requestscreates a new keychain with associated qr keyscreates a new keychain with associated qr keysreturns bad request

POST  /v3/keychains/one_time

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "One-Time Key",
      "starts_at": "2023-03-22T11:49:55+00:00",
      "ends_at": "2023-03-24T11:49:50+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ]
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107411
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "33",
    "type": "keychains",
    "attributes": {
      "name": "One-Time Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:55Z",
      "ends_at": "2023-03-24T11:49:50Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "one_time",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "27",
            "type": "virtual_keys"
          },
          {
            "id": "28",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "27",
      "type": "virtual_keys",
      "attributes": {
        "name": "One-Time Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-aiv1dx.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "754960",
        "instructions_url": "http://user.butterflymx.test/public/kemmer-llc-158/virtual_keys/27/9d0f697c5f190699683487ca1a690d81",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "28",
      "type": "virtual_keys",
      "attributes": {
        "name": "One-Time Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-uy6tsd.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "000758",
        "instructions_url": "http://user.butterflymx.test/public/kemmer-llc-158/virtual_keys/28/064d094cbece979e56b5194a61aa117e",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/one_time

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "keychains",
    "attributes": {
      "name": "One-Time Key",
      "starts_at": "2023-03-22T11:49:56+00:00",
      "ends_at": "2023-03-24T11:49:51+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ]
    },
    "relationships": {
      "tenant": {
        "data": {
          "id": "636166974",
          "type": "tenant"
        }
      },
      "access_points": {
        "data": [
          {
            "type": "access_point",
            "id": 842395211
          }
        ]
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "34",
    "type": "keychains",
    "attributes": {
      "name": "One-Time Key",
      "weekdays": [],
      "starts_at": "2023-03-22T11:49:56Z",
      "ends_at": "2023-03-24T11:49:51Z",
      "time_from": "11:49",
      "time_to": "11:49",
      "kind": "one_time",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "29",
            "type": "virtual_keys"
          },
          {
            "id": "30",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "29",
      "type": "virtual_keys",
      "attributes": {
        "name": "One-Time Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-shm5fr.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "963003",
        "instructions_url": "http://user.butterflymx.test/public/powlowski-llc-159/virtual_keys/29/6a1061978ac2a84c7d23664685d7cc0d",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "30",
      "type": "virtual_keys",
      "attributes": {
        "name": "One-Time Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-16waxse.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "442847",
        "instructions_url": "http://user.butterflymx.test/public/powlowski-llc-159/virtual_keys/30/a0d00163c3467c1dbefeeb5580cc9f47",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/one_time

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "One-Time Key",
      "starts_at": "",
      "ends_at": "2023-03-24T11:49:52+00:00",
      "recipients": [
        "test@example.com",
        "+12345678901"
      ]
    },
    "type": "keychains",
    "relationships": {
      "tenant": {
        "data": {
          "type": "tenant",
          "id": 636166975
        }
      }
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/starts_at"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/starts_at"
      },
      "detail": "is not a valid datetime"
    },
    {
      "source": {
        "pointer": "/data/attributes/ends_at"
      },
      "detail": "Error occurred validating ends_at for :after restriction:\ncomparison of ActiveSupport::TimeWithZone with nil failed"
    }
  ]
}

Create One-Time Keychain
POST/v3/keychains/one_time


POST /v3/keychains/recurring
Requestscreates a new keychain with associated qr keyscreates a new keychain with associated qr keyscreates a new keychain with associated devicesreturns bad request

POST  /v3/keychains/recurring

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Recurring Key",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "time_from": "11:20",
      "time_to": "11:50",
      "weekdays": [
        "wed",
        "sat"
      ],
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "creator": {
        "id": 636167011,
        "account_id": 112,
        "first_name": "Bea",
        "last_name": "Schinner",
        "created_at": "2023-03-22T11:49:59Z",
        "updated_at": "2023-03-22T11:49:59Z",
        "email_cache": "jae@boyle.org",
        "qr_key_enabled": true,
        "contact_preference": "phone_call",
        "confirmed_at_cache": null,
        "deleted_at": null,
        "devices_count": 0,
        "status": "registered",
        "panel_status_report": false,
        "invited_at": null,
        "language": "en",
        "download_app_page_shown": true,
        "privacy_consent_given": true,
        "anonymized": false
      }
    },
    "type": "keychains",
    "relationships": {
      "unit": {
        "data": {
          "type": "unit",
          "id": 843107430
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "39",
    "type": "keychains",
    "attributes": {
      "name": "Recurring Key",
      "weekdays": [
        "wed",
        "sat"
      ],
      "starts_at": "2023-03-22T11:20:00Z",
      "ends_at": "2023-03-24T11:50:00Z",
      "time_from": "11:20",
      "time_to": "11:50",
      "kind": "recurring",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "33",
            "type": "virtual_keys"
          },
          {
            "id": "34",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "33",
      "type": "virtual_keys",
      "attributes": {
        "name": "Recurring Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-785b8g.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "247052",
        "instructions_url": "http://user.butterflymx.test/public/howe-rohan-and-wintheiser-173/virtual_keys/33/60115f020ddacee0b5de86dded0271fa",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "34",
      "type": "virtual_keys",
      "attributes": {
        "name": "Recurring Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-hzrjhs.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "847510",
        "instructions_url": "http://user.butterflymx.test/public/howe-rohan-and-wintheiser-173/virtual_keys/34/6ac93f3b5a6bf9643b0d19635ebc7356",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/recurring

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Recurring Key",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "time_from": "11:20",
      "time_to": "11:50",
      "weekdays": [
        "wed",
        "sat"
      ],
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "creator": {
        "id": 636167013,
        "account_id": 114,
        "first_name": "Lino",
        "last_name": "Ankunding",
        "created_at": "2023-03-22T11:50:00Z",
        "updated_at": "2023-03-22T11:50:00Z",
        "email_cache": "enrique_sporer@braun.com",
        "qr_key_enabled": true,
        "contact_preference": "phone_call",
        "confirmed_at_cache": null,
        "deleted_at": null,
        "devices_count": 0,
        "status": "registered",
        "panel_status_report": false,
        "invited_at": null,
        "language": "en",
        "download_app_page_shown": true,
        "privacy_consent_given": true,
        "anonymized": false
      }
    },
    "type": "keychains",
    "relationships": {
      "tenant": {
        "data": {
          "type": "tenant",
          "id": 636166985
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "40",
    "type": "keychains",
    "attributes": {
      "name": "Recurring Key",
      "weekdays": [
        "wed",
        "sat"
      ],
      "starts_at": "2023-03-22T11:20:00Z",
      "ends_at": "2023-03-24T11:50:00Z",
      "time_from": "11:20",
      "time_to": "11:50",
      "kind": "recurring",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "35",
            "type": "virtual_keys"
          },
          {
            "id": "36",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": []
      }
    }
  },
  "included": [
    {
      "id": "35",
      "type": "virtual_keys",
      "attributes": {
        "name": "Recurring Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-i120om.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "437420",
        "instructions_url": "http://user.butterflymx.test/public/o-hara-and-sons-174/virtual_keys/35/13d5fda09ad1e38b4b6bca51119330e7",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "36",
      "type": "virtual_keys",
      "attributes": {
        "name": "Recurring Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1vlia5h.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "438702",
        "instructions_url": "http://user.butterflymx.test/public/o-hara-and-sons-174/virtual_keys/36/c0ba745d65679c00d4c1a0fcdd50d5ef",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    }
  ]
}

POST  /v3/keychains/recurring

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "keychains",
    "attributes": {
      "name": "Recurring Key",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "time_from": "11:20",
      "time_to": "11:50",
      "weekdays": [
        "wed",
        "sat"
      ],
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "creator": {
        "id": 636167015,
        "account_id": 116,
        "first_name": "David",
        "last_name": "Nicolas",
        "created_at": "2023-03-22T11:50:02Z",
        "updated_at": "2023-03-22T11:50:02Z",
        "email_cache": "floria@rippinvandervort.com",
        "qr_key_enabled": true,
        "contact_preference": "phone_call",
        "confirmed_at_cache": null,
        "deleted_at": null,
        "devices_count": 0,
        "status": "registered",
        "panel_status_report": false,
        "invited_at": null,
        "language": "en",
        "download_app_page_shown": true,
        "privacy_consent_given": true,
        "anonymized": false
      }
    },
    "relationships": {
      "devices": {
        "data": [
          {
            "id": "708353713",
            "type": "panels"
          },
          {
            "id": "708353714",
            "type": "panels"
          }
        ]
      },
      "tenant": {
        "data": {
          "id": "636166986",
          "type": "tenant"
        }
      },
      "access_points": {
        "data": [
          {
            "type": "access_point",
            "id": 842395215
          }
        ]
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "41",
    "type": "keychains",
    "attributes": {
      "name": "Recurring Key",
      "weekdays": [
        "wed",
        "sat"
      ],
      "starts_at": "2023-03-22T11:20:00Z",
      "ends_at": "2023-03-24T11:50:00Z",
      "time_from": "11:20",
      "time_to": "11:50",
      "kind": "recurring",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "allow_unit_access": false
    },
    "relationships": {
      "virtual_keys": {
        "data": [
          {
            "id": "37",
            "type": "virtual_keys"
          },
          {
            "id": "38",
            "type": "virtual_keys"
          }
        ]
      },
      "devices": {
        "data": [
          {
            "id": "708353713",
            "type": "panels"
          },
          {
            "id": "708353714",
            "type": "panels"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "37",
      "type": "virtual_keys",
      "attributes": {
        "name": "Recurring Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-hcjquh.png",
        "email": "test@example.com",
        "sms_number": null,
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "209076",
        "instructions_url": "http://user.butterflymx.test/public/doyle-group-175/virtual_keys/37/febb13cc1725da81abfe69fd38ff0c73",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "38",
      "type": "virtual_keys",
      "attributes": {
        "name": "Recurring Key",
        "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1xp2atf.png",
        "email": null,
        "sms_number": "+12345678901",
        "used_at": null,
        "one_time_key_used_at": null,
        "pin": "762447",
        "instructions_url": "http://user.butterflymx.test/public/doyle-group-175/virtual_keys/38/47880fd930ee08081b5d6de585c63234",
        "sent_at": null,
        "synced_with_remote_lock": false
      },
      "relationships": {
        "door_releases": {
          "data": []
        }
      }
    },
    {
      "id": "708353713",
      "type": "panels",
      "attributes": {
        "name": "Hasimir Fenring 63",
        "nfc": {
          "uuid": "57f9fe70-db36-4078-a821-378280722695"
        }
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696437",
            "type": "buildings"
          }
        }
      }
    },
    {
      "id": "708353714",
      "type": "panels",
      "attributes": {
        "name": "Liet-Kynes 64",
        "nfc": {
          "uuid": "a187bd6e-4a41-4f13-9b7c-e9e1c54fffb5"
        }
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696437",
            "type": "buildings"
          }
        }
      }
    }
  ]
}

POST  /v3/keychains/recurring

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "",
      "start_date": "2023-03-22",
      "end_date": "2023-03-24",
      "time_from": "11:20",
      "time_to": "11:50",
      "weekdays": [
        "wed",
        "sat"
      ],
      "recipients": [
        "test@example.com",
        "+12345678901"
      ],
      "creator": {
        "id": 636167017,
        "account_id": 118,
        "first_name": "Patricia",
        "last_name": "Lockman",
        "created_at": "2023-03-22T11:50:05Z",
        "updated_at": "2023-03-22T11:50:05Z",
        "email_cache": "monet_heller@nienowhartmann.org",
        "qr_key_enabled": true,
        "contact_preference": "phone_call",
        "confirmed_at_cache": null,
        "deleted_at": null,
        "devices_count": 0,
        "status": "registered",
        "panel_status_report": false,
        "invited_at": null,
        "language": "en",
        "download_app_page_shown": true,
        "privacy_consent_given": true,
        "anonymized": false
      }
    },
    "type": "keychains",
    "relationships": {
      "tenant": {
        "data": {
          "type": "tenant",
          "id": 636166987
        }
      }
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/name"
      },
      "detail": "can't be blank"
    }
  ]
}

Create Recurring Keychain
POST/v3/keychains/recurring


Virtual Keys

POST /v3/keychains/35/virtual_keys
Requestscreates a new qr keyreturns bad requestreturns not found

POST  /v3/keychains/35/virtual_keys

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Virtual Key",
      "email": "test@example.com"
    },
    "type": "virtual_keys",
    "relationships": null
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "31",
    "type": "virtual_keys",
    "attributes": {
      "name": "Virtual Key",
      "qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1eow6bm.png",
      "email": "test@example.com",
      "sms_number": null,
      "used_at": null,
      "one_time_key_used_at": null,
      "pin": "188756",
      "instructions_url": "http://user.butterflymx.test/public/towne-schultz-and-connelly-169/virtual_keys/31/d60d196635ddf1c3b777df0bb96bb057",
      "sent_at": null,
      "synced_with_remote_lock": false
    },
    "relationships": {
      "door_releases": {
        "data": []
      }
    }
  }
}

POST  /v3/keychains/36/virtual_keys

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Virtual Key",
      "sms_number": "DOES_NOT_EXIST"
    },
    "type": "virtual_keys",
    "relationships": null
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/sms_number"
      },
      "detail": "DOES_NOT_EXIST is invalid"
    }
  ]
}

POST  /v3/keychains/DOES_NOT_EXIST/virtual_keys

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Virtual Key",
      "email": "test@example.com"
    },
    "type": "virtual_keys",
    "relationships": null
  }
}
Responses404
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "title": "Record not found",
      "detail": "Requested record could not be found"
    }
  ]
}

Create
POST/v3/keychains/{keychain_id}/virtual_keys

URI Parameters
HideShow
keychain_id
number (required) Example: 35

DELETE /v3/keychains/38/virtual_keys/32
Requestsdeletes the virtual key

DELETE  /v3/keychains/38/virtual_keys/32

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses204
This response has no content.

Delete
DELETE/v3/keychains/{keychain_id}/virtual_keys/{id}

URI Parameters
HideShow
keychain_id
number (required) Example: 38
id
number (required) Example: 32

Notifications

Call Accepted

POST /v3/notifications/call_accepted
Requestsreturns notification successreturns validation error

POST  /v3/notifications/call_accepted

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353703",
    "attributes": {
      "panel_id": 708353703,
      "video": true,
      "audio": false,
      "call_guid": "87142693-c04f-43a6-bf12-8495b33633d0"
    }
  }
}
Responses204
This response has no content.

POST  /v3/notifications/call_accepted

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353704",
    "attributes": {
      "panel_id": "NOT_EXIST",
      "video": true,
      "audio": false,
      "call_guid": "9d0c24fa-3cbe-4ec6-80dd-5f34c8efd1d3"
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/panel_id"
      },
      "detail": "No panel with that ID"
    }
  ]
}

Call Accepted
POST/v3/notifications/call_accepted


Call Ended

POST /v3/notifications/call_ended
Requestsreturns notification successreturns validation error

POST  /v3/notifications/call_ended

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353705",
    "attributes": {
      "panel_id": 708353705,
      "call_guid": "b4d4a83c-ba08-46c6-bdd7-bb73184da626"
    }
  }
}
Responses204
This response has no content.

POST  /v3/notifications/call_ended

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353706",
    "attributes": {
      "panel_id": "NOT_EXIST",
      "call_guid": "c9f0908e-fd3e-4585-90dd-2cc5a169b95a"
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/panel_id"
      },
      "detail": "No panel with that ID"
    }
  ]
}

Call Ended
POST/v3/notifications/call_ended


Is Active

POST /v3/notifications/is_active
Requestsreturns notification successreturns validation error

POST  /v3/notifications/is_active

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353707",
    "attributes": {
      "panel_id": 708353707,
      "call_guid": "adaa57b8-39f1-4681-a91d-0c6c01fce14e"
    }
  }
}
Responses204
This response has no content.

POST  /v3/notifications/is_active

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353708",
    "attributes": {
      "panel_id": "NOT_EXIST",
      "call_guid": "6c555721-7e57-40d6-815e-b944866c52fa"
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/panel_id"
      },
      "detail": "No panel with that ID"
    }
  ]
}

Is Active
POST/v3/notifications/is_active


Open Door

POST /v3/notifications/open_door
Requestsreturns notification successreturns validation error

POST  /v3/notifications/open_door

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353709",
    "attributes": {
      "panel_id": 708353709,
      "call_guid": "28a0c2ab-a3f0-43b7-9fc6-085197475a87"
    }
  }
}
Responses204
This response has no content.

POST  /v3/notifications/open_door

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353710",
    "attributes": {
      "panel_id": "NOT_EXIST",
      "call_guid": "eb02d900-9ff5-4e92-83d1-6bcf8be2eca9"
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/panel_id"
      },
      "detail": "No panel with that ID"
    }
  ]
}

Open Door
POST/v3/notifications/open_door


Toggle Camera

POST /v3/notifications/toggle_camera
Requestsreturns notification successreturns validation error

POST  /v3/notifications/toggle_camera

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353711",
    "attributes": {
      "panel_id": 708353711,
      "video": true,
      "audio": false,
      "call_guid": "8a9624ab-3765-4afc-9191-38ebe5ecac29"
    }
  }
}
Responses204
This response has no content.

POST  /v3/notifications/toggle_camera

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "notifications",
    "id": "708353712",
    "attributes": {
      "panel_id": "NOT_EXIST",
      "video": true,
      "audio": false,
      "call_guid": "e6ce8c87-fe11-4259-a62c-bc0f678ae655"
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/panel_id"
      },
      "detail": "No panel with that ID"
    }
  ]
}

Toggle Camera
POST/v3/notifications/toggle_camera


Pins

Pins

On these endpoints you can create and view PINs for tenants. The id parameter in the request must be the id of the tenant.

Parameters that are required for pins:

id -> integer

code -> string (must be numeric)

POST /v3/pins/combine
Requestsreturns success

POST  /v3/pins/combine

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "pins",
    "id": "636166976",
    "attributes": {}
  }
}
Responses204
This response has no content.

Combine
POST/v3/pins/combine


GET /v3/pins/636166977
Requestsreturns the PIN code

GET  /v3/pins/636166977

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166977",
    "type": "pins",
    "attributes": {
      "code": "5834",
      "unique_code": null
    }
  }
}

Show
GET/v3/pins/{id}

URI Parameters
HideShow
id
number (required) Example: 636166977

PUT /v3/pins
Requestschanges the pin for the tenantdoes not change the pin for the tenant

PUT  /v3/pins

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "pins",
    "id": "636166978",
    "attributes": {
      "code": "0854",
      "unique_code": "085436"
    }
  }
}
Responses204
This response has no content.

PUT  /v3/pins

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "pins",
    "id": "636166979",
    "attributes": {
      "code": ""
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/code"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/code"
      },
      "detail": "is not a number"
    },
    {
      "source": {
        "pointer": "/data/attributes/code"
      },
      "detail": "is the wrong length (should be 4 characters)"
    }
  ]
}

Set
PUT/v3/pins


Tenants

Integrations

Integrations

Allowed integrators:

  • webhook

Allowed config attributes for integrators:

  • webhook
    • url (String)
    • method (String get or post)

Allowed binding resource types:

  • call

  • door_release

GET /v3/tenants/2262/integrations
Requestsreturns the list of integrations associated with this tenant

GET  /v3/tenants/2262/integrations

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70",
      "type": "integrations",
      "attributes": {
        "integrator": "webhook",
        "config": {
          "method": "get",
          "url": "http://localhost:999"
        },
        "bindings": [
          {
            "resource_type": "door_release",
            "resource_id": "7",
            "actions": [
              "update",
              "destroy"
            ]
          }
        ]
      },
      "relationships": {
        "bindings": {
          "data": [
            {
              "resource_type": "door_release",
              "resource_id": "7",
              "actions": [
                "update",
                "destroy"
              ]
            }
          ]
        },
        "building": {
          "data": null
        },
        "tenant": {
          "data": {
            "id": "2262",
            "type": "units_users"
          }
        }
      },
      "links": {
        "self": "http://api.butterflymx.com/v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70"
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/tenants/2262/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "first": "http://api.butterflymx.com/v3/tenants/2262/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=10",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/tenants/2262/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=10"
  }
}

List
GET/v3/tenants/{tenant_id}/integrations

URI Parameters
HideShow
tenant_id
number (required) Example: 2262

GET /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Requestsreturns the requested integration

GET  /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70",
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "config": {
        "method": "get",
        "url": "http://localhost:999"
      },
      "bindings": [
        {
          "resource_type": "door_release",
          "resource_id": "7",
          "actions": [
            "update",
            "destroy"
          ]
        }
      ]
    },
    "relationships": {
      "bindings": {
        "data": [
          {
            "resource_type": "door_release",
            "resource_id": "7",
            "actions": [
              "update",
              "destroy"
            ]
          }
        ]
      },
      "building": {
        "data": null
      },
      "tenant": {
        "data": {
          "id": "2262",
          "type": "units_users"
        }
      }
    },
    "links": {
      "self": "http://api.butterflymx.com/v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70"
    }
  }
}

Show
GET/v3/tenants/{tenant_id}/integrations/{id}

URI Parameters
HideShow
tenant_id
number (required) Example: 2262
id
string (required) Example: bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70

POST /v3/tenants/2262/integrations
Requestscreates the integration for the tenant

POST  /v3/tenants/2262/integrations

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Body
{
  "data": {
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "configuration": {
        "url": "http://localhost:666",
        "method": "post"
      },
      "bindings": [
        {
          "actions": [
            "create"
          ],
          "resource_type": "call",
          "resource_id": null
        }
      ]
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70",
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "config": {
        "method": "post",
        "url": "http://localhost:666"
      },
      "bindings": [
        {
          "resource_type": "call",
          "resource_id": null,
          "actions": [
            "create"
          ]
        }
      ]
    },
    "relationships": {
      "bindings": {
        "data": [
          {
            "resource_type": "call",
            "resource_id": null,
            "actions": [
              "create"
            ]
          }
        ]
      },
      "building": {
        "data": null
      },
      "tenant": {
        "data": {
          "id": "2262",
          "type": "units_users"
        }
      }
    },
    "links": {
      "self": "http://api.butterflymx.com/v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70"
    }
  }
}

Create
POST/v3/tenants/{tenant_id}/integrations

URI Parameters
HideShow
tenant_id
number (required) Example: 2262

PATCH /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Requestsupdates the tenet's integration

PATCH  /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Body
{
  "data": {
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "configuration": {
        "url": "http://localhost:999",
        "method": "get"
      },
      "bindings": [
        {
          "actions": [
            "update",
            "destroy"
          ],
          "resource_type": "door_release",
          "resource_id": "7"
        }
      ]
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70",
    "type": "integrations",
    "attributes": {
      "integrator": "webhook",
      "config": {
        "method": "get",
        "url": "http://localhost:999"
      },
      "bindings": [
        {
          "resource_type": "door_release",
          "resource_id": "7",
          "actions": [
            "update",
            "destroy"
          ]
        }
      ]
    },
    "relationships": {
      "bindings": {
        "data": [
          {
            "resource_type": "door_release",
            "resource_id": "7",
            "actions": [
              "update",
              "destroy"
            ]
          }
        ]
      },
      "building": {
        "data": null
      },
      "tenant": {
        "data": {
          "id": "2262",
          "type": "units_users"
        }
      }
    },
    "links": {
      "self": "http://api.butterflymx.com/v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70"
    }
  }
}

Update
PATCH/v3/tenants/{tenant_id}/integrations/{id}

URI Parameters
HideShow
tenant_id
number (required) Example: 2262
id
string (required) Example: bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70

DELETE /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Requestsdeletes the tenant's integration

DELETE  /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70

Headers
Accept: application/vnd.api+json
Content-Type: application/json
Responses204
This response has no content.

Delete
DELETE/v3/tenants/{tenant_id}/integrations/{id}

URI Parameters
HideShow
tenant_id
number (required) Example: 2262
id
string (required) Example: bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70

Tenants

Assign User to the Unit as a Tenant

A user is assigned as a unit’s tenant by creating a tenancy. This can be achieved with API call: POST /v3/tenants

And sending following required attributes:

  • email (String) - must be a valid email address

  • first_name (String)

  • last_name (String)

  • unit_id (Integer)

Optional Attributes:

  • active_at (DateTime) - in ISO 8601 format e.g. 2017-12-27T11:03:50Z

  • inactive_at (DateTime)

  • pin (String)

  • directory_message (String)

  • display_name_strategy (String), one of the allowed values:

    • building
    • custom
    • first_name_and_last_name
    • first_name_initial_and_last_name
    • anonymous
    • first_name_and_last_name_initial
  • sms_notifications (Boolean)

  • email_notifications (Boolean)

  • preferences (Object)

    • calls (Object)
      • push (Boolean)
      • email (Boolean)
      • sms (Boolean)
    • door_opens (Object)
      • push (Boolean)
      • email (Boolean)
      • sms (Boolean)
    • messages (Object)
      • push (Boolean)
      • email (Boolean)
      • sms (Boolean)
  • do_not_disturb (Boolean)

  • skip_registration_email(Boolean)

When a valid email is submitted, then:

  • if there is no registered user in ButterflyMX with this email, a new user will be created and added as a tenant. Additionally, a registration e-mail will be sent to the users e-mail address unless skip_registration_email parameter is set to true

  • if there is a registered user with this email, an existing user will be added as a tenant (submitted attributes first_name and last_name will be ignored)

On success, server will respond with a 201 Created status code and a JSON API document.

Sortable fields:

  • created_at

Filterable fields:

  • display_name_strategy

  • display_only_on_search

  • pin_enabled

  • email_notifications

  • sms_notifications

  • do_not_disturb

Enumerations:

  • display_name_strategy:
    • building
    • custom
    • first_name_and_last_name
    • first_name_initial_and_last_name
    • anonymous
    • first_name_and_last_name_initial
GET /v3/tenants
Requestsshows a list of tenants

GET  /v3/tenants

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "636166991",
      "type": "tenants",
      "attributes": {
        "active_at": "2023-03-22T11:50:06Z",
        "inactive_at": null,
        "qr_key_enabled": true,
        "delivery_pass_instructions": null,
        "directory_message": "Regional Advertising Supervisor",
        "display_name": "Mrs. Tyron Bruen",
        "display_name_strategy": "building",
        "display_first_name": "Maryalice Lebsack",
        "display_last_name": "James Stamm",
        "display_only_on_search": true,
        "pin_enabled": true,
        "email_notifications": true,
        "sms_notifications": true,
        "do_not_disturb": false,
        "preferences": {
          "door_opens": {
            "push": false,
            "email": false,
            "sms": null
          },
          "messages": {
            "push": true,
            "email": false,
            "sms": false
          }
        }
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107440",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636167024",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "636166990",
      "type": "tenants",
      "attributes": {
        "active_at": "2023-03-22T11:50:06Z",
        "inactive_at": null,
        "qr_key_enabled": true,
        "delivery_pass_instructions": null,
        "directory_message": "Marketing Architect",
        "display_name": "Hannelore Kohler",
        "display_name_strategy": "building",
        "display_first_name": "Brian Muller V",
        "display_last_name": "Lance Fahey",
        "display_only_on_search": false,
        "pin_enabled": true,
        "email_notifications": true,
        "sms_notifications": true,
        "do_not_disturb": false,
        "preferences": {
          "door_opens": {
            "push": false,
            "email": false,
            "sms": null
          },
          "messages": {
            "push": true,
            "email": false,
            "sms": false
          }
        }
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107440",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636167023",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "636166989",
      "type": "tenants",
      "attributes": {
        "active_at": "2023-03-22T11:50:06Z",
        "inactive_at": null,
        "qr_key_enabled": true,
        "delivery_pass_instructions": null,
        "directory_message": "Global Hospitality Liaison",
        "display_name": "Hui Hessel",
        "display_name_strategy": "building",
        "display_first_name": "Roselle Runolfsson",
        "display_last_name": "Vicente Jakubowski PhD",
        "display_only_on_search": false,
        "pin_enabled": true,
        "email_notifications": true,
        "sms_notifications": true,
        "do_not_disturb": false,
        "preferences": {
          "door_opens": {
            "push": false,
            "email": false,
            "sms": null
          },
          "messages": {
            "push": true,
            "email": false,
            "sms": false
          }
        }
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "843107440",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "636167022",
            "type": "users"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "636167024",
      "type": "users",
      "attributes": {
        "name": "Cleo Kohler",
        "first_name": "Cleo",
        "last_name": "Kohler",
        "contact_preference": "phone_call",
        "thumb_url": null,
        "medium_url": null,
        "sip_username": "125",
        "registration_status": "registered",
        "email": "noel_wilkinson@bartonsipes.org",
        "sms_phone_number": null,
        "phone_number": null
      }
    },
    {
      "id": "636167023",
      "type": "users",
      "attributes": {
        "name": "Lacie Cole",
        "first_name": "Lacie",
        "last_name": "Cole",
        "contact_preference": "phone_call",
        "thumb_url": null,
        "medium_url": null,
        "sip_username": "124",
        "registration_status": "registered",
        "email": "deon.kertzmann@cole.org",
        "sms_phone_number": null,
        "phone_number": null
      }
    },
    {
      "id": "636167022",
      "type": "users",
      "attributes": {
        "name": "Werner Trantow",
        "first_name": "Werner",
        "last_name": "Trantow",
        "contact_preference": "phone_call",
        "thumb_url": null,
        "medium_url": null,
        "sip_username": "123",
        "registration_status": "registered",
        "email": "cleopatra_krajcik@oberbrunner.biz",
        "sms_phone_number": null,
        "phone_number": null
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/tenants?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/tenants?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/tenants?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/tenants


GET /v3/tenants/636166992
Requestsshows the tenant

GET  /v3/tenants/636166992

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166992",
    "type": "tenants",
    "attributes": {
      "active_at": "2023-03-22T11:50:07Z",
      "inactive_at": null,
      "qr_key_enabled": true,
      "delivery_pass_instructions": null,
      "directory_message": "Forward Manufacturing Manager",
      "display_name": "Adalberto Johnston",
      "display_name_strategy": "building",
      "display_first_name": "Abram Hansen",
      "display_last_name": "Mr. Bo Emard",
      "display_only_on_search": false,
      "pin_enabled": true,
      "email_notifications": true,
      "sms_notifications": true,
      "do_not_disturb": false,
      "preferences": {
        "door_opens": {
          "push": false,
          "email": false,
          "sms": null
        },
        "messages": {
          "push": true,
          "email": false,
          "sms": false
        }
      }
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "843107442",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "636167026",
          "type": "users"
        }
      }
    }
  },
  "included": [
    {
      "id": "636167026",
      "type": "users",
      "attributes": {
        "name": "Johnny Cole",
        "first_name": "Johnny",
        "last_name": "Cole",
        "contact_preference": "phone_call",
        "thumb_url": null,
        "medium_url": null,
        "sip_username": "127",
        "registration_status": "registered",
        "email": "chad.cummings@wehner.net",
        "sms_phone_number": null,
        "phone_number": null
      }
    }
  ]
}

Show
GET/v3/tenants/{id}

URI Parameters
HideShow
id
number (required) Example: 636166992

POST /v3/tenants
Requestscreates a tenantreturns bad request

POST  /v3/tenants

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "unit_id": 843107444,
      "email": "fiona@schneider.biz",
      "active_at": "2023-03-22T11:50:07Z"
    },
    "type": "tenants",
    "relationships": null
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166993",
    "type": "tenants",
    "attributes": {
      "active_at": "2023-03-22T11:50:07Z",
      "inactive_at": null,
      "qr_key_enabled": true,
      "delivery_pass_instructions": null,
      "directory_message": null,
      "display_name": "Resident",
      "display_name_strategy": "building",
      "display_first_name": "Resident",
      "display_last_name": " ",
      "display_only_on_search": false,
      "pin_enabled": true,
      "email_notifications": false,
      "sms_notifications": false,
      "do_not_disturb": false,
      "preferences": {
        "door_opens": {
          "push": false,
          "email": false,
          "sms": null
        },
        "messages": {
          "push": true,
          "email": false,
          "sms": false
        }
      }
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "843107444",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "636167028",
          "type": "users"
        }
      }
    }
  }
}

POST  /v3/tenants

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "unit_id": 843107446,
      "email": "",
      "first_name": "",
      "last_name": "User",
      "active_at": "2023-03-22T11:50:08Z"
    },
    "type": "tenants",
    "relationships": null
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/user"
      },
      "detail": "must exist"
    },
    {
      "source": {
        "pointer": "/data/attributes/user"
      },
      "detail": "can't be blank"
    }
  ]
}

Create
POST/v3/tenants


PATCH /v3/tenants/636166994
Requestsupdates the tenantreturns bad request

PATCH  /v3/tenants/636166994

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "tenants",
    "id": "636166994",
    "attributes": {
      "do_not_disturb": true,
      "user_panel_config": {
        "pin_enabled": true
      }
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "636166994",
    "type": "tenants",
    "attributes": {
      "active_at": "2023-03-22T11:50:08Z",
      "inactive_at": null,
      "qr_key_enabled": true,
      "delivery_pass_instructions": null,
      "directory_message": "Mining Strategist",
      "display_name": "Giovanna Moen",
      "display_name_strategy": "building",
      "display_first_name": "Zola Jacobs",
      "display_last_name": "Mica Smitham",
      "display_only_on_search": true,
      "pin_enabled": true,
      "email_notifications": true,
      "sms_notifications": true,
      "do_not_disturb": true,
      "preferences": {
        "door_opens": {
          "push": false,
          "email": false,
          "sms": null
        },
        "messages": {
          "push": true,
          "email": false,
          "sms": false
        }
      }
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "843107448",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "636167032",
          "type": "users"
        }
      }
    }
  }
}

PATCH  /v3/tenants/636166995

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "tenants",
    "id": "636166995",
    "attributes": {
      "display_name_strategy": ""
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/user_panel_config.display_name_strategy"
      },
      "detail": "can't be blank"
    }
  ]
}

Update
PATCH/v3/tenants/{id}

URI Parameters
HideShow
id
number (required) Example: 636166994

DELETE /v3/tenants/636166996
Requestsdeletes the tenant

DELETE  /v3/tenants/636166996

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses204
This response has no content.

Delete
DELETE/v3/tenants/{id}

URI Parameters
HideShow
id
number (required) Example: 636166996

Tours

Tour Schedules

Creating Tours consumes time slots. The number of time slots and the duration of a time slot is configurable in the PAC UI.

The consumed time slots can be reviewed with GET/v3/tours/{building_handle}/tour_schedules endpoint.

Times can be specified with AM/PM format timezone offsets, for example like this:

2021-04-16T02:00:00 PM -05:00 along with UTC time format described in the examples below.

GET /v3/tours/kemmer-and-sons-188/tour_schedules
Requestsreturns building data with availabilities and taken time slots

GET  /v3/tours/kemmer-and-sons-188/tour_schedules

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "577696450",
    "type": "buildings",
    "attributes": {
      "handle": "kemmer-and-sons-188",
      "name": "Kemmer and Sons-188",
      "slots": {
        "weekday_availabilities": {
          "mon": [
            [
              "09:00",
              "22:00"
            ]
          ],
          "wed": [
            [
              "09:00",
              "22:00"
            ]
          ],
          "fri": [
            [
              "09:00",
              "22:00"
            ]
          ]
        },
        "scheduled_slots": {
          "2020-12-14T13:00:00Z": 1,
          "2020-12-14T14:00:00Z": 1,
          "2020-12-14T19:00:00Z": 1
        },
        "reserved_slots": {
          "2020-12-14T12:00:00Z": 1
        },
        "blacked_out_slots": [
          {
            "starts_at": "2020-12-14T17:00:00Z",
            "ends_at": "2020-12-14T18:00:00Z"
          }
        ]
      },
      "slot_duration_minutes": 60,
      "max_simultaneous_bookings": 1,
      "time_window_days": 14,
      "address": {
        "country": "us",
        "address_1": "11493 Stark Junctions",
        "address_2": "Ritchieview, CT 32693",
        "city": "Ritchieview",
        "state": "Connecticut",
        "zip_code": "32693",
        "phone_number": "358.136.0006 x88336"
      },
      "enabled": true,
      "tour_units": [],
      "unit_selection": false,
      "identity_verification": false,
      "key_locker_in_use": false,
      "shared_key_compartment_count": 0,
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00",
      "day_of_tour_text": null,
      "tos_text": null,
      "day_of_tour_text_draft": null,
      "credit_card_hold": false,
      "email_communication": true,
      "sms_communication": true,
      "enable_scheduling_portal": true
    }
  }
}

List
GET/v3/tours/{building_handle}/tour_schedules

URI Parameters
HideShow
building_handle
string (required) Example: kemmer-and-sons-188

POST /v3/tours/funk-klocko-190/tour_schedules
Requestscreates a TourSchedulereturns bad request

POST  /v3/tours/funk-klocko-190/tour_schedules

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Funk-Klocko-190 Tour",
      "email": "tour@example.com",
      "phone_number": "(555) 555-1234",
      "starts_at": "2020-12-14T12:00:00Z"
    },
    "type": "tour_schedules",
    "relationships": null
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "10",
    "type": "tour_schedules",
    "attributes": {
      "name": "Funk-Klocko-190 Tour",
      "email": "tour@example.com",
      "starts_at": "2020-12-14T12:00:00Z",
      "ends_at": "2020-12-14T13:00:00Z",
      "uuid": "e343acdf-06f7-4fd7-849f-a8637604039a",
      "status": "confirmed",
      "qr_key_public_url": "http://user.butterflymx.test/public/funk-klocko-190/virtual_keys/39/b0d420fe3982af7e215eb5b5c90e2ba4",
      "pin": "892274",
      "qr_key_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/qr_code_20201214-1020-828a3j.png",
      "phone_number": "(555) 555-1234",
      "building_handle": "funk-klocko-190",
      "building_name": "Funk-Klocko-190",
      "building_address": {
        "country": "us",
        "address_1": "604 Conn Grove",
        "address_2": "Romagueraside, LA 68501-9973",
        "city": "Romagueraside",
        "state": "Louisiana",
        "zip_code": "68501-9973",
        "phone_number": "(727) 944-9106 x4951"
      },
      "tour_units": [],
      "day_of_tour_url": "http://selftours.butterflymx.test/tour/e343acdf-06f7-4fd7-849f-a8637604039a",
      "keychains": [],
      "key_locker_in_use": false
    }
  }
}

POST  /v3/tours/kozey-bradtke-and-langosh-192/tour_schedules

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "name": "Kozey, Bradtke and Langosh-192 Tour ",
      "email": "tour@example.com",
      "starts_at": "2020-12-15T11:00:00Z"
    },
    "type": "tour_schedules",
    "relationships": null
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/starts_at"
      },
      "detail": "is not available, outside availability hours"
    }
  ]
}

Create
POST/v3/tours/{building_handle}/tour_schedules

URI Parameters
HideShow
building_handle
string (required) Example: funk-klocko-190

GET /v3/tours/49040d35-8bd7-4ba3-a9ee-865b60364b8d
Requestsreturns success

GET  /v3/tours/49040d35-8bd7-4ba3-a9ee-865b60364b8d

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "11",
    "type": "tour_schedules",
    "attributes": {
      "name": "Confirmed Tour",
      "email": "guest@example.com",
      "starts_at": "2020-12-14T12:00:00Z",
      "ends_at": "2020-12-14T13:00:00Z",
      "uuid": "49040d35-8bd7-4ba3-a9ee-865b60364b8d",
      "status": "confirmed",
      "qr_key_public_url": null,
      "pin": null,
      "qr_key_image_url": null,
      "phone_number": "864.205.0010",
      "building_handle": "kub-llc-194",
      "building_name": "Kub LLC-194",
      "building_address": {
        "country": "us",
        "address_1": "636 Cronin Estates",
        "address_2": "Port Lloyd, AL 70551-8106",
        "city": "Port Lloyd",
        "state": "Alabama",
        "zip_code": "70551-8106",
        "phone_number": "1-443-330-4141 x168"
      },
      "tour_units": [],
      "day_of_tour_url": "http://selftours.butterflymx.test/tour/49040d35-8bd7-4ba3-a9ee-865b60364b8d",
      "keychains": [],
      "key_locker_in_use": false
    }
  }
}

Show
GET/v3/tours/{uuid}

URI Parameters
HideShow
uuid
string (required) Example: 49040d35-8bd7-4ba3-a9ee-865b60364b8d

PATCH /v3/tours/314b95d7-9a06-4a84-9328-39250572bd58
Requestsupdates the TourSchedule starts_at and changes status to rescheduled

PATCH  /v3/tours/314b95d7-9a06-4a84-9328-39250572bd58

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "tour_schedules",
    "id": "12",
    "attributes": {
      "starts_at": "2020-12-16T12:00:00Z"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "12",
    "type": "tour_schedules",
    "attributes": {
      "name": "Confirmed Tour",
      "email": "guest@example.com",
      "starts_at": "2020-12-16T12:00:00Z",
      "ends_at": "2020-12-16T13:00:00Z",
      "uuid": "314b95d7-9a06-4a84-9328-39250572bd58",
      "status": "rescheduled",
      "qr_key_public_url": "http://user.butterflymx.test/public/ernser-borer-196/virtual_keys/40/2a9a993b8c07d4d82f03d5d94db35d9c",
      "pin": "687879",
      "qr_key_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/qr_code_20201214-1020-15ptoms.png",
      "phone_number": "779-379-4810 x5638",
      "building_handle": "ernser-borer-196",
      "building_name": "Ernser-Borer-196",
      "building_address": {
        "country": "us",
        "address_1": "801 Champlin Mills",
        "address_2": "Gabriellestad, WY 94650",
        "city": "Gabriellestad",
        "state": "Wyoming",
        "zip_code": "94650",
        "phone_number": "144-994-6521 x5559"
      },
      "tour_units": [],
      "day_of_tour_url": "http://selftours.butterflymx.test/tour/314b95d7-9a06-4a84-9328-39250572bd58",
      "keychains": [],
      "key_locker_in_use": false
    }
  }
}

Update
PATCH/v3/tours/{uuid}

URI Parameters
HideShow
uuid
string (required) Example: 314b95d7-9a06-4a84-9328-39250572bd58

DELETE /v3/tours/c0a05911-2270-49ab-8e50-26566d87439d
Requestschanges the TourSchedule status to cancelled

DELETE  /v3/tours/c0a05911-2270-49ab-8e50-26566d87439d

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "13",
    "type": "tour_schedules",
    "attributes": {
      "name": "Confirmed Tour",
      "email": "guest@example.com",
      "starts_at": "2020-12-14T12:00:00Z",
      "ends_at": "2020-12-14T13:00:00Z",
      "uuid": "c0a05911-2270-49ab-8e50-26566d87439d",
      "status": "cancelled",
      "qr_key_public_url": null,
      "pin": null,
      "qr_key_image_url": null,
      "phone_number": "(361) 047-8999 x1508",
      "building_handle": "torp-mueller-and-white-198",
      "building_name": "Torp, Mueller and White-198",
      "building_address": {
        "country": "us",
        "address_1": "1862 Zieme Centers",
        "address_2": "Harlandburgh, LA 86478",
        "city": "Harlandburgh",
        "state": "Louisiana",
        "zip_code": "86478",
        "phone_number": "(100) 663-1417 x895"
      },
      "tour_units": [],
      "day_of_tour_url": "http://selftours.butterflymx.test/tour/c0a05911-2270-49ab-8e50-26566d87439d",
      "keychains": [],
      "key_locker_in_use": false
    }
  }
}

Delete
DELETE/v3/tours/{uuid}

URI Parameters
HideShow
uuid
string (required) Example: c0a05911-2270-49ab-8e50-26566d87439d

Units

Units

Unit creation

  • When creating a unit, a building_id needs to be sent alongside the units attributes, so a unit can be assigned to a building.

Includeable resources:

  • building

  • users

Filterable fields:

  • floor_number (integer)

  • kind (enumeration)

  • label (string)

Sortable fields:

  • id

  • floor_number

  • kind

  • label

  • updated_at

  • created_at

Enumerations:

  • kind:
    • residential
    • commercial
GET /v3/units/843107473
Requestsshows the unit

GET  /v3/units/843107473

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "843107473",
    "type": "units",
    "attributes": {
      "kind": "residential",
      "label": "56056",
      "floor_number": 56
    },
    "relationships": {
      "building": {
        "data": {
          "id": "577696462",
          "type": "buildings"
        }
      },
      "users": {
        "data": []
      }
    }
  }
}

Show
GET/v3/units/{id}

URI Parameters
HideShow
id
number (required) Example: 843107473

GET /v3/units
Requestsshows a list of tenantsshows a list of tenants with included resources

GET  /v3/units

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "843107477",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "59059",
        "floor_number": 59
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696464",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    },
    {
      "id": "843107476",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "58058",
        "floor_number": 58
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696464",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    },
    {
      "id": "843107475",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "57057",
        "floor_number": 57
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696464",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    },
    {
      "id": "843107474",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "00",
        "floor_number": 0
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696464",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/units?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/units?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/units?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

GET  /v3/units?include=users,building

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "843107481",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "62062",
        "floor_number": 62
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696465",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    },
    {
      "id": "843107480",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "61061",
        "floor_number": 61
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696465",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    },
    {
      "id": "843107479",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "60060",
        "floor_number": 60
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696465",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    },
    {
      "id": "843107478",
      "type": "units",
      "attributes": {
        "kind": "residential",
        "label": "00",
        "floor_number": 0
      },
      "relationships": {
        "building": {
          "data": {
            "id": "577696465",
            "type": "buildings"
          }
        },
        "users": {
          "data": []
        }
      }
    }
  ],
  "included": [
    {
      "id": "577696465",
      "type": "buildings",
      "attributes": {
        "name": "Gibson-Wuckert-203",
        "building_type": "multi_family",
        "display_name_strategy": "first_name_and_last_name",
        "nfc_enabled": false,
        "send_panel_status_report": false,
        "mobile_logo_picture": {
          "thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
          "medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
        },
        "panel_logo_picture": {
          "thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
          "medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
        },
        "address_1": "890 Kuhn Plains",
        "address_2": "North Rickmouth, OR 96362",
        "city": "North Rickmouth",
        "state": "Oregon",
        "zip_code": "96362",
        "phone_number": "(125) 346-0118 x8652",
        "country": "us",
        "qr_key_enabled": true,
        "time_zone": "Etc/UTC",
        "time_zone_offset": "+00:00",
        "delivery_pass_enabled": true,
        "door_release_pin": true,
        "open_door_button_enabled": true
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/units?include=users%2Cbuilding&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/units?include=users%2Cbuilding&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/units?include=users%2Cbuilding&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/units


POST /v3/buildings/577696466/units
Requestscreates the unitreturns bad requestreturns not found

POST  /v3/buildings/577696466/units

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "kind": "residential",
      "label": "foo",
      "floor_number": 11
    },
    "type": "units",
    "relationships": null
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "843107483",
    "type": "units",
    "attributes": {
      "kind": "residential",
      "label": "foo",
      "floor_number": 11
    },
    "relationships": {
      "building": {
        "data": {
          "id": "577696466",
          "type": "buildings"
        }
      },
      "users": {
        "data": []
      }
    }
  }
}

POST  /v3/buildings/577696467/units

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units",
    "attributes": {
      "kind": "residential"
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/label"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/floor_number"
      },
      "detail": "can't be blank"
    },
    {
      "source": {
        "pointer": "/data/attributes/floor_number"
      },
      "detail": "is not a number"
    }
  ]
}

POST  /v3/buildings/DOES_NOT_EXIST/units

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units",
    "attributes": {
      "kind": "residential",
      "label": "foo",
      "floor_number": 11
    }
  }
}
Responses404
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "title": "Record not found",
      "detail": "Requested record could not be found"
    }
  ]
}

Create
POST/v3/buildings/{building_id}/units

URI Parameters
HideShow
building_id
number (required) Example: 577696466

PUT /v3/units/843107488
Requestsupdates the unitreturns bad request

PUT  /v3/units/843107488

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units",
    "attributes": {
      "kind": "residential",
      "label": "New Label",
      "floor_number": 11,
      "building_id": 577696469
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "843107488",
    "type": "units",
    "attributes": {
      "kind": "residential",
      "label": "New Label",
      "floor_number": 11
    },
    "relationships": {
      "building": {
        "data": {
          "id": "577696469",
          "type": "buildings"
        }
      },
      "users": {
        "data": []
      }
    }
  }
}

PUT  /v3/units/843107491

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units",
    "attributes": {
      "label": ""
    }
  }
}
Responses400
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "errors": [
    {
      "source": {
        "pointer": "/data/attributes/label"
      },
      "detail": "can't be blank"
    }
  ]
}

Update
PUT/v3/units/{id}

URI Parameters
HideShow
id
number (required) Example: 843107488

DELETE /v3/units/843107494
Requestsdeletes a unit

DELETE  /v3/units/843107494

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses204
This response has no content.

Delete
DELETE/v3/units/{id}

URI Parameters
HideShow
id
number (required) Example: 843107494

Generated by aglio on 22 Mar 2023