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": "Bruen-Collins-13",
"building_type": "multi_family",
"display_name_strategy": "first_name_initial_and_last_name",
"nfc_enabled": false,
"send_panel_status_report": false,
"mobile_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"address_1": "4998 Emmerich Land",
"address_2": "East Isiahtown, KS 26004",
"city": "East Isiahtown",
"state": "Kansas",
"zip_code": "26004",
"phone_number": "951-071-3650 x291",
"country": "us",
"qr_key_enabled": true,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"delivery_pass_enabled": true,
"door_release_pin": true,
"open_door_button_enabled": true
},
"relationships": {
"panels": {
"data": [
{
"id": "708353664",
"type": "panels"
}
]
},
"key_lockers": {
"data": []
}
}
}
],
"included": [
{
"id": "708353664",
"type": "panels",
"attributes": {
"name": "Edric 4",
"nfc": {
"uuid": "b88a1c2a-1e57-4081-9b98-6854ff137fd8"
}
},
"relationships": {
"building": {
"data": {
"id": "577696285",
"type": "buildings"
}
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}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": "Kovacek, Tillman and Renner-16",
"building_type": "multi_family",
"display_name_strategy": "last_name_and_first_name_initial",
"nfc_enabled": false,
"send_panel_status_report": false,
"mobile_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"address_1": "4209 Eric Streets",
"address_2": "North Raestad, GA 60840",
"city": "North Raestad",
"state": "Georgia",
"zip_code": "60840",
"phone_number": "1-200-336-5925 x08198",
"country": "us",
"qr_key_enabled": true,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"delivery_pass_enabled": true,
"door_release_pin": true,
"open_door_button_enabled": true
},
"relationships": {
"panels": {
"data": [
{
"id": "708353665",
"type": "panels"
}
]
},
"key_lockers": {
"data": []
}
}
},
"included": [
{
"id": "708353665",
"type": "panels",
"attributes": {
"name": "Nayla 5",
"nfc": {
"uuid": "8dc3ce6b-1e01-481b-9c09-921e090ac323"
}
},
"relationships": {
"building": {
"data": {
"id": "577696288",
"type": "buildings"
}
}
}
}
]
}GET /v3/buildings/577696291?include[]=key_lockers
Headers
Accept: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "577696291",
"type": "buildings",
"attributes": {
"name": "Cummerata-Hayes-19",
"building_type": "multi_family",
"display_name_strategy": "first_name_initial_and_last_name",
"nfc_enabled": false,
"send_panel_status_report": false,
"mobile_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"address_1": "34540 Tanner Lane",
"address_2": "New Lennychester, PA 69498-3142",
"city": "New Lennychester",
"state": "Pennsylvania",
"zip_code": "69498-3142",
"phone_number": "(518) 383-2557 x6771",
"country": "us",
"qr_key_enabled": true,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"delivery_pass_enabled": true,
"door_release_pin": true,
"open_door_button_enabled": true
},
"relationships": {
"panels": {
"data": [
{
"id": "708353666",
"type": "panels"
}
]
},
"key_lockers": {
"data": [
{
"id": "1",
"type": "key_lockers"
}
]
}
}
},
"included": [
{
"id": "708353666",
"type": "panels",
"attributes": {
"name": "Shadout Mapes 6",
"nfc": {
"uuid": "2ded2f2f-6ec5-4460-80eb-b8d9a8d10251"
}
},
"relationships": {
"building": {
"data": {
"id": "577696291",
"type": "buildings"
}
}
}
},
{
"id": "1",
"type": "key_lockers",
"attributes": {
"name": "Chani 7"
},
"relationships": {
"building": {
"data": {
"id": "577696291",
"type": "buildings"
}
},
"compartments": {
"data": [
{
"id": "1",
"type": "key_locker_compartments"
},
{
"id": "2",
"type": "key_locker_compartments"
},
{
"id": "3",
"type": "key_locker_compartments"
},
{
"id": "4",
"type": "key_locker_compartments"
},
{
"id": "5",
"type": "key_locker_compartments"
},
{
"id": "6",
"type": "key_locker_compartments"
},
{
"id": "7",
"type": "key_locker_compartments"
},
{
"id": "8",
"type": "key_locker_compartments"
},
{
"id": "9",
"type": "key_locker_compartments"
},
{
"id": "10",
"type": "key_locker_compartments"
},
{
"id": "11",
"type": "key_locker_compartments"
},
{
"id": "12",
"type": "key_locker_compartments"
},
{
"id": "13",
"type": "key_locker_compartments"
},
{
"id": "14",
"type": "key_locker_compartments"
},
{
"id": "15",
"type": "key_locker_compartments"
},
{
"id": "16",
"type": "key_locker_compartments"
},
{
"id": "17",
"type": "key_locker_compartments"
},
{
"id": "18",
"type": "key_locker_compartments"
},
{
"id": "19",
"type": "key_locker_compartments"
},
{
"id": "20",
"type": "key_locker_compartments"
},
{
"id": "21",
"type": "key_locker_compartments"
},
{
"id": "22",
"type": "key_locker_compartments"
},
{
"id": "23",
"type": "key_locker_compartments"
},
{
"id": "24",
"type": "key_locker_compartments"
},
{
"id": "25",
"type": "key_locker_compartments"
},
{
"id": "26",
"type": "key_locker_compartments"
},
{
"id": "27",
"type": "key_locker_compartments"
},
{
"id": "28",
"type": "key_locker_compartments"
},
{
"id": "29",
"type": "key_locker_compartments"
},
{
"id": "30",
"type": "key_locker_compartments"
},
{
"id": "31",
"type": "key_locker_compartments"
},
{
"id": "32",
"type": "key_locker_compartments"
},
{
"id": "33",
"type": "key_locker_compartments"
},
{
"id": "34",
"type": "key_locker_compartments"
}
]
}
}
},
{
"id": "1",
"type": "key_locker_compartments",
"attributes": {
"cell": "A1",
"open": false,
"full": false
}
},
{
"id": "2",
"type": "key_locker_compartments",
"attributes": {
"cell": "B1",
"open": false,
"full": false
}
},
{
"id": "3",
"type": "key_locker_compartments",
"attributes": {
"cell": "C1",
"open": false,
"full": false
}
},
{
"id": "4",
"type": "key_locker_compartments",
"attributes": {
"cell": "D1",
"open": false,
"full": false
}
},
{
"id": "5",
"type": "key_locker_compartments",
"attributes": {
"cell": "E1",
"open": false,
"full": false
}
},
{
"id": "6",
"type": "key_locker_compartments",
"attributes": {
"cell": "F1",
"open": false,
"full": false
}
},
{
"id": "7",
"type": "key_locker_compartments",
"attributes": {
"cell": "G1",
"open": false,
"full": false
}
},
{
"id": "8",
"type": "key_locker_compartments",
"attributes": {
"cell": "H1",
"open": false,
"full": false
}
},
{
"id": "9",
"type": "key_locker_compartments",
"attributes": {
"cell": "A2",
"open": false,
"full": false
}
},
{
"id": "10",
"type": "key_locker_compartments",
"attributes": {
"cell": "B2",
"open": false,
"full": false
}
},
{
"id": "11",
"type": "key_locker_compartments",
"attributes": {
"cell": "C2",
"open": false,
"full": false
}
},
{
"id": "12",
"type": "key_locker_compartments",
"attributes": {
"cell": "D2",
"open": false,
"full": false
}
},
{
"id": "13",
"type": "key_locker_compartments",
"attributes": {
"cell": "E2",
"open": false,
"full": false
}
},
{
"id": "14",
"type": "key_locker_compartments",
"attributes": {
"cell": "F2",
"open": false,
"full": false
}
},
{
"id": "15",
"type": "key_locker_compartments",
"attributes": {
"cell": "G2",
"open": false,
"full": false
}
},
{
"id": "16",
"type": "key_locker_compartments",
"attributes": {
"cell": "H2",
"open": false,
"full": false
}
},
{
"id": "17",
"type": "key_locker_compartments",
"attributes": {
"cell": "A3",
"open": false,
"full": false
}
},
{
"id": "18",
"type": "key_locker_compartments",
"attributes": {
"cell": "B3",
"open": false,
"full": false
}
},
{
"id": "19",
"type": "key_locker_compartments",
"attributes": {
"cell": "C3",
"open": false,
"full": false
}
},
{
"id": "20",
"type": "key_locker_compartments",
"attributes": {
"cell": "F3",
"open": false,
"full": false
}
},
{
"id": "21",
"type": "key_locker_compartments",
"attributes": {
"cell": "G3",
"open": false,
"full": false
}
},
{
"id": "22",
"type": "key_locker_compartments",
"attributes": {
"cell": "H3",
"open": false,
"full": false
}
},
{
"id": "23",
"type": "key_locker_compartments",
"attributes": {
"cell": "A4",
"open": false,
"full": false
}
},
{
"id": "24",
"type": "key_locker_compartments",
"attributes": {
"cell": "B4",
"open": false,
"full": false
}
},
{
"id": "25",
"type": "key_locker_compartments",
"attributes": {
"cell": "C4",
"open": false,
"full": false
}
},
{
"id": "26",
"type": "key_locker_compartments",
"attributes": {
"cell": "F4",
"open": false,
"full": false
}
},
{
"id": "27",
"type": "key_locker_compartments",
"attributes": {
"cell": "G4",
"open": false,
"full": false
}
},
{
"id": "28",
"type": "key_locker_compartments",
"attributes": {
"cell": "H4",
"open": false,
"full": false
}
},
{
"id": "29",
"type": "key_locker_compartments",
"attributes": {
"cell": "A5",
"open": false,
"full": false
}
},
{
"id": "30",
"type": "key_locker_compartments",
"attributes": {
"cell": "B5",
"open": false,
"full": false
}
},
{
"id": "31",
"type": "key_locker_compartments",
"attributes": {
"cell": "C5",
"open": false,
"full": false
}
},
{
"id": "32",
"type": "key_locker_compartments",
"attributes": {
"cell": "F5",
"open": false,
"full": false
}
},
{
"id": "33",
"type": "key_locker_compartments",
"attributes": {
"cell": "G5",
"open": false,
"full": false
}
},
{
"id": "34",
"type": "key_locker_compartments",
"attributes": {
"cell": "H5",
"open": false,
"full": false
}
}
]
}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-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"address_1": "99237 Bradtke Canyon",
"address_2": "Lonborough, SC 14873-3549",
"city": "Lonborough",
"state": "South Carolina",
"zip_code": "14873-3549",
"phone_number": "1-193-674-8250 x82170",
"country": "us",
"qr_key_enabled": false,
"time_zone": "Eastern Time (US & Canada)",
"time_zone_offset": "-04:00",
"delivery_pass_enabled": true,
"door_release_pin": false,
"open_door_button_enabled": true
},
"relationships": {
"panels": {
"data": [
{
"id": "708353667",
"type": "panels"
}
]
},
"key_lockers": {
"data": []
}
}
}
}PATCH /v3/buildings/577696298
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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": "Howe-Cremin-26",
"building_type": "multi_family",
"display_name_strategy": "last_name_and_first_name",
"nfc_enabled": false,
"send_panel_status_report": false,
"mobile_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"address_1": "New Building Address",
"address_2": "North Sherlene, NY 05889-5889",
"city": "North Sherlene",
"state": "New York",
"zip_code": "05889-5889",
"phone_number": "505-024-6212",
"country": "us",
"qr_key_enabled": true,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"delivery_pass_enabled": true,
"door_release_pin": true,
"open_door_button_enabled": true
},
"relationships": {
"panels": {
"data": [
{
"id": "708353668",
"type": "panels"
}
]
},
"key_lockers": {
"data": []
}
}
}
}PATCH /v3/buildings/577696301
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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": "Pollich, Boyle and Quigley-32",
"building_type": "multi_family",
"display_name_strategy": "anonymous",
"nfc_enabled": false,
"send_panel_status_report": false,
"mobile_logo_picture": {
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb_small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium_small_picture.jpg"
},
"panel_logo_picture": {
"thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
"medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
},
"address_1": "722 Leif Lake",
"address_2": "Tienton, CT 68210",
"city": "Tienton",
"state": "Connecticut",
"zip_code": "68210",
"phone_number": "1-611-992-3131 x5246",
"country": "us",
"qr_key_enabled": true,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"delivery_pass_enabled": true,
"door_release_pin": true,
"open_door_button_enabled": true
},
"relationships": {
"panels": {
"data": [
{
"id": "708353670",
"type": "panels"
}
]
},
"key_lockers": {
"data": []
}
}
}
}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/f4e25234-586f-4db6-a483-c56d48252946/status
Requests
GET /v3/me/calls/f4e25234-586f-4db6-a483-c56d48252946/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-03-22T11:49:02Z"
},
"relationships": {
"call": {
"data": {
"id": "1",
"type": "calls"
}
}
}
},
"included": [
{
"id": "1",
"type": "calls",
"attributes": {
"guid": "f4e25234-586f-4db6-a483-c56d48252946",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"status": "initializing",
"display_status": "Initializing",
"panel_id": 708353671,
"panel_name": "Scytale 12",
"panel_sip": "panel_708353671",
"provider": "internal"
}
}
]
}GET /v3/me/calls/DOES_NOT_EXIST/status
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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: f4e25234-586f-4db6-a483-c56d48252946
Calls ¶
Sortable fields:
-
created_at
-
logged_at
-
notification_type
-
call_type
Filterable fields:
-
unit -> integer -
notification_type -> enum(string) -
call_type -> enum(string) -
guid -> string
Enumerations:
-
call_type:
- voip
- mobile
-
notification_type:
- visitor
- delivery
GET /v3/me/calls
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": "8f48eeb0-7619-4247-9739-4ecbdbe9cca1",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"status": "initializing",
"display_status": "Initializing",
"initial": true,
"provider": "internal"
},
"relationships": {
"rollover_calls": {
"data": []
},
"panel": {
"data": {
"id": "708353673",
"type": "panels"
}
}
}
},
{
"id": "4",
"type": "calls",
"attributes": {
"guid": "31830e29-b8c7-46e3-83ee-2b93f583deb8",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"status": "initializing",
"display_status": "Initializing",
"initial": true,
"provider": "internal"
},
"relationships": {
"rollover_calls": {
"data": []
},
"panel": {
"data": {
"id": "708353673",
"type": "panels"
}
}
}
},
{
"id": "3",
"type": "calls",
"attributes": {
"guid": "75ddb8d6-03cf-4909-a3c8-ff64a98f3b32",
"call_type": "voip",
"notification_type": "visitor",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"status": "initializing",
"display_status": "Initializing",
"initial": true,
"provider": "internal"
},
"relationships": {
"rollover_calls": {
"data": []
},
"panel": {
"data": {
"id": "708353673",
"type": "panels"
}
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}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": "c08a1434-f8d4-4877-97a1-b121e5308684",
"delivery_guid": "3ae99e37-8d50-4010-bec7-0625189edca7",
"name": "Jong Block",
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb/small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/small_picture.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z"
},
"relationships": {
"unit": {
"data": {
"id": "843107278",
"type": "units"
}
},
"user": {
"data": {
"id": "636166931",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353674",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353677",
"type": "panels"
}
}
}
},
{
"id": "5",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"call_guid": "9dfaee4c-da80-41e0-b635-abcb19f1e1cb",
"delivery_guid": "3969b699-321b-469f-9564-292cf0b59dc6",
"name": "Miss Ashton Pacocha",
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb/small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/small_picture.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z"
},
"relationships": {
"unit": {
"data": {
"id": "843107278",
"type": "units"
}
},
"user": {
"data": {
"id": "636166931",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353674",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353676",
"type": "panels"
}
}
}
},
{
"id": "4",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"call_guid": "767748e1-165f-4c8c-bc95-95b261b77c1b",
"delivery_guid": "3995bffc-4080-4e03-bf6e-feda8a2eaf72",
"name": "Nohemi Dickens",
"thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/thumb/small_picture.jpg",
"medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/small_picture.jpg",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z"
},
"relationships": {
"unit": {
"data": {
"id": "843107278",
"type": "units"
}
},
"user": {
"data": {
"id": "636166931",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353674",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353675",
"type": "panels"
}
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}Door 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-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/voice_message.mp3"
},
"message_type": "voice"
}
},
{
"id": "2",
"type": "messages",
"attributes": {
"message": null,
"voice": {
"url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/voice_message.mp3"
},
"message_type": "voice"
}
},
{
"id": "1",
"type": "messages",
"attributes": {
"message": null,
"voice": {
"url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/voice_message.mp3"
},
"message_type": "voice"
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/me/messages?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/me/messages?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/me/messages?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}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": "c9b77456-0649-4abf-80f7-8a02ab9519c5",
"created_at": "2023-03-22T11:49:07Z"
}
}
}POST /v3/me/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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": "874d3de9-0f1a-4e0c-8b45-4e1017934f2b",
"created_at": "2023-03-22T11:49:08Z"
}
}
}POST /v3/me/open_door
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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": "636166939",
"type": "users",
"attributes": {
"name": "Isiah Fisher",
"first_name": "Isiah",
"last_name": "Fisher",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "40",
"email": "derrick_schmidt@jerde.info",
"sms_phone_number": null,
"phone_number": null
},
"relationships": {
"tenants": {
"data": [
{
"id": "636166938",
"type": "tenants"
}
]
}
}
}
}GET /v3/me?include=tenants.building,tenants.panels,tenants.unit
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166940",
"type": "users",
"attributes": {
"name": "Neta Hessel",
"first_name": "Neta",
"last_name": "Hessel",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "41",
"email": "jarrod.labadie@bednar.info",
"sms_phone_number": null,
"phone_number": null
},
"relationships": {
"tenants": {
"data": [
{
"id": "636166939",
"type": "tenants"
}
]
}
}
},
"included": [
{
"id": "636166939",
"type": "tenants",
"attributes": {
"unit_id": 843107312,
"inactive_at": null
},
"relationships": {
"building": {
"data": {
"id": "577696343",
"type": "buildings"
}
},
"unit": {
"data": {
"id": "843107312",
"type": "units"
}
},
"panels": {
"data": [
{
"id": "708353688",
"type": "panels"
}
]
},
"devices": {
"data": []
}
}
},
{
"id": "577696343",
"type": "buildings",
"attributes": {
"name": "Hudson-Pacocha-71",
"building_type": "multi_family",
"mobile_logo_picture": {
"thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
"medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
},
"panel_logo_picture": {
"thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
"medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
},
"address_1": "603 Mills Parkways",
"address_2": "South Deaneside, LA 18623",
"city": "South Deaneside",
"state": "Louisiana",
"zip_code": "18623",
"phone_number": "(936) 868-7856 x776",
"country": "us",
"time_zone": "Etc/UTC",
"open_door_button_enabled": true
}
},
{
"id": "843107312",
"type": "units",
"attributes": {
"kind": "residential",
"label": "00",
"floor_number": 0
}
},
{
"id": "708353688",
"type": "panels",
"attributes": {
"name": "Gurney Halleck 30",
"nfc": {
"uuid": "fd177e15-3a02-47f9-9e8d-81b3da7f0fcc"
}
}
}
]
}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": "636166941",
"attributes": {
"last_name": "Baker"
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166941",
"type": "users",
"attributes": {
"name": "Marianne Baker",
"first_name": "Marianne",
"last_name": "Baker",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "42",
"email": "billie@leannon.info",
"sms_phone_number": null,
"phone_number": null
},
"relationships": {
"tenants": {
"data": [
{
"id": "636166940",
"type": "tenants"
}
]
}
}
}
}PUT /v3/me
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "tenants",
"id": "636166942",
"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": "53f8c18d-4113-4fbb-8ae7-1f2585528747",
"delivery_guid": "77eca416-616b-4a60-822e-db0cf6655adf",
"name": "Serena Heaney",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "31",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "doorman",
"call_guid": "d7e87174-cc3e-4280-bb33-965f3709073f",
"delivery_guid": "46556694-be18-47a2-aadb-1e08e9782a7e",
"name": "Cody West",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "30",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "b8886aa3-7a1e-4f51-b76a-d69596fbe0aa",
"delivery_guid": "fb0d1908-e262-4297-8dc7-67310565949a",
"name": "Wilfredo Tromp",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "29",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "e5784825-8509-4268-a753-ee09a7427c34",
"delivery_guid": "eed65b48-7980-44a4-bf45-30aa98745ecd",
"name": "Dr. Lane Kunde",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "28",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "delivery",
"panel_user_type": "default",
"call_guid": "5ec9faa2-3942-4677-809c-17685a1c00fb",
"delivery_guid": "91c0e654-b398-4d84-bf0a-731e819fbdd5",
"name": "Marylee Reichel",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "27",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "delivery",
"panel_user_type": "default",
"call_guid": "4857a6a8-3a0b-4822-95b3-872f4df12123",
"delivery_guid": "c174dbed-9530-4423-930e-3d664f08bd36",
"name": "Trevor Mitchell PhD",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "26",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "ff22c206-5183-4c8c-a5be-e919e91dd608",
"delivery_guid": "53a265aa-7277-4880-9bc7-c91c3d4f50d4",
"name": "Dr. Chana Pfeffer",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "25",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "7ae6efa8-7b37-4a58-ac0b-313ebc264886",
"delivery_guid": "f8ad5678-4d06-4cba-810a-1a7914e06d8d",
"name": "Trenton Legros",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "24",
"type": "door_releases",
"attributes": {
"release_method": "qr_key",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "58c90aff-8032-4d9f-9a44-a5a8b8ffd7b5",
"delivery_guid": "f13f097f-7924-43f8-aa3f-6902fdcf00bc",
"name": "Elida Strosin",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "23",
"type": "door_releases",
"attributes": {
"release_method": "qr_key",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "b78e5e93-1c01-4247-96ed-f83061549e06",
"delivery_guid": "8890db75-8452-427a-a6d4-283e0d8e808d",
"name": "Blake Hackett",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "22",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "7b744227-42af-4d19-844a-539b58fbe690",
"delivery_guid": "3eb625eb-e587-4e3e-b229-a2ae4301b86d",
"name": "Emogene Blick IV",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "21",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "3e4cb91c-a408-4d21-ae2e-fecefef143b2",
"delivery_guid": "68ead11b-1511-4c8f-832d-61edb9d99df0",
"name": "Brent D'Amore",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": {
"id": "708353702",
"type": "panels"
}
},
"device": {
"data": {
"id": "708353702",
"type": "panels"
}
}
}
},
{
"id": "20",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "3cdfb1ed-6570-4bbf-8d27-d9aa8cac68a4",
"delivery_guid": "8cc8a4ff-ecec-486f-be28-4ceb97df5db0",
"name": "Mr. Rodrick Spinka",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": null
},
"device": {
"data": {
"id": "106694919",
"type": "keypads"
}
}
}
},
{
"id": "19",
"type": "door_releases",
"attributes": {
"release_method": "mobile",
"door_release_type": "visitor",
"panel_user_type": "default",
"call_guid": "c241d258-4e27-4186-b955-f2b3e909cc77",
"delivery_guid": "81e15440-02f5-4c08-a4ed-e9a635a65e33",
"name": "Hilma Greenfelder",
"created_at": "2023-03-22T11:47:12Z",
"logged_at": "2023-03-22T11:47:12Z",
"thumb_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg",
"medium_url": "/assets/no_pic-8244a33d73b6a6668863761ddfbf8baa65f32869c273f8eba97bb8478c9a1d39.jpg"
},
"relationships": {
"unit": {
"data": {
"id": "843107366",
"type": "units"
}
},
"user": {
"data": {
"id": "636166955",
"type": "users"
}
},
"panel": {
"data": null
},
"device": {
"data": {
"id": "106694919",
"type": "keypads"
}
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}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-03-22T11:49:24+00:00",
"ends_at": "2023-03-24T11:49:19+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107336
}
},
"devices": {
"data": [
{
"type": "keypads",
"id": 106694918
}
]
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "15",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:24Z",
"ends_at": "2023-03-24T11:49:19Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "7",
"type": "virtual_keys"
},
{
"id": "8",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "7",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-7cx557.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "181085",
"instructions_url": "http://user.butterflymx.test/public/dooley-and-sons-95/virtual_keys/7/4498189154c4312c3550102c4124e800",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "8",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1f8yuoc.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "794804",
"instructions_url": "http://user.butterflymx.test/public/dooley-and-sons-95/virtual_keys/8/507c8c7c6b6e8ae910260e4cc6ef3661",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-03-22T11:49:26+00:00",
"ends_at": "2023-03-24T11:49:21+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 2,
"compartment": "H3"
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107338
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "16",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:26Z",
"ends_at": "2023-03-24T11:49:21Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "9",
"type": "virtual_keys"
},
{
"id": "10",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "9",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1mcp4ll.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "251167",
"instructions_url": "http://user.butterflymx.test/public/hane-strosin-and-emard-97/virtual_keys/9/a11a5cea35586818e6e6a73a4b65b0e3",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "10",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-w4lgca.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "759572",
"instructions_url": "http://user.butterflymx.test/public/hane-strosin-and-emard-97/virtual_keys/10/e67e52ee2e8706767baae3becf1b96de",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-03-22T11:49:28+00:00",
"ends_at": "2023-03-24T11:49:23+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 3,
"compartment": "any_when_used"
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107341
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "17",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:28Z",
"ends_at": "2023-03-24T11:49:23Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "11",
"type": "virtual_keys"
},
{
"id": "12",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "11",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-q3d4rl.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "833645",
"instructions_url": "http://user.butterflymx.test/public/gleason-morissette-100/virtual_keys/11/b74c2402925cdcd32cb0c5075c3f5b4e",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "12",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-9oi5bn.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "343529",
"instructions_url": "http://user.butterflymx.test/public/gleason-morissette-100/virtual_keys/12/213b12021e226150282793269cc49777",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-03-22T11:49:30+00:00",
"ends_at": "2023-03-24T11:49:25+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 4,
"compartment_id": 123
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107344
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "18",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:30Z",
"ends_at": "2023-03-24T11:49:25Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "13",
"type": "virtual_keys"
},
{
"id": "14",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "13",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-14blgw6.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "603021",
"instructions_url": "http://user.butterflymx.test/public/wisozk-group-103/virtual_keys/13/72bc540e413a31138441c2f3003622e4",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "14",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-ac785f.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "590760",
"instructions_url": "http://user.butterflymx.test/public/wisozk-group-103/virtual_keys/14/b59a68980542601f6a6a79ecd17882b6",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-03-22T11:49:32+00:00",
"ends_at": "2023-03-24T11:49:27+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 5,
"compartment_id": 164,
"item_return_policy": "return"
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107347
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "19",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:32Z",
"ends_at": "2023-03-24T11:49:27Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "15",
"type": "virtual_keys"
},
{
"id": "16",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "15",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-137h6x2.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "395137",
"instructions_url": "http://user.butterflymx.test/public/carroll-inc-106/virtual_keys/15/0c91c8c7eac2a7527b777a30e3260ad3",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "16",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1o5ynv7.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "161698",
"instructions_url": "http://user.butterflymx.test/public/carroll-inc-106/virtual_keys/16/e1a73f77e968c61c0f8a82e42c2ba6cb",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "2023-03-22T11:49:34+00:00",
"ends_at": "2023-03-24T11:49:29+00:00",
"recipients": [
"test@example.com",
"+12345678901"
],
"key_locker": {
"id": 6,
"compartment_id": 191
},
"item_return_policy": "return"
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107350
}
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "20",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:34Z",
"ends_at": "2023-03-24T11:49:29Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "17",
"type": "virtual_keys"
},
{
"id": "18",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "17",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-2q8ir4.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "552663",
"instructions_url": "http://user.butterflymx.test/public/okuneva-o-kon-109/virtual_keys/17/6ff72116f2740af9a6dc1b1e261f8bc4",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "18",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-enehb3.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "260285",
"instructions_url": "http://user.butterflymx.test/public/okuneva-o-kon-109/virtual_keys/18/b67a461c981bd4dd94f385995b4792a9",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "keychains",
"attributes": {
"name": "Custom Key",
"starts_at": "2023-03-22T11:49:35+00:00",
"ends_at": "2023-03-24T11:49:30+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166948
}
},
"devices": {
"data": []
},
"access_points": {
"data": [
{
"type": "access_point",
"id": 842395210
}
]
}
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "21",
"type": "keychains",
"attributes": {
"name": "Custom Key",
"weekdays": [],
"starts_at": "2023-03-22T11:49:35Z",
"ends_at": "2023-03-24T11:49:30Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "19",
"type": "virtual_keys"
},
{
"id": "20",
"type": "virtual_keys"
}
]
},
"devices": {
"data": [
{
"id": "708353700",
"type": "panels"
}
]
}
}
},
"included": [
{
"id": "19",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-15jytkw.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "796587",
"instructions_url": "http://user.butterflymx.test/public/stanton-ondricka-112/virtual_keys/19/4745ca3c6520f1274f82253a0d9dde3b",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "20",
"type": "virtual_keys",
"attributes": {
"name": "Custom Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-w6kv4j.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "172435",
"instructions_url": "http://user.butterflymx.test/public/stanton-ondricka-112/virtual_keys/20/e1406a6d4d4ed24e5eda19a573bb573f",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "708353700",
"type": "panels",
"attributes": {
"name": "Paul \"Muad'Dib\" \"Usul\" Atreides 49",
"nfc": {
"uuid": "2798e80a-fda9-4e42-a178-ddb4622661ec"
}
},
"relationships": {
"building": {
"data": {
"id": "577696384",
"type": "buildings"
}
}
}
}
]
}POST /v3/keychains/custom
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Custom Key",
"starts_at": "",
"ends_at": "2023-03-24T11:49:31+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166949
}
}
}
}
}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": "Technology Manager 19",
"weekdays": [],
"starts_at": "2023-03-22T11:49:40Z",
"ends_at": "2023-03-22T12:49:40Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "26",
"type": "keychains",
"attributes": {
"name": "Sales Designer 18",
"weekdays": [],
"starts_at": "2023-03-22T11:49:40Z",
"ends_at": "2023-03-22T12:49:40Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "25",
"type": "keychains",
"attributes": {
"name": "Future Officer 17",
"weekdays": [],
"starts_at": "2023-03-22T11:49:40Z",
"ends_at": "2023-03-22T12:49:40Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "23",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/keychains?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/keychains?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/keychains?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}GET /v3/keychains?include=virtual_keys,devices
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "30",
"type": "keychains",
"attributes": {
"name": "Retail Assistant 22",
"weekdays": [],
"starts_at": "2023-03-22T11:49:40Z",
"ends_at": "2023-03-22T12:49:40Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "29",
"type": "keychains",
"attributes": {
"name": "Education Director 21",
"weekdays": [],
"starts_at": "2023-03-22T11:49:40Z",
"ends_at": "2023-03-22T12:49:40Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": []
},
"devices": {
"data": []
}
}
},
{
"id": "28",
"type": "keychains",
"attributes": {
"name": "Legal Executive 20",
"weekdays": [],
"starts_at": "2023-03-22T11:49:40Z",
"ends_at": "2023-03-22T12:49:40Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "24",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
}
],
"included": [
{
"id": "24",
"type": "virtual_keys",
"attributes": {
"name": "Carlton Greenfelder III",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-14y05bs.png",
"email": "freddie_lesch@example.com",
"sms_number": "+12546262569",
"used_at": null,
"one_time_key_used_at": null,
"pin": "807196",
"instructions_url": "http://user.butterflymx.test/public/reilly-sawayn-135/virtual_keys/24/f141ff446c86469ce45b3a3d2e9c3a8b",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/keychains?include=virtual_keys%2Cdevices&page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/keychains?include=virtual_keys%2Cdevices&page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/keychains?include=virtual_keys%2Cdevices&page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}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": "Product Construction Supervisor 23",
"weekdays": [],
"starts_at": "2023-03-22T11:49:41Z",
"ends_at": "2023-03-22T12:49:41Z",
"time_from": "11:49",
"time_to": "12:49",
"kind": "custom",
"start_date": "2023-03-22",
"end_date": "2023-03-22",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "25",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
}
}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-03-22T11:49:55+00:00",
"ends_at": "2023-03-24T11:49:50+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107411
}
}
}
}
}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-03-22T11:49:55Z",
"ends_at": "2023-03-24T11:49:50Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "one_time",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "27",
"type": "virtual_keys"
},
{
"id": "28",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "27",
"type": "virtual_keys",
"attributes": {
"name": "One-Time Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-aiv1dx.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "754960",
"instructions_url": "http://user.butterflymx.test/public/kemmer-llc-158/virtual_keys/27/9d0f697c5f190699683487ca1a690d81",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "28",
"type": "virtual_keys",
"attributes": {
"name": "One-Time Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-uy6tsd.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "000758",
"instructions_url": "http://user.butterflymx.test/public/kemmer-llc-158/virtual_keys/28/064d094cbece979e56b5194a61aa117e",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/one_time
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "keychains",
"attributes": {
"name": "One-Time Key",
"starts_at": "2023-03-22T11:49:56+00:00",
"ends_at": "2023-03-24T11:49:51+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"relationships": {
"tenant": {
"data": {
"id": "636166974",
"type": "tenant"
}
},
"access_points": {
"data": [
{
"type": "access_point",
"id": 842395211
}
]
}
}
}
}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-03-22T11:49:56Z",
"ends_at": "2023-03-24T11:49:51Z",
"time_from": "11:49",
"time_to": "11:49",
"kind": "one_time",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "29",
"type": "virtual_keys"
},
{
"id": "30",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "29",
"type": "virtual_keys",
"attributes": {
"name": "One-Time Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-shm5fr.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "963003",
"instructions_url": "http://user.butterflymx.test/public/powlowski-llc-159/virtual_keys/29/6a1061978ac2a84c7d23664685d7cc0d",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "30",
"type": "virtual_keys",
"attributes": {
"name": "One-Time Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-16waxse.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "442847",
"instructions_url": "http://user.butterflymx.test/public/powlowski-llc-159/virtual_keys/30/a0d00163c3467c1dbefeeb5580cc9f47",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/one_time
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "One-Time Key",
"starts_at": "",
"ends_at": "2023-03-24T11:49:52+00:00",
"recipients": [
"test@example.com",
"+12345678901"
]
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166975
}
}
}
}
}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-03-22",
"end_date": "2023-03-24",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167011,
"account_id": 112,
"first_name": "Bea",
"last_name": "Schinner",
"created_at": "2023-03-22T11:49:59Z",
"updated_at": "2023-03-22T11:49:59Z",
"email_cache": "jae@boyle.org",
"qr_key_enabled": true,
"contact_preference": "phone_call",
"confirmed_at_cache": null,
"deleted_at": null,
"devices_count": 0,
"status": "registered",
"panel_status_report": false,
"invited_at": null,
"language": "en",
"download_app_page_shown": true,
"privacy_consent_given": true,
"anonymized": false
}
},
"type": "keychains",
"relationships": {
"unit": {
"data": {
"type": "unit",
"id": 843107430
}
}
}
}
}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-03-22T11:20:00Z",
"ends_at": "2023-03-24T11:50:00Z",
"time_from": "11:20",
"time_to": "11:50",
"kind": "recurring",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "33",
"type": "virtual_keys"
},
{
"id": "34",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "33",
"type": "virtual_keys",
"attributes": {
"name": "Recurring Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-785b8g.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "247052",
"instructions_url": "http://user.butterflymx.test/public/howe-rohan-and-wintheiser-173/virtual_keys/33/60115f020ddacee0b5de86dded0271fa",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "34",
"type": "virtual_keys",
"attributes": {
"name": "Recurring Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-hzrjhs.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "847510",
"instructions_url": "http://user.butterflymx.test/public/howe-rohan-and-wintheiser-173/virtual_keys/34/6ac93f3b5a6bf9643b0d19635ebc7356",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/recurring
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Recurring Key",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167013,
"account_id": 114,
"first_name": "Lino",
"last_name": "Ankunding",
"created_at": "2023-03-22T11:50:00Z",
"updated_at": "2023-03-22T11:50:00Z",
"email_cache": "enrique_sporer@braun.com",
"qr_key_enabled": true,
"contact_preference": "phone_call",
"confirmed_at_cache": null,
"deleted_at": null,
"devices_count": 0,
"status": "registered",
"panel_status_report": false,
"invited_at": null,
"language": "en",
"download_app_page_shown": true,
"privacy_consent_given": true,
"anonymized": false
}
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166985
}
}
}
}
}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-03-22T11:20:00Z",
"ends_at": "2023-03-24T11:50:00Z",
"time_from": "11:20",
"time_to": "11:50",
"kind": "recurring",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "35",
"type": "virtual_keys"
},
{
"id": "36",
"type": "virtual_keys"
}
]
},
"devices": {
"data": []
}
}
},
"included": [
{
"id": "35",
"type": "virtual_keys",
"attributes": {
"name": "Recurring Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-i120om.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "437420",
"instructions_url": "http://user.butterflymx.test/public/o-hara-and-sons-174/virtual_keys/35/13d5fda09ad1e38b4b6bca51119330e7",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "36",
"type": "virtual_keys",
"attributes": {
"name": "Recurring Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1vlia5h.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "438702",
"instructions_url": "http://user.butterflymx.test/public/o-hara-and-sons-174/virtual_keys/36/c0ba745d65679c00d4c1a0fcdd50d5ef",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
]
}POST /v3/keychains/recurring
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"type": "keychains",
"attributes": {
"name": "Recurring Key",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167015,
"account_id": 116,
"first_name": "David",
"last_name": "Nicolas",
"created_at": "2023-03-22T11:50:02Z",
"updated_at": "2023-03-22T11:50:02Z",
"email_cache": "floria@rippinvandervort.com",
"qr_key_enabled": true,
"contact_preference": "phone_call",
"confirmed_at_cache": null,
"deleted_at": null,
"devices_count": 0,
"status": "registered",
"panel_status_report": false,
"invited_at": null,
"language": "en",
"download_app_page_shown": true,
"privacy_consent_given": true,
"anonymized": false
}
},
"relationships": {
"devices": {
"data": [
{
"id": "708353713",
"type": "panels"
},
{
"id": "708353714",
"type": "panels"
}
]
},
"tenant": {
"data": {
"id": "636166986",
"type": "tenant"
}
},
"access_points": {
"data": [
{
"type": "access_point",
"id": 842395215
}
]
}
}
}
}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-03-22T11:20:00Z",
"ends_at": "2023-03-24T11:50:00Z",
"time_from": "11:20",
"time_to": "11:50",
"kind": "recurring",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"allow_unit_access": false
},
"relationships": {
"virtual_keys": {
"data": [
{
"id": "37",
"type": "virtual_keys"
},
{
"id": "38",
"type": "virtual_keys"
}
]
},
"devices": {
"data": [
{
"id": "708353713",
"type": "panels"
},
{
"id": "708353714",
"type": "panels"
}
]
}
}
},
"included": [
{
"id": "37",
"type": "virtual_keys",
"attributes": {
"name": "Recurring Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-hcjquh.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "209076",
"instructions_url": "http://user.butterflymx.test/public/doyle-group-175/virtual_keys/37/febb13cc1725da81abfe69fd38ff0c73",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "38",
"type": "virtual_keys",
"attributes": {
"name": "Recurring Key",
"qr_code_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1xp2atf.png",
"email": null,
"sms_number": "+12345678901",
"used_at": null,
"one_time_key_used_at": null,
"pin": "762447",
"instructions_url": "http://user.butterflymx.test/public/doyle-group-175/virtual_keys/38/47880fd930ee08081b5d6de585c63234",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
},
{
"id": "708353713",
"type": "panels",
"attributes": {
"name": "Hasimir Fenring 63",
"nfc": {
"uuid": "57f9fe70-db36-4078-a821-378280722695"
}
},
"relationships": {
"building": {
"data": {
"id": "577696437",
"type": "buildings"
}
}
}
},
{
"id": "708353714",
"type": "panels",
"attributes": {
"name": "Liet-Kynes 64",
"nfc": {
"uuid": "a187bd6e-4a41-4f13-9b7c-e9e1c54fffb5"
}
},
"relationships": {
"building": {
"data": {
"id": "577696437",
"type": "buildings"
}
}
}
}
]
}POST /v3/keychains/recurring
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "",
"start_date": "2023-03-22",
"end_date": "2023-03-24",
"time_from": "11:20",
"time_to": "11:50",
"weekdays": [
"wed",
"sat"
],
"recipients": [
"test@example.com",
"+12345678901"
],
"creator": {
"id": 636167017,
"account_id": 118,
"first_name": "Patricia",
"last_name": "Lockman",
"created_at": "2023-03-22T11:50:05Z",
"updated_at": "2023-03-22T11:50:05Z",
"email_cache": "monet_heller@nienowhartmann.org",
"qr_key_enabled": true,
"contact_preference": "phone_call",
"confirmed_at_cache": null,
"deleted_at": null,
"devices_count": 0,
"status": "registered",
"panel_status_report": false,
"invited_at": null,
"language": "en",
"download_app_page_shown": true,
"privacy_consent_given": true,
"anonymized": false
}
},
"type": "keychains",
"relationships": {
"tenant": {
"data": {
"type": "tenant",
"id": 636166987
}
}
}
}
}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-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/original/qr_code_20230322-1020-1eow6bm.png",
"email": "test@example.com",
"sms_number": null,
"used_at": null,
"one_time_key_used_at": null,
"pin": "188756",
"instructions_url": "http://user.butterflymx.test/public/towne-schultz-and-connelly-169/virtual_keys/31/d60d196635ddf1c3b777df0bb96bb057",
"sent_at": null,
"synced_with_remote_lock": false
},
"relationships": {
"door_releases": {
"data": []
}
}
}
}POST /v3/keychains/36/virtual_keys
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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": "708353703",
"attributes": {
"panel_id": 708353703,
"video": true,
"audio": false,
"call_guid": "87142693-c04f-43a6-bf12-8495b33633d0"
}
}
}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": "708353704",
"attributes": {
"panel_id": "NOT_EXIST",
"video": true,
"audio": false,
"call_guid": "9d0c24fa-3cbe-4ec6-80dd-5f34c8efd1d3"
}
}
}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": "708353705",
"attributes": {
"panel_id": 708353705,
"call_guid": "b4d4a83c-ba08-46c6-bdd7-bb73184da626"
}
}
}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": "708353706",
"attributes": {
"panel_id": "NOT_EXIST",
"call_guid": "c9f0908e-fd3e-4585-90dd-2cc5a169b95a"
}
}
}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": "708353707",
"attributes": {
"panel_id": 708353707,
"call_guid": "adaa57b8-39f1-4681-a91d-0c6c01fce14e"
}
}
}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": "708353708",
"attributes": {
"panel_id": "NOT_EXIST",
"call_guid": "6c555721-7e57-40d6-815e-b944866c52fa"
}
}
}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": "708353709",
"attributes": {
"panel_id": 708353709,
"call_guid": "28a0c2ab-a3f0-43b7-9fc6-085197475a87"
}
}
}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": "708353710",
"attributes": {
"panel_id": "NOT_EXIST",
"call_guid": "eb02d900-9ff5-4e92-83d1-6bcf8be2eca9"
}
}
}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": "708353711",
"attributes": {
"panel_id": 708353711,
"video": true,
"audio": false,
"call_guid": "8a9624ab-3765-4afc-9191-38ebe5ecac29"
}
}
}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": "708353712",
"attributes": {
"panel_id": "NOT_EXIST",
"video": true,
"audio": false,
"call_guid": "e6ce8c87-fe11-4259-a62c-bc0f678ae655"
}
}
}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-03-22T11:50:06Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Regional Advertising Supervisor",
"display_name": "Mrs. Tyron Bruen",
"display_name_strategy": "building",
"display_first_name": "Maryalice Lebsack",
"display_last_name": "James Stamm",
"display_only_on_search": true,
"pin_enabled": true,
"email_notifications": true,
"sms_notifications": true,
"do_not_disturb": false,
"preferences": {
"door_opens": {
"push": false,
"email": false,
"sms": null
},
"messages": {
"push": true,
"email": false,
"sms": false
}
}
},
"relationships": {
"unit": {
"data": {
"id": "843107440",
"type": "units"
}
},
"user": {
"data": {
"id": "636167024",
"type": "users"
}
}
}
},
{
"id": "636166990",
"type": "tenants",
"attributes": {
"active_at": "2023-03-22T11:50:06Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Marketing Architect",
"display_name": "Hannelore Kohler",
"display_name_strategy": "building",
"display_first_name": "Brian Muller V",
"display_last_name": "Lance Fahey",
"display_only_on_search": false,
"pin_enabled": true,
"email_notifications": true,
"sms_notifications": true,
"do_not_disturb": false,
"preferences": {
"door_opens": {
"push": false,
"email": false,
"sms": null
},
"messages": {
"push": true,
"email": false,
"sms": false
}
}
},
"relationships": {
"unit": {
"data": {
"id": "843107440",
"type": "units"
}
},
"user": {
"data": {
"id": "636167023",
"type": "users"
}
}
}
},
{
"id": "636166989",
"type": "tenants",
"attributes": {
"active_at": "2023-03-22T11:50:06Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Global Hospitality Liaison",
"display_name": "Hui Hessel",
"display_name_strategy": "building",
"display_first_name": "Roselle Runolfsson",
"display_last_name": "Vicente Jakubowski PhD",
"display_only_on_search": false,
"pin_enabled": true,
"email_notifications": true,
"sms_notifications": true,
"do_not_disturb": false,
"preferences": {
"door_opens": {
"push": false,
"email": false,
"sms": null
},
"messages": {
"push": true,
"email": false,
"sms": false
}
}
},
"relationships": {
"unit": {
"data": {
"id": "843107440",
"type": "units"
}
},
"user": {
"data": {
"id": "636167022",
"type": "users"
}
}
}
}
],
"included": [
{
"id": "636167024",
"type": "users",
"attributes": {
"name": "Cleo Kohler",
"first_name": "Cleo",
"last_name": "Kohler",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "125",
"registration_status": "registered",
"email": "noel_wilkinson@bartonsipes.org",
"sms_phone_number": null,
"phone_number": null
}
},
{
"id": "636167023",
"type": "users",
"attributes": {
"name": "Lacie Cole",
"first_name": "Lacie",
"last_name": "Cole",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "124",
"registration_status": "registered",
"email": "deon.kertzmann@cole.org",
"sms_phone_number": null,
"phone_number": null
}
},
{
"id": "636167022",
"type": "users",
"attributes": {
"name": "Werner Trantow",
"first_name": "Werner",
"last_name": "Trantow",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "123",
"registration_status": "registered",
"email": "cleopatra_krajcik@oberbrunner.biz",
"sms_phone_number": null,
"phone_number": null
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/tenants?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/tenants?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/tenants?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}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-03-22T11:50:07Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Forward Manufacturing Manager",
"display_name": "Adalberto Johnston",
"display_name_strategy": "building",
"display_first_name": "Abram Hansen",
"display_last_name": "Mr. Bo Emard",
"display_only_on_search": false,
"pin_enabled": true,
"email_notifications": true,
"sms_notifications": true,
"do_not_disturb": false,
"preferences": {
"door_opens": {
"push": false,
"email": false,
"sms": null
},
"messages": {
"push": true,
"email": false,
"sms": false
}
}
},
"relationships": {
"unit": {
"data": {
"id": "843107442",
"type": "units"
}
},
"user": {
"data": {
"id": "636167026",
"type": "users"
}
}
}
},
"included": [
{
"id": "636167026",
"type": "users",
"attributes": {
"name": "Johnny Cole",
"first_name": "Johnny",
"last_name": "Cole",
"contact_preference": "phone_call",
"thumb_url": null,
"medium_url": null,
"sip_username": "127",
"registration_status": "registered",
"email": "chad.cummings@wehner.net",
"sms_phone_number": null,
"phone_number": null
}
}
]
}POST /v3/tenants
Requests
POST /v3/tenants
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"unit_id": 843107444,
"email": "fiona@schneider.biz",
"active_at": "2023-03-22T11:50:07Z"
},
"type": "tenants",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "636166993",
"type": "tenants",
"attributes": {
"active_at": "2023-03-22T11:50:07Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": null,
"display_name": "Resident",
"display_name_strategy": "building",
"display_first_name": "Resident",
"display_last_name": " ",
"display_only_on_search": false,
"pin_enabled": true,
"email_notifications": false,
"sms_notifications": false,
"do_not_disturb": false,
"preferences": {
"door_opens": {
"push": false,
"email": false,
"sms": null
},
"messages": {
"push": true,
"email": false,
"sms": false
}
}
},
"relationships": {
"unit": {
"data": {
"id": "843107444",
"type": "units"
}
},
"user": {
"data": {
"id": "636167028",
"type": "users"
}
}
}
}
}POST /v3/tenants
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"unit_id": 843107446,
"email": "",
"first_name": "",
"last_name": "User",
"active_at": "2023-03-22T11:50:08Z"
},
"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-03-22T11:50:08Z",
"inactive_at": null,
"qr_key_enabled": true,
"delivery_pass_instructions": null,
"directory_message": "Mining Strategist",
"display_name": "Giovanna Moen",
"display_name_strategy": "building",
"display_first_name": "Zola Jacobs",
"display_last_name": "Mica Smitham",
"display_only_on_search": true,
"pin_enabled": true,
"email_notifications": true,
"sms_notifications": true,
"do_not_disturb": true,
"preferences": {
"door_opens": {
"push": false,
"email": false,
"sms": null
},
"messages": {
"push": true,
"email": false,
"sms": false
}
}
},
"relationships": {
"unit": {
"data": {
"id": "843107448",
"type": "units"
}
},
"user": {
"data": {
"id": "636167032",
"type": "users"
}
}
}
}
}PATCH /v3/tenants/636166995
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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/kemmer-and-sons-188/tour_schedules
Requests
GET /v3/tours/kemmer-and-sons-188/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": "577696450",
"type": "buildings",
"attributes": {
"handle": "kemmer-and-sons-188",
"name": "Kemmer and Sons-188",
"slots": {
"weekday_availabilities": {
"mon": [
[
"09:00",
"22:00"
]
],
"wed": [
[
"09:00",
"22:00"
]
],
"fri": [
[
"09:00",
"22:00"
]
]
},
"scheduled_slots": {
"2020-12-14T13:00:00Z": 1,
"2020-12-14T14:00:00Z": 1,
"2020-12-14T19:00:00Z": 1
},
"reserved_slots": {
"2020-12-14T12:00:00Z": 1
},
"blacked_out_slots": [
{
"starts_at": "2020-12-14T17:00:00Z",
"ends_at": "2020-12-14T18:00:00Z"
}
]
},
"slot_duration_minutes": 60,
"max_simultaneous_bookings": 1,
"time_window_days": 14,
"address": {
"country": "us",
"address_1": "11493 Stark Junctions",
"address_2": "Ritchieview, CT 32693",
"city": "Ritchieview",
"state": "Connecticut",
"zip_code": "32693",
"phone_number": "358.136.0006 x88336"
},
"enabled": true,
"tour_units": [],
"unit_selection": false,
"identity_verification": false,
"key_locker_in_use": false,
"shared_key_compartment_count": 0,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"day_of_tour_text": null,
"tos_text": null,
"day_of_tour_text_draft": null,
"credit_card_hold": false,
"email_communication": true,
"sms_communication": true,
"enable_scheduling_portal": true
}
}
}ListGET/v3/tours/{building_handle}/tour_schedules
URI Parameters
- building_handle
string(required) Example: kemmer-and-sons-188
POST /v3/tours/funk-klocko-190/tour_schedules
Requests
POST /v3/tours/funk-klocko-190/tour_schedules
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Funk-Klocko-190 Tour",
"email": "tour@example.com",
"phone_number": "(555) 555-1234",
"starts_at": "2020-12-14T12:00:00Z"
},
"type": "tour_schedules",
"relationships": null
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "10",
"type": "tour_schedules",
"attributes": {
"name": "Funk-Klocko-190 Tour",
"email": "tour@example.com",
"starts_at": "2020-12-14T12:00:00Z",
"ends_at": "2020-12-14T13:00:00Z",
"uuid": "e343acdf-06f7-4fd7-849f-a8637604039a",
"status": "confirmed",
"qr_key_public_url": "http://user.butterflymx.test/public/funk-klocko-190/virtual_keys/39/b0d420fe3982af7e215eb5b5c90e2ba4",
"pin": "892274",
"qr_key_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/qr_code_20201214-1020-828a3j.png",
"phone_number": "(555) 555-1234",
"building_handle": "funk-klocko-190",
"building_name": "Funk-Klocko-190",
"building_address": {
"country": "us",
"address_1": "604 Conn Grove",
"address_2": "Romagueraside, LA 68501-9973",
"city": "Romagueraside",
"state": "Louisiana",
"zip_code": "68501-9973",
"phone_number": "(727) 944-9106 x4951"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/e343acdf-06f7-4fd7-849f-a8637604039a",
"keychains": [],
"key_locker_in_use": false
}
}
}POST /v3/tours/kozey-bradtke-and-langosh-192/tour_schedules
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonBody
{
"data": {
"attributes": {
"name": "Kozey, Bradtke and Langosh-192 Tour ",
"email": "tour@example.com",
"starts_at": "2020-12-15T11:00:00Z"
},
"type": "tour_schedules",
"relationships": null
}
}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: funk-klocko-190
GET /v3/tours/49040d35-8bd7-4ba3-a9ee-865b60364b8d
Requests
GET /v3/tours/49040d35-8bd7-4ba3-a9ee-865b60364b8d
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": "49040d35-8bd7-4ba3-a9ee-865b60364b8d",
"status": "confirmed",
"qr_key_public_url": null,
"pin": null,
"qr_key_image_url": null,
"phone_number": "864.205.0010",
"building_handle": "kub-llc-194",
"building_name": "Kub LLC-194",
"building_address": {
"country": "us",
"address_1": "636 Cronin Estates",
"address_2": "Port Lloyd, AL 70551-8106",
"city": "Port Lloyd",
"state": "Alabama",
"zip_code": "70551-8106",
"phone_number": "1-443-330-4141 x168"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/49040d35-8bd7-4ba3-a9ee-865b60364b8d",
"keychains": [],
"key_locker_in_use": false
}
}
}ShowGET/v3/tours/{uuid}
URI Parameters
- uuid
string(required) Example: 49040d35-8bd7-4ba3-a9ee-865b60364b8d
PATCH /v3/tours/314b95d7-9a06-4a84-9328-39250572bd58
Requests
PATCH /v3/tours/314b95d7-9a06-4a84-9328-39250572bd58
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": "314b95d7-9a06-4a84-9328-39250572bd58",
"status": "rescheduled",
"qr_key_public_url": "http://user.butterflymx.test/public/ernser-borer-196/virtual_keys/40/2a9a993b8c07d4d82f03d5d94db35d9c",
"pin": "687879",
"qr_key_image_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1679485633-4ec56a19407de66fbee45e716e35bfc7/store/medium/qr_code_20201214-1020-15ptoms.png",
"phone_number": "779-379-4810 x5638",
"building_handle": "ernser-borer-196",
"building_name": "Ernser-Borer-196",
"building_address": {
"country": "us",
"address_1": "801 Champlin Mills",
"address_2": "Gabriellestad, WY 94650",
"city": "Gabriellestad",
"state": "Wyoming",
"zip_code": "94650",
"phone_number": "144-994-6521 x5559"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/314b95d7-9a06-4a84-9328-39250572bd58",
"keychains": [],
"key_locker_in_use": false
}
}
}UpdatePATCH/v3/tours/{uuid}
URI Parameters
- uuid
string(required) Example: 314b95d7-9a06-4a84-9328-39250572bd58
DELETE /v3/tours/c0a05911-2270-49ab-8e50-26566d87439d
Requests
DELETE /v3/tours/c0a05911-2270-49ab-8e50-26566d87439d
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": "c0a05911-2270-49ab-8e50-26566d87439d",
"status": "cancelled",
"qr_key_public_url": null,
"pin": null,
"qr_key_image_url": null,
"phone_number": "(361) 047-8999 x1508",
"building_handle": "torp-mueller-and-white-198",
"building_name": "Torp, Mueller and White-198",
"building_address": {
"country": "us",
"address_1": "1862 Zieme Centers",
"address_2": "Harlandburgh, LA 86478",
"city": "Harlandburgh",
"state": "Louisiana",
"zip_code": "86478",
"phone_number": "(100) 663-1417 x895"
},
"tour_units": [],
"day_of_tour_url": "http://selftours.butterflymx.test/tour/c0a05911-2270-49ab-8e50-26566d87439d",
"keychains": [],
"key_locker_in_use": false
}
}
}DeleteDELETE/v3/tours/{uuid}
URI Parameters
- uuid
string(required) Example: c0a05911-2270-49ab-8e50-26566d87439d
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/843107473
Requests
GET /v3/units/843107473
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "843107473",
"type": "units",
"attributes": {
"kind": "residential",
"label": "56056",
"floor_number": 56
},
"relationships": {
"building": {
"data": {
"id": "577696462",
"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": "843107477",
"type": "units",
"attributes": {
"kind": "residential",
"label": "59059",
"floor_number": 59
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107476",
"type": "units",
"attributes": {
"kind": "residential",
"label": "58058",
"floor_number": 58
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107475",
"type": "units",
"attributes": {
"kind": "residential",
"label": "57057",
"floor_number": 57
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107474",
"type": "units",
"attributes": {
"kind": "residential",
"label": "00",
"floor_number": 0
},
"relationships": {
"building": {
"data": {
"id": "577696464",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/units?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/units?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/units?page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}GET /v3/units?include=users,building
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": [
{
"id": "843107481",
"type": "units",
"attributes": {
"kind": "residential",
"label": "62062",
"floor_number": 62
},
"relationships": {
"building": {
"data": {
"id": "577696465",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107480",
"type": "units",
"attributes": {
"kind": "residential",
"label": "61061",
"floor_number": 61
},
"relationships": {
"building": {
"data": {
"id": "577696465",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107479",
"type": "units",
"attributes": {
"kind": "residential",
"label": "60060",
"floor_number": 60
},
"relationships": {
"building": {
"data": {
"id": "577696465",
"type": "buildings"
}
},
"users": {
"data": []
}
}
},
{
"id": "843107478",
"type": "units",
"attributes": {
"kind": "residential",
"label": "00",
"floor_number": 0
},
"relationships": {
"building": {
"data": {
"id": "577696465",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
],
"included": [
{
"id": "577696465",
"type": "buildings",
"attributes": {
"name": "Gibson-Wuckert-203",
"building_type": "multi_family",
"display_name_strategy": "first_name_and_last_name",
"nfc_enabled": false,
"send_panel_status_report": false,
"mobile_logo_picture": {
"thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
"medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
},
"panel_logo_picture": {
"thumb_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png",
"medium_url": "/assets/BMX_logo-950095e4e7500998fa6993f28f8950cba6f2322a76806abb7820fa39eb6394b6.png"
},
"address_1": "890 Kuhn Plains",
"address_2": "North Rickmouth, OR 96362",
"city": "North Rickmouth",
"state": "Oregon",
"zip_code": "96362",
"phone_number": "(125) 346-0118 x8652",
"country": "us",
"qr_key_enabled": true,
"time_zone": "Etc/UTC",
"time_zone_offset": "+00:00",
"delivery_pass_enabled": true,
"door_release_pin": true,
"open_door_button_enabled": true
}
}
],
"links": {
"self": "http://api.butterflymx.com/v3/units?include=users%2Cbuilding&page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://api.butterflymx.com/v3/units?include=users%2Cbuilding&page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://api.butterflymx.com/v3/units?include=users%2Cbuilding&page%5Bnumber%5D=1&page%5Bsize%5D=20"
}
}ListGET/v3/units
POST /v3/buildings/577696466/units
Requests
POST /v3/buildings/577696466/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": "843107483",
"type": "units",
"attributes": {
"kind": "residential",
"label": "foo",
"floor_number": 11
},
"relationships": {
"building": {
"data": {
"id": "577696466",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
}POST /v3/buildings/577696467/units
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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: 577696466
PUT /v3/units/843107488
Requests
PUT /v3/units/843107488
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": 577696469
}
}
}Responses
Headers
Content-Type: application/vnd.api+json; charset=utf-8Body
{
"data": {
"id": "843107488",
"type": "units",
"attributes": {
"kind": "residential",
"label": "New Label",
"floor_number": 11
},
"relationships": {
"building": {
"data": {
"id": "577696469",
"type": "buildings"
}
},
"users": {
"data": []
}
}
}
}PUT /v3/units/843107491
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+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/843107494
Requests
DELETE /v3/units/843107494
Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+jsonResponses
This response has no content.
Generated by aglio on 22 Mar 2023