ButterflyMX API V3

API Endpoint

OAuth2 Authentication

ButterflyMX API V3 implements Resource Owner Credentials (Password) Flow with refresh_token

Obtaining access_token

To obtain a valid access_token and refresh_token, you can send your $CLIENT_ID and Resource Owner’s $USERNAME and $PASSWORD

curl -X POST "https://accountstest.butterflymx.com/oauth/token" \
  -d grant_type=password \
  -d client_id=$CLIENT_ID \
  --data-urlencode "username=$USERNAME"\
  --data-urlencode "password=$PASSWORD"

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:

{
  "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://accountstest.butterflymx.com/oauth/token" \
  -d grant_type=refresh_token \
  -d refresh_token=6d8cd1d...9f75 \
  -d client_id=$CLIENT_ID

Response sample in case of success:

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

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

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

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

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


User Password Change

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

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

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

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

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

  { "errors" : "Wrong password" }

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

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

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

User Roles

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

  • Tenant

  • Unit Admin

  • Zone Admin

  • Building Admin

Data Models

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

  • building has many zones

  • zone belongs to only one building

  • zone has many units

  • unit belongs to only one zone

  • user can be a tenant in many units

  • unit can have many tenants (users)

Building Data Model


JSON API Specification

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

Pagination

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

For example:

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

Sorting

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

Example:

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

Multiple Sort You can sort on multiple fields like this:

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

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

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

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

Multiple Sort with Descendant Sort

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

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

Filtering

Examples:

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

or

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

Check each resource to see which fields can be filtered.

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

Example:

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

You can read more about includes here

Buildings

Buildings

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

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

Fields that can be changed by the building admin:

  • name (String)

  • time_zone (String)

  • building_type (String)

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

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

  • panel_logo (File)

  • mobile_logo (File)

  • remove_panel_logo (Boolean)

  • remove_mobile_logo (Boolean)

  • qr_key_enabled (Boolean)

  • door_release_pin (String)

  • in_unit_phone_number (String)

  • address_1 (String)

  • address_2 (String)

  • city (String)

  • state (String)

  • zip_code (String)

  • phone_number (String)

  • country (String)

GET /v3/buildings
Requestsreturns the list of the buildings

GET  /v3/buildings

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "1",
      "type": "buildings",
      "attributes": {
        "name": "Pollich LLC-1",
        "building_type": "multi_family",
        "display_name_strategy": "first_name_initial_and_last_name",
        "door_release_pin": false,
        "qr_key_enabled": true,
        "nfc_enabled": false,
        "send_panel_status_report": false,
        "mobile_logo_picture": {
          "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
          "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
        },
        "panel_logo_picture": {
          "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
          "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
        },
        "address_1": "153 Herzog Centers",
        "address_2": "Sydneemouth, GA 84990-6024",
        "city": "Sydneemouth",
        "state": "Georgia",
        "zip_code": "84990-6024",
        "phone_number": "187-187-6033 x530",
        "country": "us",
        "time_zone": "Etc/UTC",
        "time_zone_offset": "+00:00"
      },
      "relationships": {
        "zones": {
          "data": [
            {
              "id": "1",
              "type": "zones"
            }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/buildings?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/buildings


GET /v3/buildings/3
Requestsreturns the building data

GET  /v3/buildings/3

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "3",
    "type": "buildings",
    "attributes": {
      "name": "Bailey, Orn and Carroll-3",
      "building_type": "multi_family",
      "display_name_strategy": "first_name_and_last_name_initial",
      "door_release_pin": false,
      "qr_key_enabled": true,
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "address_1": "9445 Jamison Ramp",
      "address_2": "West Garfieldbury, MI 78136-4313",
      "city": "West Garfieldbury",
      "state": "Michigan",
      "zip_code": "78136-4313",
      "phone_number": "1-183-533-5857",
      "country": "us",
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00"
    },
    "relationships": {
      "zones": {
        "data": [
          {
            "id": "3",
            "type": "zones"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "3",
      "type": "zones",
      "attributes": {
        "name": "default"
      }
    }
  ]
}

Show
GET/v3/buildings/{id}

URI Parameters
HideShow
id
number (required) Example: 3

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

PATCH  /v3/buildings/5

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "buildings",
    "id": "5",
    "attributes": {
      "name": "My Building",
      "building_type": "commercial_office",
      "display_name_strategy": "first_name_and_last_name",
      "door_release_pin": false,
      "qr_key_enabled": false,
      "send_panel_status_report": true,
      "time_zone": "Eastern Time (US & Canada)"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "5",
    "type": "buildings",
    "attributes": {
      "name": "My Building",
      "building_type": "commercial_office",
      "display_name_strategy": "first_name_and_last_name",
      "door_release_pin": false,
      "qr_key_enabled": false,
      "nfc_enabled": false,
      "send_panel_status_report": true,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "address_1": "7750 Spinka Falls",
      "address_2": "North Queenburgh, NC 84921",
      "city": "North Queenburgh",
      "state": "North Carolina",
      "zip_code": "84921",
      "phone_number": "1-879-159-0969 x5325",
      "country": "us",
      "time_zone": "Eastern Time (US & Canada)",
      "time_zone_offset": "-04:00"
    },
    "relationships": {
      "zones": {
        "data": [
          {
            "id": "5",
            "type": "zones"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "5",
      "type": "zones",
      "attributes": {
        "name": "default"
      }
    }
  ]
}

PATCH  /v3/buildings/7

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "buildings",
    "id": "7",
    "attributes": {
      "address_1": "New Building Address"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "7",
    "type": "buildings",
    "attributes": {
      "name": "Robel, Buckridge and Rolfson-7",
      "building_type": "multi_family",
      "display_name_strategy": "first_name_and_last_name_initial",
      "door_release_pin": false,
      "qr_key_enabled": true,
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "address_1": "New Building Address",
      "address_2": "Litzyville, SD 23076-9225",
      "city": "Litzyville",
      "state": "South Dakota",
      "zip_code": "23076-9225",
      "phone_number": "(486) 040-8493 x5467",
      "country": "us",
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00"
    },
    "relationships": {
      "zones": {
        "data": [
          {
            "id": "7",
            "type": "zones"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "7",
      "type": "zones",
      "attributes": {
        "name": "default"
      }
    }
  ]
}

PATCH  /v3/buildings/9

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

PATCH  /v3/buildings/11

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "attributes": {
      "remove_panel_logo": true
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "11",
    "type": "buildings",
    "attributes": {
      "name": "Denesik, Stroman and Koch-11",
      "building_type": "multi_family",
      "display_name_strategy": "first_name_and_last_name_initial",
      "door_release_pin": false,
      "qr_key_enabled": true,
      "nfc_enabled": false,
      "send_panel_status_report": false,
      "mobile_logo_picture": {
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb_small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium_small_picture.jpg"
      },
      "panel_logo_picture": {
        "thumb_url": null,
        "medium_url": null
      },
      "address_1": "42993 Fritsch Route",
      "address_2": "Port Bernitashire, WI 31950-6690",
      "city": "Port Bernitashire",
      "state": "Wisconsin",
      "zip_code": "31950-6690",
      "phone_number": "1-683-189-8087 x868",
      "country": "us",
      "time_zone": "Etc/UTC",
      "time_zone_offset": "+00:00"
    },
    "relationships": {
      "zones": {
        "data": [
          {
            "id": "11",
            "type": "zones"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "11",
      "type": "zones",
      "attributes": {
        "name": "default"
      }
    }
  ]
}

Update
PATCH/v3/buildings/{id}

URI Parameters
HideShow
id
number (required) Example: 5

Current User

Calls

Sortable fields:

  • created_at

  • logged_at

  • notification_type

  • call_type

Filterable fields:

  • unit -> integer

  • notification_type -> enum(string)

  • call_type -> enum(string)

  • guid -> string

Enumerations:

  • call_type:

    • voip
    • mobile
  • notification_type:

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

GET  /v3/me/calls

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "3",
      "type": "calls",
      "attributes": {
        "guid": "f5ad4238-2698-4be7-97f2-33354c4ee68c",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:49Z",
        "logged_at": "2019-03-28T14:37:49Z"
      }
    },
    {
      "id": "2",
      "type": "calls",
      "attributes": {
        "guid": "4983bcbd-6e85-49a7-ade4-420f7172dc3e",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:49Z",
        "logged_at": "2019-03-28T14:37:49Z"
      }
    },
    {
      "id": "1",
      "type": "calls",
      "attributes": {
        "guid": "947911ac-3c0c-4dc3-9f1a-b05f100a1c00",
        "call_type": "voip",
        "notification_type": "visitor",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:48Z",
        "logged_at": "2019-03-28T14:37:48Z"
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/me/calls?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

Calls
GET/v3/me/calls


Door Releases

Sortable fields:

  • created_at

  • logged_at

  • notification_type

  • call_type

Filterable fields:

  • unit -> integer

  • release_method -> enum

  • door_release_type -> enum

  • name -> string

  • call_guid -> string

Enumerations:

  • release_method:

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

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

GET  /v3/me/door_releases

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "3",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "call_guid": "56916b17-ad87-467d-af23-d2fde95b6a36",
        "name": "Evan Olson",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/small_picture.jpg",
        "created_at": "2019-03-28T14:37:50Z"
      }
    },
    {
      "id": "2",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "call_guid": "4ae4cd99-6b76-4f86-94bf-ef6afbcff9e0",
        "name": "Evan Olson",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/small_picture.jpg",
        "created_at": "2019-03-28T14:37:50Z"
      }
    },
    {
      "id": "1",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "call_guid": "46d9c1ad-e284-4c37-8f08-427e2da0c719",
        "name": "Evan Olson",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/small_picture.jpg",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/small_picture.jpg",
        "created_at": "2019-03-28T14:37:49Z"
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/me/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

Door Releases
GET/v3/me/door_releases


Messages

Sortable fields:

  • message_type

  • created_at

Filterable fields:

  • message_type -> enum

Enumerations:

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

GET  /v3/me/messages

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

Messages
GET/v3/me/messages


User

Resources that can be included:

  • buildings

  • units

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

GET  /v3/me

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "16",
    "type": "users",
    "attributes": {
      "name": "Velva Schumm",
      "first_name": "Velva",
      "last_name": "Schumm",
      "contact_preference": "phone_call",
      "thumb_url": null,
      "medium_url": null,
      "email": "giles@fadeltromp.co",
      "sms_phone_number": null,
      "phone_number": null
    },
    "relationships": {
      "units": {
        "data": [
          {
            "id": "22",
            "type": "units"
          }
        ]
      },
      "buildings": {
        "data": [
          {
            "id": "22",
            "type": "buildings"
          }
        ]
      }
    }
  }
}

GET  /v3/me?include=buildings,units

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "17",
    "type": "users",
    "attributes": {
      "name": "Ulices Abshire",
      "first_name": "Ulices",
      "last_name": "Abshire",
      "contact_preference": "phone_call",
      "thumb_url": null,
      "medium_url": null,
      "email": "rosalee@satterfield.net",
      "sms_phone_number": null,
      "phone_number": null
    },
    "relationships": {
      "units": {
        "data": [
          {
            "id": "23",
            "type": "units"
          }
        ]
      },
      "buildings": {
        "data": [
          {
            "id": "26",
            "type": "buildings"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "23",
      "type": "units",
      "attributes": {
        "unit_type": "apartment",
        "label": "23023",
        "floor_number": 23
      }
    },
    {
      "id": "26",
      "type": "buildings",
      "attributes": {
        "name": "Howell-Stiedemann-26",
        "building_type": "multi_family",
        "mobile_logo_picture": {
          "thumb_url": null,
          "medium_url": null
        },
        "panel_logo_picture": {
          "thumb_url": null,
          "medium_url": null
        },
        "address_1": "8189 Gutmann Park",
        "address_2": "Strackeburgh, MO 16632-4206",
        "city": "Strackeburgh",
        "state": "Missouri",
        "zip_code": "16632-4206",
        "phone_number": "534.444.0034 x5029",
        "country": "us",
        "time_zone": "Etc/UTC"
      }
    }
  ]
}

Show
GET/v3/me


PUT /v3/me
Requestsupdates the current userreturns bad request

PUT  /v3/me

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "tenants",
    "id": "18",
    "attributes": {
      "last_name": "Baker"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "18",
    "type": "users",
    "attributes": {
      "name": "Bart Baker",
      "first_name": "Bart",
      "last_name": "Baker",
      "contact_preference": "phone_call",
      "thumb_url": null,
      "medium_url": null,
      "email": "estefania@gorczanybotsford.com",
      "sms_phone_number": null,
      "phone_number": null
    },
    "relationships": {
      "units": {
        "data": [
          {
            "id": "24",
            "type": "units"
          }
        ]
      },
      "buildings": {
        "data": [
          {
            "id": "30",
            "type": "buildings"
          }
        ]
      }
    }
  }
}

PUT  /v3/me

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

Update
PUT/v3/me


Door Releases

Door Releases

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

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

Request Samples with Filter:

GET /v3/door_releases?unit_id=11

GET /v3/door_releases?user_id=22

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

GET /v3/door_releases?door_release_type=delivery


Request Samples with Sort:

GET /v3/door_releases?sort=created

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

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


Allowed values for:

  • release_method:

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

    • visitor
    • delivery
  • panel_user_type:

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

GET  /v3/door_releases

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "27",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "doorman",
        "call_guid": "ce2be75b-4c20-472f-95b4-9c7379a4db53",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "26",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "doorman",
        "call_guid": "d0168ecf-31f8-4054-b42d-9c34a6c94c98",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "25",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "6b0a7f66-32ec-4414-9fa5-c748c81a5b8f",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "24",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "0112a79f-09f7-41a8-b5ca-1ddb404e6f29",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "23",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "delivery",
        "panel_user_type": "default",
        "call_guid": "85dee216-07e4-4ef0-afc0-e0d0f68163e6",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "22",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "delivery",
        "panel_user_type": "default",
        "call_guid": "323b8b84-facc-4408-824f-1add8bd1067b",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "21",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "a9f2424a-4bfb-4099-898c-dac7af359995",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "20",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "2eb62a4a-14ce-4af4-8582-3e31758d6733",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "19",
      "type": "door_releases",
      "attributes": {
        "release_method": "qr_key",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "26594977-6b7c-40d9-8409-4ff17e6ee562",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "18",
      "type": "door_releases",
      "attributes": {
        "release_method": "qr_key",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "c65038bc-3786-427d-b73a-8db3d3fd3c82",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "17",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "3786cd2e-fe18-4bfb-b973-1d658f106c39",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "16",
      "type": "door_releases",
      "attributes": {
        "release_method": "mobile",
        "door_release_type": "visitor",
        "panel_user_type": "default",
        "call_guid": "2cfe5863-0256-47d2-b9c0-57edd37825fe",
        "name": "Maverick Barton",
        "thumb_url": null,
        "medium_url": null,
        "created_at": "2019-03-28T14:37:55Z"
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "26",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "20",
            "type": "users"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/door_releases?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/door_releases


Tenants

Tenants

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

Assign User to the Unit as a Tenant

A user is assigned as a unit’s tenant by creating a units-users relationship. This can be achieved with API call: POST /v3/units/:unit_id/users

Required Attributes:

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

  • first_name (String)

  • last_name (String)

Optional Attributes:

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

  • inactive_at (DateTime)

  • pin (String)

  • directory_message (String)

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

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

  • email_notifications (boolean)

  • do_not_disturb (boolean)

When a valid email is submitted, then:

  • if there is no registered user in ButterflyMX having this email, a new user will be created and added as a tenant

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

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

GET /v3/units/71/users
Requestslist the unit's tenants

GET  /v3/units/71/users

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "71",
      "type": "units_users",
      "attributes": {
        "active_at": "2019-03-28T14:38:10Z",
        "inactive_at": null,
        "qr_key_enabled": true,
        "directory_message": "Lead Research Liaison",
        "display_name": "Luigi Trantow",
        "display_name_strategy": "building",
        "display_only_on_search": false,
        "pin_enabled": false,
        "pin": null,
        "email_notifications": true,
        "sms_notifications": true,
        "do_not_disturb": false
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "72",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "48",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "70",
      "type": "units_users",
      "attributes": {
        "active_at": "2019-03-28T14:38:10Z",
        "inactive_at": null,
        "qr_key_enabled": true,
        "directory_message": "Lead Infrastructure Director",
        "display_name": "Werner Hirthe",
        "display_name_strategy": "building",
        "display_only_on_search": false,
        "pin_enabled": false,
        "pin": null,
        "email_notifications": true,
        "sms_notifications": true,
        "do_not_disturb": false
      },
      "relationships": {
        "unit": {
          "data": {
            "id": "71",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "47",
            "type": "users"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "48",
      "type": "users",
      "attributes": {
        "name": "Ellis Hermiston",
        "first_name": "Ellis",
        "last_name": "Hermiston",
        "contact_preference": "phone_call",
        "email": "annabelle.little@oreillygreen.com",
        "sms_phone_number": null,
        "phone_number": null,
        "avatar": {
          "thumb_url": null,
          "medium_url": null
        }
      }
    },
    {
      "id": "47",
      "type": "users",
      "attributes": {
        "name": "Lupe Schoen",
        "first_name": "Lupe",
        "last_name": "Schoen",
        "contact_preference": "phone_call",
        "email": "lexie@dach.com",
        "sms_phone_number": null,
        "phone_number": null,
        "avatar": {
          "thumb_url": null,
          "medium_url": null
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/units/71/users?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/units/71/users?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/units/71/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/units/{unit_id}/users

URI Parameters
HideShow
unit_id
number (required) Example: 71

POST /v3/units/73/users
Requestscreates the user

POST  /v3/units/73/users

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units_users",
    "attributes": {
      "email": "vivien@ortizhahn.name",
      "first_name": "Nova",
      "last_name": "Champlin",
      "active_at": "2017-12-27T11:03:50Z",
      "pin": "12345",
      "directory_message": "Hi",
      "sms_notifications": true,
      "email_notifications": true,
      "do_not_disturb": false
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "75",
    "type": "units_users",
    "attributes": {
      "active_at": "2017-12-27T11:03:50Z",
      "inactive_at": null,
      "qr_key_enabled": true,
      "directory_message": "Hi",
      "display_name": "Nova C.",
      "display_name_strategy": "building",
      "display_only_on_search": false,
      "pin_enabled": false,
      "pin": "12345",
      "email_notifications": true,
      "sms_notifications": true,
      "do_not_disturb": false
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "73",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "51",
          "type": "users"
        }
      }
    }
  }
}

Create
POST/v3/units/{unit_id}/users

URI Parameters
HideShow
unit_id
number (required) Example: 73

PATCH /v3/units/76/users/52
Requestsupdates the tenant preferences

PATCH  /v3/units/76/users/52

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units_users",
    "attributes": {
      "inactive_at": "2019-03-29T14:38:11Z",
      "pin": "54321",
      "directory_message": "foo",
      "sms_notifications": true,
      "email_notifications": true,
      "do_not_disturb": false
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "76",
    "type": "units_users",
    "attributes": {
      "active_at": "2019-03-28T14:38:11Z",
      "inactive_at": "2019-03-29T14:38:11Z",
      "qr_key_enabled": true,
      "directory_message": "foo",
      "display_name": "Aileen Schmitt",
      "display_name_strategy": "building",
      "display_only_on_search": false,
      "pin_enabled": false,
      "pin": "54321",
      "email_notifications": true,
      "sms_notifications": true,
      "do_not_disturb": false
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "76",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "52",
          "type": "users"
        }
      }
    }
  }
}

Update
PATCH/v3/units/{unit_id}/users/{user_id}

URI Parameters
HideShow
unit_id
number (required) Example: 76
user_id
number (required) Example: 52

DELETE /v3/units/79/users/54
Requestsremoves the tenant from the unit

DELETE  /v3/units/79/users/54

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

Delete
DELETE/v3/units/{unit_id}/users/{user_id}

URI Parameters
HideShow
unit_id
number (required) Example: 79
user_id
number (required) Example: 54

Units

Units

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

Allowed Values for unit_type:

  • apartment
GET /v3/units
Requestsreturns units where user is tenant

GET  /v3/units

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "57",
      "type": "units",
      "attributes": {
        "unit_type": "apartment",
        "label": "57057",
        "floor_number": 57
      },
      "relationships": {
        "zone": {
          "data": {
            "id": "64",
            "type": "zones"
          }
        },
        "building": {
          "data": {
            "id": "56",
            "type": "buildings"
          }
        },
        "users": {
          "data": [
            {
              "id": "39",
              "type": "users"
            }
          ]
        }
      }
    },
    {
      "id": "54",
      "type": "units",
      "attributes": {
        "unit_type": "apartment",
        "label": "54054",
        "floor_number": 54
      },
      "relationships": {
        "zone": {
          "data": {
            "id": "64",
            "type": "zones"
          }
        },
        "building": {
          "data": {
            "id": "56",
            "type": "buildings"
          }
        },
        "users": {
          "data": [
            {
              "id": "39",
              "type": "users"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "64",
      "type": "zones",
      "attributes": {
        "name": "default"
      }
    },
    {
      "id": "39",
      "type": "users",
      "attributes": {
        "name": "Ray Green",
        "first_name": "Ray",
        "last_name": "Green",
        "contact_preference": "phone_call",
        "email": "susan.cremin@okuneva.org",
        "sms_phone_number": null,
        "phone_number": null,
        "avatar": {
          "thumb_url": null,
          "medium_url": null
        }
      }
    }
  ],
  "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"
  }
}

List
GET/v3/units


GET /v3/units/58
Requestsreturns the unit data

GET  /v3/units/58

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "58",
    "type": "units",
    "attributes": {
      "unit_type": "apartment",
      "label": "58058",
      "floor_number": 58
    },
    "relationships": {
      "zone": {
        "data": {
          "id": "66",
          "type": "zones"
        }
      },
      "building": {
        "data": {
          "id": "58",
          "type": "buildings"
        }
      },
      "users": {
        "data": [
          {
            "id": "41",
            "type": "users"
          }
        ]
      }
    }
  }
}

Show
GET/v3/units/{id}

URI Parameters
HideShow
id
number (required) Example: 58

POST /v3/units
Requestscreates the unit

POST  /v3/units

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units",
    "attributes": {
      "unit_type": "apartment",
      "label": "foo",
      "floor_number": 11
    },
    "relationships": {
      "zone": {
        "data": {
          "id": "68"
        }
      }
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "66",
    "type": "units",
    "attributes": {
      "unit_type": "apartment",
      "label": "foo",
      "floor_number": 11
    },
    "relationships": {
      "zone": {
        "data": {
          "id": "68",
          "type": "zones"
        }
      },
      "building": {
        "data": {
          "id": "60",
          "type": "buildings"
        }
      },
      "users": {
        "data": []
      }
    }
  }
}

Create
POST/v3/units


PATCH /v3/units/67
Requestsupdates the unit

PATCH  /v3/units/67

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "units",
    "id": "67",
    "attributes": {
      "label": "updated"
    }
  }
}
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "67",
    "type": "units",
    "attributes": {
      "unit_type": "apartment",
      "label": "updated",
      "floor_number": 66
    },
    "relationships": {
      "zone": {
        "data": {
          "id": "70",
          "type": "zones"
        }
      },
      "building": {
        "data": {
          "id": "62",
          "type": "buildings"
        }
      },
      "users": {
        "data": [
          {
            "id": "45",
            "type": "users"
          }
        ]
      }
    }
  }
}

Update
PATCH/v3/units/{id}

URI Parameters
HideShow
id
number (required) Example: 67

Virtual Keys

Keychains

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

You can create a single QR Key, like this:

POST /v3/qr_keys HTTP/1.1
Authorization: Bearer eyJ0eXAi...TcV3Q
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "qr_keys",
    "attributes": {
      "name": "mykey",
      "email": "foo@bar.baz",
      "activated_at": "2017-11-29T21:01:00Z",
      "expired_at": "2017-11-29T21:06:00Z",
    },
    "relationships": {
      "unit": {"data": {"id": "11"}},
      "user": {"data": {"id": "22"}}
    }
  }
}

… or, you can create many QR Keys with the same properties (validity), by creating a keychain first, like this:

POST /v3/keychains HTTP/1.1
Authorization: Bearer eyJ0eXAi...TcV3Q
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "keychains",
    "attributes": {
      "name": "foo",
      "weekdays": ["mon","fri"],
      "valid_date_from": "2017-08-01",
      "valid_date_to": "2017-08-21",
      "valid_time_from": "11:00:00",
      "valid_time_to": "15:50:00",
    },
    "relationships": {
      "unit": {"data": {"id": "11"}},
      "user": {"data": {"id": "22"}}
    }
  }
}

