ButterflyMX API V3
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_SECRETResponse 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)
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+jsonSorting
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+jsonMultiple 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+jsonDescendant 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+jsonMultiple Sort with Descendant Sort
GET https://apisandbox.butterflymx.com/v3/door_releases?sort=-created_at,name
Accept: application/vnd.api+jsonThe 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+jsonor
GET https://apisandbox.butterflymx.com/v3/door_releases?filter[unit]=11&filter[user]=22
Accept: application/vnd.api+jsonCheck each resource to see which fields can be filtered.
Inclusion of related resources
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+jsonYou 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:buildingcustomfirst_name_and_last_namefirst_name_initial_and_last_nameanonymousfirst_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
Requests
GET /v3/buildings
Headers
Accept: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "577696285",
"type": "buildings",
"attributes": {
"name": "Kautzer-Hartmann-13",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"address_1": "316 O'Conner Brook",
"address_2": "Port Kieth, VA 51148-6766",
"city": "Port Kieth",
"state": "Virginia",
"zip_code": "51148-6766",
"phone_number": "(480) 760-6557 x8014",
"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": "Irulan 4",
"nfc": {
"uuid": "a146db64-2e10-4301-b4ec-6e5afc8e8df4"
}
},
"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"
}
}ListGET/v3/buildings
GET /v3/buildings/577696288
Requests
GET /v3/buildings/577696288
Headers
Accept: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "577696288",
"type": "buildings",
"attributes": {
"name": "Rath-Dare-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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"address_1": "2173 Kendrick Plaza",
"address_2": "South Pricilla, GA 34630",
"city": "South Pricilla",
"state": "Georgia",
"zip_code": "34630",
"phone_number": "684.883.4246 x45085",
"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": "Leto Atreides 5",
"nfc": {
"uuid": "8254af6a-95c1-4516-9f56-22bf63b5b59b"
}
},
"relationships": {
"building": {
"data": {
"id": "577696288",
"type": "buildings"
}
}
}
}
]
}GET /v3/buildings/577696291?include[]=key_lockers
Headers
Accept: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "577696291",
"type": "buildings",
"attributes": {
"name": "McKenzie Inc-19",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"address_1": "176 Barton Fall",
"address_2": "Endabury, AZ 76328",
"city": "Endabury",
"state": "Arizona",
"zip_code": "76328",
"phone_number": "(508) 150-0198 x53374",
"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": "Glossu \"Beast\" Rabban 6",
"nfc": {
"uuid": "e4d7e065-c4c4-4c7e-812b-475cf318a7f2"
}
},
"relationships": {
"building": {
"data": {
"id": "577696291",
"type": "buildings"
}
}
}
},
{
"id": "1",
"type": "key_lockers",
"attributes": {
"name": "Gaius Helen Mohiam 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
}
}
]
}PATCH /v3/buildings/577696295
Requests
PATCH /v3/buildings/577696295
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"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)"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"address_1": "154 Izola Land",
"address_2": "South Moiraburgh, GA 66761",
"city": "South Moiraburgh",
"state": "Georgia",
"zip_code": "66761",
"phone_number": "126-321-9638 x218",
"country": "us",
"qr_key_enabled": false,
"time_zone": "Eastern Time (US & Canada)",
"time_zone_offset": "-05: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+jsonBody
{
"data": {
"type": "buildings",
"id": "577696298",
"attributes": {
"address_1": "New Building Address"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "577696298",
"type": "buildings",
"attributes": {
"name": "Romaguera, Schuppe and Bahringer-26",
"building_type": "multi_family",
"display_name_strategy": "first_name_and_last_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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"address_1": "New Building Address",
"address_2": "Willettehaven, AZ 06130-3524",
"city": "Willettehaven",
"state": "Arizona",
"zip_code": "06130-3524",
"phone_number": "1-152-834-4247",
"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+jsonBody
{
"data": {
"type": "buildings",
"id": "577696301",
"attributes": {
"address_1": ""
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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+jsonBody
{
"data": {
"attributes": {
"remove_panel_logo": true
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "577696304",
"type": "buildings",
"attributes": {
"name": "Zieme-Conn-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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
"medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
},
"address_1": "25384 Anderson Ridges",
"address_2": "Purdymouth, UT 26455",
"city": "Purdymouth",
"state": "Utah",
"zip_code": "26455",
"phone_number": "1-829-791-1409 x89776",
"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": []
}
}
}
}Integrations ¶
Integrations
Allowed integrators:
webhook
Allowed config attributes for integrators:
- webhook
- url (String)
- method (String
getorpost)
Allowed binding resource types:
-
call -
door_release
GET /v3/buildings/1337/integrations
Requests
GET /v3/buildings/1337/integrations
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}ListGET/v3/buildings/{building_id}/integrations
URI Parameters
- building_id
number(required) Example: 1337
GET /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Requests
GET /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}
}ShowGET/v3/buildings/{building_id}/integrations/{id}
URI Parameters
- building_id
number(required) Example: 1337- id
string(required) Example: 79c9dc15-1bef-4ecc-956e-824be46901ce
POST /v3/buildings/1337/integrations
Requests
POST /v3/buildings/1337/integrations
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonBody
{
"data": {
"type": "integrations",
"attributes": {
"integrator": "webhook",
"configuration": {
"url": "http://localhost:666",
"method": "post"
},
"bindings": [
{
"actions": [
"create"
],
"resource_type": "call",
"resource_id": null
}
]
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}
}CreatePOST/v3/buildings/{building_id}/integrations
URI Parameters
- building_id
number(required) Example: 1337
PATCH /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Requests
PATCH /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonBody
{
"data": {
"type": "integrations",
"attributes": {
"integrator": "webhook",
"configuration": {
"url": "http://localhost:999",
"method": "get"
},
"bindings": [
{
"actions": [
"update",
"destroy"
],
"resource_type": "door_release",
"resource_id": "7"
}
]
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}
}UpdatePATCH/v3/buildings/{building_id}/integrations/{id}
URI Parameters
- 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
Requests
DELETE /v3/buildings/1337/integrations/79c9dc15-1bef-4ecc-956e-824be46901ce
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonResponses
This response has no content.
DeleteDELETE/v3/buildings/{building_id}/integrations/{id}
URI Parameters
- 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/06b73de8-28a3-4f0e-950b-3a354846f529/status
Requests
GET /v3/me/calls/06b73de8-28a3-4f0e-950b-3a354846f529/status
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "2",
"type": "call_statuses",
"attributes": {
"status": "initializing",
"multiple_devices": false,
"created_at": "2023-01-31T16:37:13Z"
},
"relationships": {
"call": {
"data": {
"id": "1",
"type": "calls"
}
}
}
},
"included": [
{
"id": "1",
"type": "calls",
"attributes": {
"guid": "06b73de8-28a3-4f0e-950b-3a354846f529",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"status": "initializing",
"display_status": "Initializing",
"panel_id": 708353671,
"panel_name": "Murbella 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+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"title": "Record not found",
"detail": "Requested record could not be found"
}
]
}Call StatusGET/v3/me/calls/{call_guid}/status
URI Parameters
- call_guid
string(required) Example: 06b73de8-28a3-4f0e-950b-3a354846f529
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
Requests
GET /v3/me/calls
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "5",
"type": "calls",
"attributes": {
"guid": "62a9b507-3bd7-4665-b419-3a729839901a",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"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": "8b453380-3a87-4723-87cc-7701fe20931e",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"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": "19ad42ca-d998-44b2-af07-20e215ace151",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"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"
}
}CallsGET/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
Requests
GET /v3/me/door_releases
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "6",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"call_guid": "29051720-10be-4ff8-b181-66d154363321",
"delivery_guid": "86c64424-86bd-4667-81b0-018a71a78aa1",
"name": "Alfonso Ondricka",
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb/small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium/small_picture.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z"
},
"relationships": {
"unit": {
"data": {
"id": "843107278",
"type": "units"
}
},
"user": {
"data": {
"id": "636166929",
"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": "5a2ab3ef-c5b8-447a-a084-f1709230c053",
"delivery_guid": "4964a0ac-6272-4cea-aa4d-06c4159dfada",
"name": "Ileen Trantow",
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb/small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium/small_picture.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z"
},
"relationships": {
"unit": {
"data": {
"id": "843107278",
"type": "units"
}
},
"user": {
"data": {
"id": "636166929",
"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": "05bb1e1b-aa37-47dc-88ee-69ce1f76c2eb",
"delivery_guid": "f17ee2e2-93e7-4f45-af6d-c6fe5a4d6096",
"name": "June West",
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/thumb/small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium/small_picture.jpg",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z"
},
"relationships": {
"unit": {
"data": {
"id": "843107278",
"type": "units"
}
},
"user": {
"data": {
"id": "636166929",
"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 ReleasesGET/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
Requests
GET /v3/me/messages
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "3",
"type": "messages",
"attributes": {
"message": null,
"voice": {
"url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/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"
}
}MessagesGET/v3/me/messages
Open Door ¶
POST /v3/me/open_door
Requests
POST /v3/me/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {},
"type": "open_door",
"relationships": {
"panel": {
"data": {
"type": "panel",
"id": 708353678
}
},
"unit": {
"data": {
"type": "unit",
"id": 843107288
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "1",
"type": "door_release_requests",
"attributes": {
"guid": "1b5e972e-11c9-4fc6-854b-3f268559ea49",
"created_at": "2023-01-31T16:37:17Z"
}
}
}POST /v3/me/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {},
"type": "open_door",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107290
}
},
"device": {
"data": {
"type": "keypads",
"id": 106694917
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "2",
"type": "door_release_requests",
"attributes": {
"guid": "640320bf-9381-480d-b116-cd39bbb62383",
"created_at": "2023-01-31T16:37:18Z"
}
}
}POST /v3/me/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {},
"type": "open_doors",
"relationships": {
"panels": {
"data": {
"type": "panels",
"id": "DOES_NOT_EXIST"
}
},
"unit": {
"data": {
"type": "unit",
"id": 843107293
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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 DoorPOST/v3/me/open_door
Tokens ¶
POST /v3/me/calls/twiliotest/token
Requests
POST /v3/me/calls/twiliotest/token
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"device_uuid": "test-123-test"
},
"type": "token",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"tokens": {
"twilio": "token-12345679-token"
}
}POST /v3/me/calls/twiliotest/token
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"device_uuid": "test-123-test"
},
"type": "token",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"tokens": {
"twilio": "token-12345679-token"
}
}POST /v3/me/calls/voiptest/token
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"device_uuid": "test-123-test"
},
"type": "token",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"error": "Bad Request",
"error_description": "Token was not generated"
}CreatePOST/v3/me/calls/{call_guid}/token
URI Parameters
- 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
Requests
GET /v3/me
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166937",
"type": "users",
"attributes": {
"name": "Eladia Simonis",
"first_name": "Eladia",
"last_name": "Simonis",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "38",
"email": "lester.predovic@adams.io",
"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+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166938",
"type": "users",
"attributes": {
"name": "Lola Gislason",
"first_name": "Lola",
"last_name": "Gislason",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "39",
"email": "hyon.spinka@sporer.co",
"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": "Olson Inc-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": "989 Nolan Port",
"address_2": "West Vince, RI 59088-7890",
"city": "West Vince",
"state": "Rhode Island",
"zip_code": "59088-7890",
"phone_number": "159.451.9957",
"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": "Leto Atreides 30",
"nfc": {
"uuid": "b86bbe17-2182-454e-9214-b96cab0d8496"
}
}
}
]
}ShowGET/v3/me
PUT /v3/me
Requests
PUT /v3/me
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "tenants",
"id": "636166939",
"attributes": {
"last_name": "Baker"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166939",
"type": "users",
"attributes": {
"name": "Gil Baker",
"first_name": "Gil",
"last_name": "Baker",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "40",
"email": "loida.okeefe@lehnerarmstrong.name",
"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+jsonBody
{
"data": {
"type": "tenants",
"id": "636166940",
"attributes": {
"last_name": ""
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"error": "Bad Request",
"error_description": "Last name can't be blank"
}UpdatePUT/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
Requests
GET /v3/devices?include=building
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": []
}ListGET/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:mobilepanelqr_keynfcvoip
-
door_release_type:visitordelivery
-
panel_user_type:defaultdoorman
GET /v3/door_releases
Requests
GET /v3/door_releases
Headers
Accept: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "32",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "doorman",
"call_guid": "849b86ec-8a09-413a-9ee6-6b255fe143eb",
"delivery_guid": "2c5c0a77-bdfe-469e-ac28-edcc80283dd8",
"name": "Enrique Ryan",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "31",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "doorman",
"call_guid": "26dd5ece-c02a-4ab6-820b-140e895dab71",
"delivery_guid": "4628585d-1d00-4a91-9712-4696436d445c",
"name": "Dr. Noah Collins",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "30",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "1c81fa12-ec60-430f-b6a8-94ef84d3f32f",
"delivery_guid": "5db7765f-ad81-4342-95ed-3e10d69d60ad",
"name": "Clyde Witting",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "29",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "b8551c19-3170-44d9-8bb3-e48fad23b1d5",
"delivery_guid": "c498dd8e-11b5-46a3-8d46-74bf4c730d82",
"name": "Jacinto Towne II",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "28",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "delivery",
"panel_user_type": "default",
"call_guid": "dec5b4f4-b54e-4c13-9e54-05f0021fc1a2",
"delivery_guid": "e1a76132-8651-4e21-99d6-6c1d29c4da79",
"name": "Mrs. Wilhelmina Corwin",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "27",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "delivery",
"panel_user_type": "default",
"call_guid": "d4e0aecf-4dd0-4d13-b593-2fe1a6771a58",
"delivery_guid": "61178955-c015-48be-94de-66c5fb8d89d1",
"name": "Kira Moore",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "26",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "35662d6d-f470-4eb7-8478-5ad18f40e11c",
"delivery_guid": "680c7dbe-6336-4266-93ec-1297f79d5cf0",
"name": "Ms. Gary Parisian",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "25",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "8ccaa70a-d51d-45da-b53e-7631e0882ebc",
"delivery_guid": "aa05a2ec-be45-4c19-9041-fc8e915a42f5",
"name": "Normand Schulist",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "24",
"type": "door_releases",
"attributes": {
"release_method": "qr_key",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "f024f0b4-944b-4817-a9a5-860c94598170",
"delivery_guid": "a179e493-89e7-4e99-97cc-67bcb30b9831",
"name": "Dallas Abshire",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "23",
"type": "door_releases",
"attributes": {
"release_method": "qr_key",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "a9353fd5-9846-431f-987d-37d64ab247f9",
"delivery_guid": "fb7b4e6d-257e-496e-84bd-cd3fee16ba5a",
"name": "Mr. Deshawn Reynolds",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "22",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "f11ae83c-3051-420a-b5fb-de8f0da74c01",
"delivery_guid": "12634a10-d2cf-44fa-8ef3-de3c42392b96",
"name": "Dorthy Davis",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "21",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "9d756382-1fd9-4665-a3a5-59241cff94c3",
"delivery_guid": "a324d0a6-e205-4225-ad22-c05c0772d35d",
"name": "Santos Deckow",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353701",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353701",
"type": "panels"
}
}
}
},
{
"id": "20",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "1c0edbd6-efbe-4dba-8b43-068442d4c9e4",
"delivery_guid": "17496bec-50f3-4c77-a50c-9db235893ca2",
"name": "Elias Buckridge Jr.",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"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": "4e72cfa1-571a-43eb-b5a4-b46e56980d48",
"delivery_guid": "da814dab-1425-42d0-ae5d-a58d160beca7",
"name": "Miss Edison Bernhard",
"created_at": "2023-01-31T16:35:41Z",
"logged_at": "2023-01-31T16:35:41Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107365",
"type": "units"
}
},
"user": {
"data": {
"id": "636166953",
"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"
}
}ListGET/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.
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).
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
Requests
POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:32+00:00",
"ends_at": "2023-02-02T16:37:27+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107336
}
},
"devices": {
"data": [
{
"type": "keypads",
"id": 106694918
}
]
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "15",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:32Z",
"ends_at": "2023-02-02T16:37:27Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-rcs244.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "442668",
"instructions_url": "http://user.butterflymx.test/public/rodriguez-breitenberg-and-nienow-95/virtual_keys/7/579ea567511224ea95ed15b54ab56cf7",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1jgizk9.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "304886",
"instructions_url": "http://user.butterflymx.test/public/rodriguez-breitenberg-and-nienow-95/virtual_keys/8/5e7fd7e225e80b2fca0c900a0b6a487c",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:34+00:00",
"ends_at": "2023-02-02T16:37:29+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 2,
"compartment": "H5"
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107338
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "16",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:34Z",
"ends_at": "2023-02-02T16:37:29Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-ko14pm.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "236685",
"instructions_url": "http://user.butterflymx.test/public/daniel-streich-and-rau-97/virtual_keys/9/bcca6f4248af940ac15d636857091c30",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-zab93a.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "585911",
"instructions_url": "http://user.butterflymx.test/public/daniel-streich-and-rau-97/virtual_keys/10/5c0a2fd19c78f4731440ec352a0d5089",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:35+00:00",
"ends_at": "2023-02-02T16:37:30+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 3,
"compartment": "any_when_used"
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107341
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "17",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:35Z",
"ends_at": "2023-02-02T16:37:30Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1e34pek.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "870644",
"instructions_url": "http://user.butterflymx.test/public/kling-connelly-and-kshlerin-100/virtual_keys/11/3609498288ae78c0e2ef00731bcd761c",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1rka2gm.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "166474",
"instructions_url": "http://user.butterflymx.test/public/kling-connelly-and-kshlerin-100/virtual_keys/12/2692634fc257bc2ca403647a8c692da6",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:37+00:00",
"ends_at": "2023-02-02T16:37:32+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 4,
"compartment_id": 106
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107344
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "18",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:37Z",
"ends_at": "2023-02-02T16:37:32Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1w4ktzf.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "806546",
"instructions_url": "http://user.butterflymx.test/public/muller-inc-103/virtual_keys/13/774f5c4ebe96a9f93c43114243c8a3b3",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-6rvw55.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "352925",
"instructions_url": "http://user.butterflymx.test/public/muller-inc-103/virtual_keys/14/53519c62f08a196e705322fc18afa9db",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:38+00:00",
"ends_at": "2023-02-02T16:37:33+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 5,
"compartment_id": 154,
"item_return_policy": "return"
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107347
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "19",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:38Z",
"ends_at": "2023-02-02T16:37:33Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1midei1.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "823433",
"instructions_url": "http://user.butterflymx.test/public/luettgen-inc-106/virtual_keys/15/3bc2dbde1d65498f92cccdfedcf779dd",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-162mq81.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "343118",
"instructions_url": "http://user.butterflymx.test/public/luettgen-inc-106/virtual_keys/16/90fe88a80ba61f037bb92a142c1015a0",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:40+00:00",
"ends_at": "2023-02-02T16:37:35+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 6,
"compartment_id": 187
},
"item_return_policy": "return"
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107350
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "20",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:40Z",
"ends_at": "2023-02-02T16:37:35Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1re34s8.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "693762",
"instructions_url": "http://user.butterflymx.test/public/grant-beahan-109/virtual_keys/17/a48add059e344e3330cf689e124b9df3",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1n9dmli.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "654065",
"instructions_url": "http://user.butterflymx.test/public/grant-beahan-109/virtual_keys/18/9d580643be7aa51401291f2274e5263e",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-01-31T16:37:40+00:00",
"ends_at": "2023-02-02T16:37:35+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166948
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "21",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-01-31T16:37:40Z",
"ends_at": "2023-02-02T16:37:35Z",
"time_from": "16:37",
"time_to": "16:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "19",
"type": "virtual_keys"
},
{
"id": "20",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1ohgw4b.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "870346",
"instructions_url": "http://user.butterflymx.test/public/hills-keebler-112/virtual_keys/19/1701c659c1ace6b8925187f47aff9381",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1hbil4v.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "062057",
"instructions_url": "http://user.butterflymx.test/public/hills-keebler-112/virtual_keys/20/b4743439ce4dd864ef9f36ec481d9f7e",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "",
"ends_at": "2023-02-02T16:37:36+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166949
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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 KeychainPOST/v3/keychains/custom
GET /v3/keychains
Requests
GET /v3/keychains
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "27",
"type": "keychains",
"attributes": {
"name": "Future Coordinator 19",
"weekdays": [],
"starts_at": "2023-01-31T16:37:46Z",
"ends_at": "2023-01-31T17:37:46Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "26",
"type": "keychains",
"attributes": {
"name": "Legal Engineer 18",
"weekdays": [],
"starts_at": "2023-01-31T16:37:46Z",
"ends_at": "2023-01-31T17:37:46Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "25",
"type": "keychains",
"attributes": {
"name": "Farming Orchestrator 17",
"weekdays": [],
"starts_at": "2023-01-31T16:37:46Z",
"ends_at": "2023-01-31T17:37:46Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"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+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "30",
"type": "keychains",
"attributes": {
"name": "Lead Government Representative 22",
"weekdays": [],
"starts_at": "2023-01-31T16:37:47Z",
"ends_at": "2023-01-31T17:37:47Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "29",
"type": "keychains",
"attributes": {
"name": "Marketing Officer 21",
"weekdays": [],
"starts_at": "2023-01-31T16:37:47Z",
"ends_at": "2023-01-31T17:37:47Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "28",
"type": "keychains",
"attributes": {
"name": "Central IT Manager 20",
"weekdays": [],
"starts_at": "2023-01-31T16:37:47Z",
"ends_at": "2023-01-31T17:37:47Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "24",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
}
],
"included": [
{
"id": "24",
"type": "virtual_keys",
"attributes": {
"name": "Winona Ferry",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1l3d8ls.png",
"email": "kali.schimmel@example.net",
"sms_number": "+12546226243",
"used_at": null,
"one_time_key_used_at": null,
"pin": "105439",
"instructions_url": "http://user.butterflymx.test/public/hodkiewicz-hammes-and-wolff-134/virtual_keys/24/23960c17904288e151ebf7e1d7f85ca9",
"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"
}
}ListGET/v3/keychains
GET /v3/keychains/31
Requests
GET /v3/keychains/31
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "31",
"type": "keychains",
"attributes": {
"name": "Dynamic Mining Agent 23",
"weekdays": [],
"starts_at": "2023-01-31T16:37:47Z",
"ends_at": "2023-01-31T17:37:47Z",
"time_from": "16:37",
"time_to": "17:37",
"kind": "custom",
"start_date": "2023-01-31",
"end_date": "2023-01-31",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "25",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
}
}DELETE /v3/keychains/32
Requests
DELETE /v3/keychains/32
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
This response has no content.
POST /v3/keychains/one_time
Requests
POST /v3/keychains/one_time
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "One-Time Key",
"starts_at": "2023-01-31T16:38:00+00:00",
"ends_at": "2023-02-02T16:37:55+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107410
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "33",
"type": "keychains",
"attributes": {
"name": "One-Time Key",
"weekdays": [],
"starts_at": "2023-01-31T16:38:00Z",
"ends_at": "2023-02-02T16:37:55Z",
"time_from": "16:38",
"time_to": "16:37",
"kind": "one_time",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-fl64xu.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "774606",
"instructions_url": "http://user.butterflymx.test/public/altenwerth-and-sons-157/virtual_keys/27/26e4704efddbf739f976728555c1670f",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-r9j3lh.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "754347",
"instructions_url": "http://user.butterflymx.test/public/altenwerth-and-sons-157/virtual_keys/28/ad06f18fe647edca0521392f49d4890f",
"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+jsonBody
{
"data": {
"attributes": {
"name": "One-Time Key",
"starts_at": "2023-01-31T16:38:01+00:00",
"ends_at": "2023-02-02T16:37:56+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166974
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "34",
"type": "keychains",
"attributes": {
"name": "One-Time Key",
"weekdays": [],
"starts_at": "2023-01-31T16:38:01Z",
"ends_at": "2023-02-02T16:37:56Z",
"time_from": "16:38",
"time_to": "16:37",
"kind": "one_time",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1sr586u.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "230196",
"instructions_url": "http://user.butterflymx.test/public/wunsch-lubowitz-and-smith-158/virtual_keys/29/bf4ceeca14384b94a262095b5e542510",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1qljfm5.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "011673",
"instructions_url": "http://user.butterflymx.test/public/wunsch-lubowitz-and-smith-158/virtual_keys/30/abbfe81ab305963f0d4c0e18f8e65241",
"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+jsonBody
{
"data": {
"attributes": {
"name": "One-Time Key",
"starts_at": "",
"ends_at": "2023-02-02T16:37:57+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166975
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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 KeychainPOST/v3/keychains/one_time
POST /v3/keychains/recurring
Requests
POST /v3/keychains/recurring
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Recurring Key",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167009,
"account_id": 110,
"first_name": "Chauncey",
"last_name": "Swift",
"created_at": "2023-01-31T16:38:03Z",
"updated_at": "2023-01-31T16:38:03Z",
"email_cache": "clair.halvorson@torpupton.info",
"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": 843107429
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "39",
"type": "keychains",
"attributes": {
"name": "Recurring Key",
"weekdays": [
"wed",
"sat"
],
"starts_at": "2023-01-31T11:20:00Z",
"ends_at": "2023-02-02T11:50:00Z",
"time_from": "11:20",
"time_to": "11:50",
"kind": "recurring",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-a9j15v.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "564173",
"instructions_url": "http://user.butterflymx.test/public/goodwin-group-172/virtual_keys/33/a5f79b2a4148284f7d903edc36be261a",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1pnp4oh.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "597825",
"instructions_url": "http://user.butterflymx.test/public/goodwin-group-172/virtual_keys/34/571f50c50a8a07126b6fc1c4e1817422",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Recurring Key",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167011,
"account_id": 112,
"first_name": "Caitlyn",
"last_name": "Hilll",
"created_at": "2023-01-31T16:38:04Z",
"updated_at": "2023-01-31T16:38:04Z",
"email_cache": "jeramy_rutherford@mclaughlin.net",
"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
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "40",
"type": "keychains",
"attributes": {
"name": "Recurring Key",
"weekdays": [
"wed",
"sat"
],
"starts_at": "2023-01-31T11:20:00Z",
"ends_at": "2023-02-02T11:50:00Z",
"time_from": "11:20",
"time_to": "11:50",
"kind": "recurring",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-14004t5.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "348197",
"instructions_url": "http://user.butterflymx.test/public/lesch-prosacco-173/virtual_keys/35/34c1f90755ee2bbf9ba586b28ea9c3e4",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-foztab.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "446182",
"instructions_url": "http://user.butterflymx.test/public/lesch-prosacco-173/virtual_keys/36/71c3c98a0a86d4915aa89e8f5055e86b",
"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+jsonBody
{
"data": {
"type": "keychains",
"attributes": {
"name": "Recurring Key",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167013,
"account_id": 114,
"first_name": "Edie",
"last_name": "Lang",
"created_at": "2023-01-31T16:38:06Z",
"updated_at": "2023-01-31T16:38:06Z",
"email_cache": "eveline_donnelly@herman.name",
"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": "708353712",
"type": "panels"
},
{
"id": "708353713",
"type": "panels"
}
]
},
"tenant": {
"data": {
"id": "636166986",
"type": "tenant"
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "41",
"type": "keychains",
"attributes": {
"name": "Recurring Key",
"weekdays": [
"wed",
"sat"
],
"starts_at": "2023-01-31T11:20:00Z",
"ends_at": "2023-02-02T11:50:00Z",
"time_from": "11:20",
"time_to": "11:50",
"kind": "recurring",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "37",
"type": "virtual_keys"
},
{
"id": "38",
"type": "virtual_keys"
}
]
},
"devices": {
"data": [
{
"id": "708353712",
"type": "panels"
},
{
"id": "708353713",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-1przr2c.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "403414",
"instructions_url": "http://user.butterflymx.test/public/kreiger-jones-174/virtual_keys/37/00053de6ebb1b09d5a1ea817cd0f61e4",
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-622vig.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "945556",
"instructions_url": "http://user.butterflymx.test/public/kreiger-jones-174/virtual_keys/38/33711fd6a2394d726da3241862a339a2",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "708353712",
"type": "panels",
"attributes": {
"name": "Shaddam Corrino IV 62",
"nfc": {
"uuid": "a7578e34-8d65-4aba-b963-5aa216d5abe0"
}
},
"relationships": {
"building": {
"data": {
"id": "577696436",
"type": "buildings"
}
}
}
},
{
"id": "708353713",
"type": "panels",
"attributes": {
"name": "Murbella 63",
"nfc": {
"uuid": "8039294b-3241-4c7b-96ff-7561449a70c1"
}
},
"relationships": {
"building": {
"data": {
"id": "577696436",
"type": "buildings"
}
}
}
}
]
}POST /v3/keychains/recurring
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "",
"start_date": "2023-01-31",
"end_date": "2023-02-02",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167015,
"account_id": 116,
"first_name": "Omar",
"last_name": "Corkery",
"created_at": "2023-01-31T16:38:08Z",
"updated_at": "2023-01-31T16:38:08Z",
"email_cache": "ginette.dickinson@rath.io",
"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
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/name"
},
"detail": "can't be blank"
}
]
}Create Recurring KeychainPOST/v3/keychains/recurring
Virtual Keys ¶
POST /v3/keychains/35/virtual_keys
Requests
POST /v3/keychains/35/virtual_keys
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Virtual Key",
"email": "test@example.com"
},
"type": "virtual_keys",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/original/qr_code_20230131-1061-tvyde.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "839277",
"instructions_url": "http://user.butterflymx.test/public/jacobson-llc-168/virtual_keys/31/d55e09f1f4aa9d1e7f919ee17057e12c",
"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+jsonBody
{
"data": {
"attributes": {
"name": "Virtual Key",
"sms_number": "DOES_NOT_EXIST"
},
"type": "virtual_keys",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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+jsonBody
{
"data": {
"attributes": {
"name": "Virtual Key",
"email": "test@example.com"
},
"type": "virtual_keys",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"title": "Record not found",
"detail": "Requested record could not be found"
}
]
}CreatePOST/v3/keychains/{keychain_id}/virtual_keys
URI Parameters
- keychain_id
number(required) Example: 35
DELETE /v3/keychains/38/virtual_keys/32
Requests
DELETE /v3/keychains/38/virtual_keys/32
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
This response has no content.
DeleteDELETE/v3/keychains/{keychain_id}/virtual_keys/{id}
URI Parameters
- keychain_id
number(required) Example: 38- id
number(required) Example: 32
Notifications ¶
Call Accepted ¶
POST /v3/notifications/call_accepted
Requests
POST /v3/notifications/call_accepted
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353702",
"attributes": {
"panel_id": 708353702,
"video": true,
"audio": false,
"call_guid": "e00cb0cc-693f-47e4-b528-d719c30afa15"
}
}
}Responses
This response has no content.
POST /v3/notifications/call_accepted
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353703",
"attributes": {
"panel_id": "NOT_EXIST",
"video": true,
"audio": false,
"call_guid": "ee76e86c-9b8d-475c-b981-2130d67a78fa"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/panel_id"
},
"detail": "No panel with that ID"
}
]
}Call AcceptedPOST/v3/notifications/call_accepted
Call Ended ¶
POST /v3/notifications/call_ended
Requests
POST /v3/notifications/call_ended
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353704",
"attributes": {
"panel_id": 708353704,
"call_guid": "8c92c3ad-6d08-4128-a79a-b152fc80fbd9"
}
}
}Responses
This response has no content.
POST /v3/notifications/call_ended
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353705",
"attributes": {
"panel_id": "NOT_EXIST",
"call_guid": "6274014e-cf7d-491b-97c0-2d258e4e355c"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/panel_id"
},
"detail": "No panel with that ID"
}
]
}Call EndedPOST/v3/notifications/call_ended
Is Active ¶
POST /v3/notifications/is_active
Requests
POST /v3/notifications/is_active
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353706",
"attributes": {
"panel_id": 708353706,
"call_guid": "0474e8d7-9466-458c-95b9-dd145c46c3d9"
}
}
}Responses
This response has no content.
POST /v3/notifications/is_active
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353707",
"attributes": {
"panel_id": "NOT_EXIST",
"call_guid": "d42d067f-e413-4eee-a418-290cc033813d"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/panel_id"
},
"detail": "No panel with that ID"
}
]
}Is ActivePOST/v3/notifications/is_active
Open Door ¶
POST /v3/notifications/open_door
Requests
POST /v3/notifications/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353708",
"attributes": {
"panel_id": 708353708,
"call_guid": "52cdc2f5-0630-49cb-9da2-603cec7acdd2"
}
}
}Responses
This response has no content.
POST /v3/notifications/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353709",
"attributes": {
"panel_id": "NOT_EXIST",
"call_guid": "b0f32069-37b5-418f-9ec1-9966db32ab63"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/panel_id"
},
"detail": "No panel with that ID"
}
]
}Open DoorPOST/v3/notifications/open_door
Toggle Camera ¶
POST /v3/notifications/toggle_camera
Requests
POST /v3/notifications/toggle_camera
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353710",
"attributes": {
"panel_id": 708353710,
"video": true,
"audio": false,
"call_guid": "56d27d09-df81-4969-8b6e-2ad887772843"
}
}
}Responses
This response has no content.
POST /v3/notifications/toggle_camera
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "notifications",
"id": "708353711",
"attributes": {
"panel_id": "NOT_EXIST",
"video": true,
"audio": false,
"call_guid": "c4e381ba-eeeb-430d-a704-1681dbb6fd78"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/panel_id"
},
"detail": "No panel with that ID"
}
]
}Toggle CameraPOST/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
Requests
POST /v3/pins/combine
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "pins",
"id": "636166976",
"attributes": {}
}
}Responses
This response has no content.
CombinePOST/v3/pins/combine
GET /v3/pins/636166977
Requests
GET /v3/pins/636166977
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166977",
"type": "pins",
"attributes": {
"code": "5834",
"unique_code": null
}
}
}PUT /v3/pins
Requests
PUT /v3/pins
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "pins",
"id": "636166978",
"attributes": {
"code": "0854",
"unique_code": "085436"
}
}
}Responses
This response has no content.
PUT /v3/pins
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "pins",
"id": "636166979",
"attributes": {
"code": ""
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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)"
}
]
}SetPUT/v3/pins
Tenants ¶
Integrations ¶
Integrations
Allowed integrators:
webhook
Allowed config attributes for integrators:
- webhook
- url (String)
- method (String
getorpost)
Allowed binding resource types:
-
call -
door_release
GET /v3/tenants/2262/integrations
Requests
GET /v3/tenants/2262/integrations
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}GET /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Requests
GET /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}
}ShowGET/v3/tenants/{tenant_id}/integrations/{id}
URI Parameters
- tenant_id
number(required) Example: 2262- id
string(required) Example: bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
POST /v3/tenants/2262/integrations
Requests
POST /v3/tenants/2262/integrations
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonBody
{
"data": {
"type": "integrations",
"attributes": {
"integrator": "webhook",
"configuration": {
"url": "http://localhost:666",
"method": "post"
},
"bindings": [
{
"actions": [
"create"
],
"resource_type": "call",
"resource_id": null
}
]
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}
}CreatePOST/v3/tenants/{tenant_id}/integrations
URI Parameters
- tenant_id
number(required) Example: 2262
PATCH /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Requests
PATCH /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonBody
{
"data": {
"type": "integrations",
"attributes": {
"integrator": "webhook",
"configuration": {
"url": "http://localhost:999",
"method": "get"
},
"bindings": [
{
"actions": [
"update",
"destroy"
],
"resource_type": "door_release",
"resource_id": "7"
}
]
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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"
}
}
}UpdatePATCH/v3/tenants/{tenant_id}/integrations/{id}
URI Parameters
- 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
Requests
DELETE /v3/tenants/2262/integrations/bb7b0ec9-8b2f-46c4-a1c7-4bf439ca4c70
Headers
Accept: application/vnd.api+json
Content-Type: application/jsonResponses
This response has no content.
DeleteDELETE/v3/tenants/{tenant_id}/integrations/{id}
URI Parameters
- 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) - inISO 8601format e.g.2017-12-27T11:03:50Z -
inactive_at(DateTime) -
pin(String) -
directory_message(String) -
display_name_strategy(String), one of the allowed values:buildingcustomfirst_name_and_last_namefirst_name_initial_and_last_nameanonymousfirst_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_nameandlast_namewill 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:buildingcustomfirst_name_and_last_namefirst_name_initial_and_last_nameanonymousfirst_name_and_last_name_initial
GET /v3/tenants
Requests
GET /v3/tenants
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "636166991",
"type": "tenants",
"attributes": {
"active_at": "2023-01-31T16:38:09Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Government Agent",
"display_name": "Freeman Labadie",
"display_name_strategy": "building",
"display_first_name": "Dr. Debbi Bartell",
"display_last_name": "Gwenda Sporer",
"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": "843107439",
"type": "units"
}
},
"user": {
"data": {
"id": "636167022",
"type": "users"
}
}
}
},
{
"id": "636166990",
"type": "tenants",
"attributes": {
"active_at": "2023-01-31T16:38:09Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Sales Engineer",
"display_name": "Mayra Larkin MD",
"display_name_strategy": "building",
"display_first_name": "Kum Schiller",
"display_last_name": "Minh Harber",
"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": "843107439",
"type": "units"
}
},
"user": {
"data": {
"id": "636167021",
"type": "users"
}
}
}
},
{
"id": "636166989",
"type": "tenants",
"attributes": {
"active_at": "2023-01-31T16:38:09Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Customer Administration Officer",
"display_name": "Barrett Blick",
"display_name_strategy": "building",
"display_first_name": "Dion Dooley",
"display_last_name": "Carmine Sanford",
"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": "843107439",
"type": "units"
}
},
"user": {
"data": {
"id": "636167020",
"type": "users"
}
}
}
}
],
"included": [
{
"id": "636167022",
"type": "users",
"attributes": {
"name": "Cornell Willms",
"first_name": "Cornell",
"last_name": "Willms",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "123",
"registration_status": "registered",
"email": "deangelo@haagskiles.com",
"sms_phone_number": null,
"phone_number": null
}
},
{
"id": "636167021",
"type": "users",
"attributes": {
"name": "Ahmad Yundt",
"first_name": "Ahmad",
"last_name": "Yundt",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "122",
"registration_status": "registered",
"email": "abigail.shields@zemlak.biz",
"sms_phone_number": null,
"phone_number": null
}
},
{
"id": "636167020",
"type": "users",
"attributes": {
"name": "Ira Bahringer",
"first_name": "Ira",
"last_name": "Bahringer",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "121",
"registration_status": "registered",
"email": "perry.breitenberg@schmitt.info",
"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"
}
}ListGET/v3/tenants
GET /v3/tenants/636166992
Requests
GET /v3/tenants/636166992
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166992",
"type": "tenants",
"attributes": {
"active_at": "2023-01-31T16:38:09Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Senior Associate",
"display_name": "Diamond Klein II",
"display_name_strategy": "building",
"display_first_name": "Ronald Willms",
"display_last_name": "Hwa Mayert",
"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": "843107441",
"type": "units"
}
},
"user": {
"data": {
"id": "636167024",
"type": "users"
}
}
}
},
"included": [
{
"id": "636167024",
"type": "users",
"attributes": {
"name": "Ahmad Cremin",
"first_name": "Ahmad",
"last_name": "Cremin",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "125",
"registration_status": "registered",
"email": "tommy.littel@kulaswindler.io",
"sms_phone_number": null,
"phone_number": null
}
}
]
}POST /v3/tenants
Requests
POST /v3/tenants
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"unit_id": 843107443,
"email": "carlo_hudson@towne.info",
"active_at": "2023-01-31T16:38:10Z"
},
"type": "tenants",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166993",
"type": "tenants",
"attributes": {
"active_at": "2023-01-31T16:38:10Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": null,
"display_name": "J. Waelchi",
"display_name_strategy": "building",
"display_first_name": "J.",
"display_last_name": "Waelchi",
"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": "843107443",
"type": "units"
}
},
"user": {
"data": {
"id": "636167026",
"type": "users"
}
}
}
}
}POST /v3/tenants
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"unit_id": 843107445,
"email": "",
"first_name": "",
"last_name": "User",
"active_at": "2023-01-31T16:38:10Z"
},
"type": "tenants",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/user"
},
"detail": "must exist"
},
{
"source": {
"pointer": "/data/attributes/user"
},
"detail": "can't be blank"
}
]
}CreatePOST/v3/tenants
PATCH /v3/tenants/636166994
Requests
PATCH /v3/tenants/636166994
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "tenants",
"id": "636166994",
"attributes": {
"do_not_disturb": true,
"user_panel_config": {
"pin_enabled": true
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166994",
"type": "tenants",
"attributes": {
"active_at": "2023-01-31T16:38:11Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Administration Planner",
"display_name": "Margret Haley",
"display_name_strategy": "building",
"display_first_name": "Cleta Rosenbaum DDS",
"display_last_name": "Javier Wisoky",
"display_only_on_search": false,
"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": "843107447",
"type": "units"
}
},
"user": {
"data": {
"id": "636167030",
"type": "users"
}
}
}
}
}PATCH /v3/tenants/636166995
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "tenants",
"id": "636166995",
"attributes": {
"display_name_strategy": ""
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/user_panel_config.display_name_strategy"
},
"detail": "can't be blank"
}
]
}DELETE /v3/tenants/636166996
Requests
DELETE /v3/tenants/636166996
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
This response has no content.
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/reichert-stamm-187/tour_schedules
Requests
GET /v3/tours/reichert-stamm-187/tour_schedules
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "577696449",
"type": "buildings",
"attributes": {
"handle": "reichert-stamm-187",
"name": "Reichert-Stamm-187",
"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": "897 Ulysses Cliffs",
"address_2": "Medhurstshire, FL 93990-6755",
"city": "Medhurstshire",
"state": "Florida",
"zip_code": "93990-6755",
"phone_number": "284-936-7368 x735"
},
"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
}
}
}ListGET/v3/tours/{building_handle}/tour_schedules
URI Parameters
- building_handle
string(required) Example: reichert-stamm-187
POST /v3/tours/monahan-inc-189/tour_schedules
Requests
POST /v3/tours/monahan-inc-189/tour_schedules
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Monahan Inc-189 Tour",
"email": "tour@example.com",
"phone_number": "(555) 555-1234",
"starts_at": "2020-12-14T12:00:00Z"
},
"type": "tour_schedules",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "10",
"type": "tour_schedules",
"attributes": {
"name": "Monahan Inc-189 Tour",
"email": "tour@example.com",
"starts_at": "2020-12-14T12:00:00Z",
"ends_at": "2020-12-14T13:00:00Z",
"uuid": "94d01112-13da-48c5-acbb-7fff83da3ae2",
"status": "confirmed",
"qr_key_public_url": "http://user.butterflymx.test/public/monahan-inc-189/virtual_keys/39/400b26c03fd86596d6abce35455d0d1c",
"pin": "947810",
"qr_key_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium/qr_code_20201214-1061-1afqe7h.png",
"phone_number": "(555) 555-1234",
"building_handle": "monahan-inc-189",
"building_name": "Monahan Inc-189",
"building_address": {
"country": "us",
"address_1": "646 Mueller Fort",
"address_2": "South Elba, WV 62252-9360",
"city": "South Elba",
"state": "West Virginia",
"zip_code": "62252-9360",
"phone_number": "1-456-204-0564"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/94d01112-13da-48c5-acbb-7fff83da3ae2",
"keychains": [],
"key_locker_in_use": false
}
}
}POST /v3/tours/kuvalis-koelpin-191/tour_schedules
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Kuvalis-Koelpin-191 Tour ",
"email": "tour@example.com",
"starts_at": "2020-12-15T11:00:00Z"
},
"type": "tour_schedules",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/starts_at"
},
"detail": "is not available, outside availability hours"
}
]
}CreatePOST/v3/tours/{building_handle}/tour_schedules
URI Parameters
- building_handle
string(required) Example: monahan-inc-189
GET /v3/tours/c96c917d-45fa-4b0e-9d95-61440f4a1cb4
Requests
GET /v3/tours/c96c917d-45fa-4b0e-9d95-61440f4a1cb4
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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": "c96c917d-45fa-4b0e-9d95-61440f4a1cb4",
"status": "confirmed",
"qr_key_public_url": null,
"pin": null,
"qr_key_image_url": null,
"phone_number": "(941) 131-5013 x9055",
"building_handle": "nolan-graham-and-walker-193",
"building_name": "Nolan, Graham and Walker-193",
"building_address": {
"country": "us",
"address_1": "646 Irma Crescent",
"address_2": "Madeleneport, WY 58982-3326",
"city": "Madeleneport",
"state": "Wyoming",
"zip_code": "58982-3326",
"phone_number": "494-385-9942 x47971"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/c96c917d-45fa-4b0e-9d95-61440f4a1cb4",
"keychains": [],
"key_locker_in_use": false
}
}
}ShowGET/v3/tours/{uuid}
URI Parameters
- uuid
string(required) Example: c96c917d-45fa-4b0e-9d95-61440f4a1cb4
PATCH /v3/tours/a8806e36-0f04-457a-9cef-e7fb129a7a1f
Requests
PATCH /v3/tours/a8806e36-0f04-457a-9cef-e7fb129a7a1f
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "tour_schedules",
"id": "12",
"attributes": {
"starts_at": "2020-12-16T12:00:00Z"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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": "a8806e36-0f04-457a-9cef-e7fb129a7a1f",
"status": "rescheduled",
"qr_key_public_url": "http://user.butterflymx.test/public/beatty-bergnaum-and-medhurst-195/virtual_keys/40/b2e1bee9638cc3b5d17481f6e2fa046f",
"pin": "075428",
"qr_key_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1675182942-dba516f92566c62ee65e7fcce5c86ad9/store/medium/qr_code_20201214-1061-1ihzg9u.png",
"phone_number": "1-406-060-4997 x770",
"building_handle": "beatty-bergnaum-and-medhurst-195",
"building_name": "Beatty, Bergnaum and Medhurst-195",
"building_address": {
"country": "us",
"address_1": "413 Kindra Circle",
"address_2": "Lake Thomasine, GA 17427-8876",
"city": "Lake Thomasine",
"state": "Georgia",
"zip_code": "17427-8876",
"phone_number": "1-690-522-2700 x5101"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/a8806e36-0f04-457a-9cef-e7fb129a7a1f",
"keychains": [],
"key_locker_in_use": false
}
}
}UpdatePATCH/v3/tours/{uuid}
URI Parameters
- uuid
string(required) Example: a8806e36-0f04-457a-9cef-e7fb129a7a1f
DELETE /v3/tours/0a157f07-cdeb-4c61-84f3-0d25b183f0a3
Requests
DELETE /v3/tours/0a157f07-cdeb-4c61-84f3-0d25b183f0a3
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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": "0a157f07-cdeb-4c61-84f3-0d25b183f0a3",
"status": "cancelled",
"qr_key_public_url": null,
"pin": null,
"qr_key_image_url": null,
"phone_number": "261-353-9197 x9916",
"building_handle": "beier-erdman-197",
"building_name": "Beier-Erdman-197",
"building_address": {
"country": "us",
"address_1": "6585 Oliver Glens",
"address_2": "Reyport, MS 32050-7706",
"city": "Reyport",
"state": "Mississippi",
"zip_code": "32050-7706",
"phone_number": "574.480.4739"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/0a157f07-cdeb-4c61-84f3-0d25b183f0a3",
"keychains": [],
"key_locker_in_use": false
}
}
}DeleteDELETE/v3/tours/{uuid}
URI Parameters
- uuid
string(required) Example: 0a157f07-cdeb-4c61-84f3-0d25b183f0a3
Units ¶
Units ¶
Unit creation
- When creating a unit, a
building_idneeds 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:residentialcommercial
GET /v3/units/843107472
Requests
GET /v3/units/843107472
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "843107472",
"type": "units",
"attributes": {
"kind": "residential",
"label": "56056",
"floor_number": 56
},
"relationships": {
"building": {
"data": {
"id": "577696461",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
}GET /v3/units
Requests
GET /v3/units
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "843107476",
"type": "units",
"attributes": {
"kind": "residential",
"label": "59059",
"floor_number": 59
},
"relationships": {
"building": {
"data": {
"id": "577696463",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107475",
"type": "units",
"attributes": {
"kind": "residential",
"label": "58058",
"floor_number": 58
},
"relationships": {
"building": {
"data": {
"id": "577696463",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107474",
"type": "units",
"attributes": {
"kind": "residential",
"label": "57057",
"floor_number": 57
},
"relationships": {
"building": {
"data": {
"id": "577696463",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107473",
"type": "units",
"attributes": {
"kind": "residential",
"label": "00",
"floor_number": 0
},
"relationships": {
"building": {
"data": {
"id": "577696463",
"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+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "843107480",
"type": "units",
"attributes": {
"kind": "residential",
"label": "62062",
"floor_number": 62
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107479",
"type": "units",
"attributes": {
"kind": "residential",
"label": "61061",
"floor_number": 61
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107478",
"type": "units",
"attributes": {
"kind": "residential",
"label": "60060",
"floor_number": 60
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107477",
"type": "units",
"attributes": {
"kind": "residential",
"label": "00",
"floor_number": 0
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
],
"included": [
{
"id": "577696464",
"type": "buildings",
"attributes": {
"name": "Denesik, Nienow and Murphy-202",
"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": "/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": "67888 Schowalter Vista",
"address_2": "New Juliashire, NH 43868-2349",
"city": "New Juliashire",
"state": "New Hampshire",
"zip_code": "43868-2349",
"phone_number": "868-536-9986 x1820",
"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"
}
}ListGET/v3/units
POST /v3/buildings/577696465/units
Requests
POST /v3/buildings/577696465/units
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"kind": "residential",
"label": "foo",
"floor_number": 11
},
"type": "units",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "843107482",
"type": "units",
"attributes": {
"kind": "residential",
"label": "foo",
"floor_number": 11
},
"relationships": {
"building": {
"data": {
"id": "577696465",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
}POST /v3/buildings/577696466/units
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "units",
"attributes": {
"kind": "residential"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"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+jsonBody
{
"data": {
"type": "units",
"attributes": {
"kind": "residential",
"label": "foo",
"floor_number": 11
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"title": "Record not found",
"detail": "Requested record could not be found"
}
]
}CreatePOST/v3/buildings/{building_id}/units
URI Parameters
- building_id
number(required) Example: 577696465
PUT /v3/units/843107487
Requests
PUT /v3/units/843107487
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "units",
"attributes": {
"kind": "residential",
"label": "New Label",
"floor_number": 11,
"building_id": 577696468
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "843107487",
"type": "units",
"attributes": {
"kind": "residential",
"label": "New Label",
"floor_number": 11
},
"relationships": {
"building": {
"data": {
"id": "577696468",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
}PUT /v3/units/843107490
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "units",
"attributes": {
"label": ""
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"errors": [
{
"source": {
"pointer": "/data/attributes/label"
},
"detail": "can't be blank"
}
]
}DELETE /v3/units/843107493
Requests
DELETE /v3/units/843107493
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
This response has no content.
Generated by aglio on 31 Jan 2023