This FAQ contains answers to and resources for common questions partners have about ButterflyMX setup, testing, and usage. This document will also help you troubleshoot some common API errors.
If you continue to run into issues after reading this FAQ, please email [email protected] for further assistance.
This FAQ will help you:
- Set up partner accounts
- Set up ButterflyMX accounts
- Set up ButterflyMX emulation software
- Understand the difference between ButterflyMX account types and how they relate to API permissions
- Configure environments and ButterflyMX panel software
- Use the API and SDK
- Troubleshoot common issues
Building Admin Account: One of the roles a ButterflyMX user can be associated with. Integrations that use building-level APIs will need to authorize using a Building Admin Account account as Resource Owner.
Tenant Account = Integrations that use tenant-level APIs will need to authorize using a Tenant Account as Resource Owner.
Unit Admin (not currently available)
Zone Admin (not currently available)
GUI = Graphical User Interface. In ButterflyMX parlance, it is often used to mean the touchscreen interface of the intercom
VCAM2 = version 2 of the virtual camera software
VCAM3 = version 3 of the virtual camera software
You’ll find many answers to FAQs about configuring and using our desktop property management dashboard and our mobile app using the links below. We recommend that you start here first:
We can install our intercom software on a Windows machine for you. Please contact [email protected] with your request.
We recommend you use a laptop with a built-in camera and the Windows 10 OS.
You'll need to install TeamViewer and provide us with your TeamViewer ID and password.
We don't support installations of the panel software on virtual machines
This depends on your use cases and the endpoints your use cases require. For example, here are the permissions associated with the building-level and door releases APIs
A partner is limited to one set of client IDs and secrets for each production environment. You will only be provided with one set for the Sandbox environment and another set for the Production environment.
Will the API access provided by the one client ID and secret that we receive be able to access all of the buildings we integrate with?
Your one client/secret pair will provide access to all of the resources to which you have access.
For the sandbox environment, your ButterflyMX partner contact can create as many Building Admin Accounts as needed. Each admin account can be used to retrieve access, refresh tokens, or work with any other API. For example, Building Admin Accounts in the sandbox environment can also create virtual keys or show a list of units.
For the production environment, partners will be provided with only one Building Admin Account per building if the integration requires that level of access.
Building Admin Accounts in both environments cannot create other Building Admin Accounts, but they can freely create tenant accounts. More details on managing users in our admin console can be found in the "Training Videos" section of this page: https://butterflymx.com/resources/property-managers/
Once an integration has been approved by ButterflyMX, we will provide you with a link to a form. You can then pass this form to building staff to request an integration activation. Once the individual property has approved the integration via this form, ButterflyMX will turn on the integration for that single building.
Please contact your ButterflyMX technical support team in the shared Slack channel that has been set up or at [email protected] to have redirect URIs added for your application.
Does each tenant have to log in through the SDK flow for us to manage their calls? Or can we instead use admin credentials for everyone and pass the calls to a specific tenant?
Each tenant will have to log in individually. Calls and all other actions performed by tenants (like creating virtual keys or opening doors) should be handled using tenant accounts.
- No repetitive PINs — more than half of the PIN needs to be a unique digit. For example,143213 (4 unique digits in a 6-digit PIN) is fine, but 144214 is not (only 3 unique digits in a 6-digit PIN)
- No consecutive number sequences (123456, 98765, etc.)
- The PIN needs to be unique at the building level
Yes. PINs are synced to the mobile app and intercom as soon as they are created. So, the intercom will still recognize a PIN even without an active internet connection.
Can I create one virtual key that allows a user access across multiple buildings that have different ButterflyMX intercoms?
If the property with multiple buildings is setup in our system as a single "Building," one virtual key will have access to all of the intercoms associated with that single "Building." But if each physical building within the property is a different "Building" in our system, different virtual keys for each building will need to be used.
Our API allows you to create tenants, set PINS and specify start and end dates for when tenants will be active in the system.
With this functionality, you can:
- Create a placeholder unit.
- Assign the non-resident to that unit.
- Create your unique PIN for that resident.
ButterflyMX PINS are automatically sent via SMS and/or email if you include the recipient email address and the mobile phone number as part of your payload when you create a keychain.
Alternatively, if your use case involves sending the PINs via another channel, you should create a recipient keychain first, and then attach a recipient-less virtual key to that keychain using the virtual key endpoint, which will return a PIN code and QR code URL.
- opens a door for the current user - you need to pass a panelid
in aPOST` parameter
`GET /v3/me/door_releases` - returns all door release events for the current user. Door release event can be created by the tenant via the Open Door API or within a call and/or visitor using virtual key
`GET /v3/door_releases` - mostly used by admin accounts with filtering options
You can send
front_door_view as a
/test to the end of your login email if you're testing in the staging environment
/sandbox to the end of your login email if you're testing in the sandbox environment
For example, for the sandbox environment :
Username: [email protected]**/sandbox**
Do you allow tenants to connect multiple devices with their profile? For example, can I use both my iPhone and iPad to receive push notifications?
Can a tenant be associated with multiple units in the same property? For example, if a tenant is transferring units and has access to both apartments, or if a tenant is renting multiple units.
Yes. We allow users to have multiple tenancies. We define ‘tenant’ by considering both the user and the unit.
When a tenant is associated with multiple units, how do you handle elevator control for their associated unit floors?
We handle elevator control by associating the tenant with each unit separately. So, if a tenant resides in an additional unit, they will have an additional tenant entity in our system and will need separate elevator control access.
Can you push updates to us if: (1) a new ButterflyMX access point is added to a community (for example, my building just opened a new pool) or (2) a tenant's access is changed (i.e. John can no longer access the pool)?
We do not currently offer push updates for either of these things, but they might become available in the future. For now, you will we need to fetch the data from our API
No. This only happens when the preference is set to Mobile App.
If a contact is listed as a “phone call user”, does that mean a Session Initiation Protocol (SIP) call will not work?
Yes. In this case the call will be routed directly to the contact's cell phone.
Currently, only one device can be in a video call at a time.
Yes, you can use the following endpoint:
display_only_on_search as a value in the attributes section
Is there any API we can use to specify a building
id while fetching, and get the units for only that building?
idwhile fetching, and get the units for only that building?
Yes, you can use the filters here:
No, Building Admin Accounts cannot create buildings, and we restrict partner accounts to no higher access level than Building Admin access.
Yes, using the 'create-one-time keychain' in our virtual keys API
Can a Butterflymx unit be assigned to the company/community level? Or is it always assigned to a building?
A ButterflyMX unit is always assigned to a building.
What timezone should be used when we send data in API requests? The timezone of the building or another?
You should use the timezone of the building. Also, you should always use the iso8601 format when sending datetime data.
I'm unable to connect and receiving the message "Version Out of Date: Update The Remote Teamviewer Software"?
Please contact [email protected] with your Teamviewer ID and Password
How do I resolve a 404 error or a
"Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method" message?
"Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method"message?
- Please ensure that there are no URL typos in your request.
- Please ensure that you are using the correct URL in your request:
- If you are in the sandbox environment, you should be sending authentication requests to
- If you are in the staging environment, you should be sending authentication requests to
- If you are in the sandbox environment, you should be sending authentication requests to
Please ensure that you are using
https:// in your endpoint
"An unexpected error occurred while processing your request" when using the Integrations endpoints
"An unexpected error occurred while processing your request"when using the Integrations endpoints
Ensure that your
"url" parameter is something other than
Ensure that you are you are sending a
unit_id in the request. The system requires a unit ID in order to associate the key with a unit/tenant.
I am receiving the error
Error in ButterflyMX QR code generation ---- ButterflyMX: generate_onetime_keychain - /data/attributes/base QR Keys feature is not enabled for the building where unit belongs when there is an attempt to create a virtual key.
Error in ButterflyMX QR code generation ---- ButterflyMX: generate_onetime_keychain - /data/attributes/base QR Keys feature is not enabled for the building where unit belongswhen there is an attempt to create a virtual key.
This usually means that virtual keys have not been manually enabled for the building. Please contact your ButterflyMX technical support team in the shared Slack channel that has been set up, or at [email protected] to have that functionality enabled.
Updated almost 2 years ago