How to Create Pin with the ButterflyMX API in PHP

Introduction to ButterflyMX API

ButterflyMX is a cutting-edge property access solution that simplifies building entry for residents, visitors, and property staff. By integrating with ButterflyMX's API, developers can enhance property management systems by automating access control and visitor management processes.

Connecting with the ButterflyMX API allows developers to create and manage PINs for tenants, offering a seamless and secure entry experience. For example, a developer might want to automate the creation of unique access PINs for new tenants, ensuring they have immediate access to their units upon move-in.

Setting Up Your ButterflyMX Sandbox Account for API Integration

To begin working with the ButterflyMX API, you'll need to set up a sandbox account. This environment allows you to test API interactions without affecting live data. However, unlike many other platforms, ButterflyMX requires you to contact their team directly to obtain a sandbox account. This ensures that you have the necessary permissions and configurations tailored to your development needs.

Contacting ButterflyMX for Sandbox Account Access

Follow these steps to request a sandbox account:

• Visit the ButterflyMX API documentation page to find contact information.
• Reach out to their support or sales team via email or phone, explaining your need for a sandbox account for development purposes.
• Provide details about your project and any specific API functionalities you intend to test.

Creating a ButterflyMX App for OAuth2 Authentication

Once you have access to the sandbox account, you'll need to create an application to use OAuth2 authentication. This process involves generating a client ID and client secret, which are essential for authorizing API requests.

1. Log in to your ButterflyMX sandbox account.
2. Navigate to the "Applications" section in the dashboard.
3. Click on "Create New App" and fill in the required details, such as the app name and description.
4. Set the redirect URI to https://usersandbox.butterflymx.com/oauth/callbacks/butterflymx.
5. Save the app to generate your client ID and client secret.

Obtaining an Authorization Code

To obtain an authorization code, construct a URL as follows and open it in a browser:

https://accountssandbox.butterflymx.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://usersandbox.butterflymx.com/oauth/callbacks/butterflymx&response_type=code&client_secret=YOUR_CLIENT_SECRET

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the values obtained from your app setup.

Exchanging the Authorization Code for Access Tokens

After obtaining the authorization code, exchange it for an access token and refresh token using the following command:

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

Ensure you replace YOUR_AUTHORIZATION_CODE, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET with the appropriate values.

With these steps completed, you are now ready to interact with the ButterflyMX API in a secure and controlled environment.

sbb-itb-96038d7

Making API Calls to Create a Pin with ButterflyMX in PHP

To interact with the ButterflyMX API and create a PIN for tenants, you'll need to use PHP. This section will guide you through the necessary steps, including setting up your PHP environment, making the API call, and handling potential errors.

Setting Up Your PHP Environment for ButterflyMX API Integration

Before making API calls, ensure you have the following prerequisites installed on your machine:

• PHP 7.4 or higher
• Composer for dependency management

Install the Guzzle HTTP client, which simplifies making HTTP requests in PHP:

composer require guzzlehttp/guzzle

Creating a Pin Using the ButterflyMX API

With your environment set up, you can now create a PIN for a tenant using the ButterflyMX API. Follow these steps:

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('PUT', 'https://apisandbox.butterflymx.com/v3/pins', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
        'Accept' => 'application/vnd.api+json',
        'Content-Type' => 'application/vnd.api+json',
    ],
    'json' => [
        'data' => [
            'type' => 'pins',
            'id' => 'TENANT_ID',
            'attributes' => [
                'code' => '1234',
                'unique_code' => '123456'
            ]
        ]
    ]
]);

if ($response->getStatusCode() == 204) {
    echo "Pin created successfully.";
} else {
    echo "Failed to create pin.";
}

Replace YOUR_ACCESS_TOKEN with the access token obtained during authentication and TENANT_ID with the tenant's ID.

Verifying the API Call and Handling Errors

After executing the API call, verify the response to ensure the PIN was created successfully. A status code of 204 indicates success. If the request fails, handle errors as follows:

• 400 Bad Request: Check the request body for missing or incorrect parameters.
• 401 Unauthorized: Ensure your access token is valid and has not expired.

For more detailed error information, refer to the ButterflyMX API documentation.

Conclusion and Best Practices for Using ButterflyMX API in PHP

Integrating with the ButterflyMX API to create PINs for tenants can significantly enhance property management systems by automating access control. By following the steps outlined in this guide, developers can efficiently set up their environment, authenticate using OAuth2, and make API calls to manage tenant access securely.

Best Practices for Secure and Efficient API Integration with ButterflyMX

• Secure Storage of Credentials: Always store your client ID, client secret, and access tokens securely. Consider using environment variables or a secure vault to prevent unauthorized access.
• Handle Rate Limiting: Be mindful of API rate limits to avoid service disruptions. Implement exponential backoff strategies for retrying requests when rate limits are reached.
• Data Standardization: Ensure that data fields are standardized across your application to maintain consistency and avoid errors during API interactions.
• Error Handling: Implement robust error handling to manage different HTTP status codes effectively. Refer to the ButterflyMX API documentation for detailed error descriptions.

Streamline Your Integration Process with Endgrate

While integrating with ButterflyMX is a powerful way to enhance your property management system, managing multiple integrations can be complex and time-consuming. Endgrate offers a unified API solution that simplifies the integration process, allowing you to focus on your core product. By using Endgrate, you can build once for each use case and leverage an intuitive integration experience for your customers. Visit Endgrate to learn more about how you can save time and resources by outsourcing your integrations.

Read More

• https://endgrate.com/provider/butterflymx
• https://apidocs.butterflymx.com/