… and then, add more qr_keys to that keychain, like this:

POST /v3/keychains/{keychain_id}/qr_keys HTTP/1.1
Authorization: Bearer eyJ0eXAi...TcV3Q
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "qr_keys",
    "attributes": {
      "name": "My Key",
      "email": "foo@bar.baz",
      "sms_number": "+15005550006"
    }
  }
}

Allowed Values for weekdays:

  • mon

  • tue

  • wed

  • thu

  • fri

  • sat

  • sun

Note: At least email or sms_number must be defined for a new QR Key.

GET /v3/keychains
Requestsreturns all keychains

GET  /v3/keychains

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "4",
      "type": "keychains",
      "attributes": {
        "name": "Investor Branding Supervisor 4",
        "weekdays": null,
        "valid_date_from": "2019-04-12",
        "valid_date_to": "2019-04-12",
        "valid_time_from": "10:00:00",
        "valid_time_to": "23:25:00"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "23",
            "type": "users"
          }
        },
        "unit": {
          "data": {
            "id": "30",
            "type": "units"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "keychains",
      "attributes": {
        "name": "Central Implementation Facilitator 3",
        "weekdays": null,
        "valid_date_from": "2019-03-18",
        "valid_date_to": "2019-04-12",
        "valid_time_from": "10:00:00",
        "valid_time_to": "23:25:00"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "23",
            "type": "users"
          }
        },
        "unit": {
          "data": {
            "id": "30",
            "type": "units"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "keychains",
      "attributes": {
        "name": "Future Markets Specialist 2",
        "weekdays": null,
        "valid_date_from": "2019-03-23",
        "valid_date_to": "2019-04-12",
        "valid_time_from": "10:00:00",
        "valid_time_to": "23:25:00"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "23",
            "type": "users"
          }
        },
        "unit": {
          "data": {
            "id": "30",
            "type": "units"
          }
        }
      }
    }
  ],
  "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"
  }
}

