Manage Resident PIN

The initial PIN is automatically generated by ButterflyMX when the resident registers.

PINs must adhere to strict complexity requirements. They cannot be simple sequences (e.g., 123456 or 654321) or repeated digits (e.g., 111111 or 222222). Additional security rules also apply.

Retrieve Tenant Information

To filter PINs for a specific tenant, first retrieve the list of tenants the user has access to by using the following API:

GET https://apisandbox.butterflymx.com/v4/tenants

Example Response:

{
  "data": [
    {
      "created_at": "2022-08-08T18:06:02Z",
      "full_name": null,
      "id": 129227,
      "updated_at": "2023-03-21T16:07:19Z",
      "first_name": "Demo",
      "last_name": "Tenant",
      "building_id": 11743,
      "inactive_after": null,
      "email": "demo.tenant@butterflymx.com",
      "unit": {
        "created_at": "2022-08-12T17:32:36Z",
        "id": 101356,
        "label": "101",
        "updated_at": "2024-07-11T13:30:46Z",
        "floor": "1",
        "building_id": 11743
      }
    }
  ]
}

From this response, note the tenant_id for use in future requests.

List Resident PINs

To retrieve the list of PINs associated with a tenant, use the following API with the tenant_id collected from the previous request:

GET https://apisandbox.butterflymx.com/v4/access_tools?q[tenant_id_eq]=175394

Example Response:

{
    "data": [
			...
        {
            "created_at": "2024-09-15T20:23:41Z",
            "id": 70091,
            "updated_at": "2024-09-15T20:39:06Z",
            "code": "235708",
            "type": "pin",
            "building_id": 15118,
            "tenant_id": 175394
        }
      ...
    ]
}

Create a Resident PIN

If a tenant does not have a PIN, you can create one using the following API:

POST https://apisandbox.butterflymx.com/v4/access_tools/pins

Request Body:

{
  "pin": {
    "code": "235704",
    "tenant_id": 175394
  }
}

Note: Only one PIN is allowed per tenant.

Update a Resident PIN

To update an existing PIN for a tenant, use the following API:

PUT https://apisandbox.butterflymx.com/v4/access_tools/pins/70091

Request Body:

{
  "code": "235708"
}