List
GET/v3/keychains


GET /v3/keychains/5
Requestsreturns the keychain data

GET  /v3/keychains/5

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "5",
    "type": "keychains",
    "attributes": {
      "name": "National Optimization Associate 5",
      "weekdays": null,
      "valid_date_from": "2019-03-23",
      "valid_date_to": "2019-04-12",
      "valid_time_from": "10:00:00",
      "valid_time_to": "23:25:00"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "25",
          "type": "users"
        }
      },
      "unit": {
        "data": {
          "id": "33",
          "type": "units"
        }
      }
    }
  }
}

Show
GET/v3/keychains/{id}

URI Parameters
HideShow
id
number (required) Example: 5

DELETE /v3/keychains/6
Requestsdestroys the keychain

DELETE  /v3/keychains/6

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

Delete
DELETE/v3/keychains/{id}

URI Parameters
HideShow
id
number (required) Example: 6

QR Keys

GET /v3/qr_keys
Requestsreturns all virtual keysreturns all virtual keys on the keychain

GET  /v3/qr_keys

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "4",
      "type": "qr_keys",
      "attributes": {
        "name": "Maxwell Dibbert",
        "email": "lolita@example.com",
        "sms_number": "+12546238565",
        "key_code": "zp8hzvs",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/qr_code_20190328-28093-jbm7d0.png",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/qr_code_20190328-28093-jbm7d0.png",
        "large_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/large/qr_code_20190328-28093-jbm7d0.png",
        "activated_at": "2019-04-12T10:00:00Z",
        "expired_at": "2019-04-12T23:25:00Z"
      },
      "relationships": {
        "keychain": {
          "data": {
            "id": "9",
            "type": "keychains"
          }
        },
        "unit": {
          "data": {
            "id": "39",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "29",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "qr_keys",
      "attributes": {
        "name": "Naomie Shields",
        "email": "julie@example.net",
        "sms_number": "+12546275580",
        "key_code": "vrh1bfl",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/qr_code_20190328-28093-kk7k0b.png",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/qr_code_20190328-28093-kk7k0b.png",
        "large_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/large/qr_code_20190328-28093-kk7k0b.png",
        "activated_at": "2019-03-18T10:00:00Z",
        "expired_at": "2019-04-12T23:25:00Z"
      },
      "relationships": {
        "keychain": {
          "data": {
            "id": "8",
            "type": "keychains"
          }
        },
        "unit": {
          "data": {
            "id": "39",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "29",
            "type": "users"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "qr_keys",
      "attributes": {
        "name": "Emmet Dooley Sr.",
        "email": "deanna_wunsch@example.com",
        "sms_number": "+12546218514",
        "key_code": "5tob86y",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/qr_code_20190328-28093-1jway9l.png",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/qr_code_20190328-28093-1jway9l.png",
        "large_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/large/qr_code_20190328-28093-1jway9l.png",
        "activated_at": "2019-03-23T10:00:00Z",
        "expired_at": "2019-04-12T23:25:00Z"
      },
      "relationships": {
        "keychain": {
          "data": {
            "id": "7",
            "type": "keychains"
          }
        },
        "unit": {
          "data": {
            "id": "39",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "29",
            "type": "users"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/qr_keys?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/qr_keys?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/qr_keys?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

GET  /v3/keychains/10/qr_keys

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": [
    {
      "id": "5",
      "type": "qr_keys",
      "attributes": {
        "name": "Holly Bergstrom DDS",
        "email": "eloy@example.com",
        "sms_number": "+12546255150",
        "key_code": "ti997df",
        "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/qr_code_20190328-28093-7e37c8.png",
        "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/qr_code_20190328-28093-7e37c8.png",
        "large_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/large/qr_code_20190328-28093-7e37c8.png",
        "activated_at": "2019-03-23T10:00:00Z",
        "expired_at": "2019-04-12T23:25:00Z"
      },
      "relationships": {
        "keychain": {
          "data": {
            "id": "10",
            "type": "keychains"
          }
        },
        "unit": {
          "data": {
            "id": "42",
            "type": "units"
          }
        },
        "user": {
          "data": {
            "id": "31",
            "type": "users"
          }
        }
      }
    }
  ],
  "links": {
    "self": "http://api.butterflymx.com/v3/keychains/10/qr_keys?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://api.butterflymx.com/v3/keychains/10/qr_keys?page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://api.butterflymx.com/v3/keychains/10/qr_keys?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  }
}

List
GET/v3/qr_keys


GET /v3/qr_keys/8
Requestsreturns the key data

GET  /v3/qr_keys/8

Headers
Accept: application/vnd.api+json
Responses200
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "8",
    "type": "qr_keys",
    "attributes": {
      "name": "Dr. Molly Greenfelder",
      "email": "madisyn_murray@example.org",
      "sms_number": "+12546294336",
      "key_code": "jf0cvpd",
      "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/qr_code_20190328-28093-jadwv3.png",
      "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/qr_code_20190328-28093-jadwv3.png",
      "large_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/large/qr_code_20190328-28093-jadwv3.png",
      "activated_at": "2019-03-23T10:00:00Z",
      "expired_at": "2019-04-12T23:25:00Z"
    },
    "relationships": {
      "keychain": {
        "data": {
          "id": "13",
          "type": "keychains"
        }
      },
      "unit": {
        "data": {
          "id": "45",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "33",
          "type": "users"
        }
      }
    }
  }
}

Show
GET/v3/qr_keys/{id}

URI Parameters
HideShow
id
number (required) Example: 8

POST /v3/keychains/14/qr_keys
Requestscreates the key

POST  /v3/keychains/14/qr_keys

Headers
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Body
{
  "data": {
    "type": "qr_keys",
    "attributes": {
      "name": "mykey",
      "email": "foo@bar.baz",
      "activated_at": "2017-11-29T21:01:00",
      "expired_at": "2017-11-29T21:06:00"
    },
    "relationships": {
      "unit": {
        "data": {
          "id": "48"
        }
      },
      "user": {
        "data": {
          "id": "35"
        }
      }
    }
  }
}
Responses201
Headers
Content-Type: application/vnd.api+json; charset=utf-8
Body
{
  "data": {
    "id": "10",
    "type": "qr_keys",
    "attributes": {
      "name": "mykey",
      "email": "foo@bar.baz",
      "sms_number": null,
      "key_code": "lq8hjy3",
      "thumb_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/thumb/qr_code_20190328-28093-50ngif.png",
      "medium_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/medium/qr_code_20190328-28093-50ngif.png",
      "large_url": "https://bmx-rails-staging.s3.amazonaws.com/system/uploads/test-1-1553783861-9fac8fbee88489899c0d8aca5bc57616/store/large/qr_code_20190328-28093-50ngif.png",
      "activated_at": "2019-03-23T10:00:00Z",
      "expired_at": "2019-04-12T23:25:00Z"
    },
    "relationships": {
      "keychain": {
        "data": {
          "id": "14",
          "type": "keychains"
        }
      },
      "unit": {
        "data": {
          "id": "48",
          "type": "units"
        }
      },
      "user": {
        "data": {
          "id": "35",
          "type": "users"
        }
      }
    }
  }
}

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

URI Parameters
HideShow
keychain_id
number (required) Example: 14

DELETE /v3/qr_keys/11
Requestsdestroys the key

DELETE  /v3/qr_keys/11

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

Delete
DELETE/v3/qr_keys/{id}

URI Parameters
HideShow
id
number (required) Example: 11

Generated by aglio on 28 Mar 2019