How to onboard new partners

To enable an OpenKit partner, please send an email to integrations@latch.com with your property name and the partner you want to enable.

A Customer will need to set up doors, have them activated by an installer, create keys, enable those keys, and invite users on behalf of the Partner. Customers can work with Door directly to set their property up properly. If a partner is also a customer, these steps are still required but can be done by the same entity. For more information on setting up your portfolio please contact Door Support at doorman@door.com.

User Kit
User Kit allows partners to programmatically grant users access to doors without the need of doing this via Door Web.

Door Setup
The first step is for the customer to select which "doors" (as presented in Door Web) can be eligible to be used programmatically by a given partner.

After selecting a door, the property manager will select the partner from the dropdown, making it eligible for partners to use it via the APIs.

Doors API

Partners can fetch a list of all the doors that are enabled for them, by using a partner-scoped token from the BE. It is possible to filter results by Building UUID.

1. GET request from the Partner BE to the Latch BE with an empty body request

GET https://rest.latchaccess.com/access/sdk/v1/doors

2. HTTP Query Parameters

pageSize: <integer>   (by default returns all doors)

pageToken: "<string>" (default is "1", first page)

buildingUuid: "<string>" (for filtering results by the Building UUID)

3. HTTP Headers

Authorization: Bearer {{access_token}}

4. HTTP Request Body

<empty>

5. HTTP Response Body

{

  "doors": [

    {

        "uuid": "<string>",

        "name": "<string>",

        "type": "DOOR" | "ELEVATOR",

        "buildingUuid": "<string>",

        "accessibilityType": "COMMUNAL | "PRIVATE",

        "isConnected": <boolean>

    },

    ...

  ],

  "nextPageToken": "<string>"

}

6. If the request was successful, the Partner BE will receive an HTTP 200 with the following fields:
   • doors: List of "doors" and their metadata. Each entry will include:
     • uuid: Unique-identifier of the door.
     • name: Name of the door.
     • type: Type of door. Possible values: "DOOR" or "ELEVATOR".
     • buildingUuid: Unique-identifier of the building where the door is located.
     • accessibilityType: Indicates whether its a communal (entrance, amenities, etc.) or private door (e.g. unit)
     • isConnected: Indicates connection status of the door. If internet or hub connected, field is set to true.
   • nextPageToken: Token to fetch the next page. Expected value is null when there is no next page.
7. In case of an error, the API will return the following error responses:
   • 401 Unauthorized: missing or invalid access token.
     ⇒ Check the token hasn't expired and refresh the token if needed.
   • 500 Internal Server Error: there was an unexpected error.
     ⇒ Contact Latch Support

Users API

Get users

Partners can fetch a list of their Users. This will be done by using a partner-scoped token from the BE.

1. GET users request from the Partner BE to the Latch BE

GET https://rest.latchaccess.com/access/sdk/v1/users

2. HTTP Query Parameters

pageSize: <integer> (default is 100)

pageToken: "<string>" (default is "0", first page)

3. HTTP Headers

Authorization: Bearer {{access_token}}

4. HTTP Request Body

<empty>

5. HTTP Response Body

{

  "users": [

    {

      "email": "<string>",

      "firstName": "<string>",

      "lastName": "<string>",

      "userUuid": "<string>",

      "accesses": [

        {

          "doorUuid": "<string>",

          "passcodeType": "<string>",

          "shareable": <boolean>,

          "startTime": "<string>",

          "endTime": "<string>",

          "granter": {

            "type": "<string>",

            "uuid": "<string>"

          },

          "role": "<string>",

          "doorcode": {

            "code": "<string>",         // e.g. "1234567"

            "description": "<string>"

          }

        },

        ...

      ]

    },

    ...

  ],

  "nextPageToken": "<string>"

}

6. If the request was successful, the Partner BE will receive an HTTP 200 containing a list of User objects, with the following fields:
   • email: Email address associated with the user.
   • firstName: First name of the user.
   • lastName: Last name of the user.
   • userUuid: Unique identifier of the user.
   • accesses: List of doors the user has access to with the following fields:
     • doorUuid: Unique identifier of the door.
     • passcodeType: Indicates access type. Possible values are PERMANENT, DAILY, DAILY_SINGLE_USE.
     • shareable: Indicates whether user can share access to guests.
     • startTime: Start time of access to door.
     • endTime: End time of access to door.
     • granter: Indicates who granted access to door. Possible values are PARTNER, USER.
     • role: Classifies a type of user. Possible values are RESIDENT, NON_RESIDENT.
     • doorcode: Doorcode object with the following fields:
       • code: 7 digit code for guest access to unlock the door. Can be null.
       • description: A message to explain the code result with the following possible values:
         • VALID: Indicates a valid 7 digit doorcode is returned.
         • COMMUNAL_DOORCODE_CONFLICT: Indicates a user has permanent access to public doors granted by a property manager in Mission Control in a property with the common doorcodes feature enabled. The code field is null.
         • USER_HAS_RESIDENT_ACCESS: Indicates the user has resident access to the door granted via UserKit or Mission Control. The code field is null.
         • USER_HAS_GUEST_ACCESS_CONFLICT: Indicates the user already has guest permanent access to the door granted via Mission Control. The code field is null.
   • nextPageToken: Token to fetch the next page. Expected value is null when there is no next page.
7. In case of an error, the API will return the following error responses:
   • 401 Unauthorized: missing or invalid access token.
     ⇒ Check the token hasn't expired and refresh the token if needed.
   • 500 Internal Server Error: there was an unexpected error.
     ⇒ Contact Latch Support

Create users and grant access

Partners can invite users, without the need of creating them ahead of time, and grant access to a set of doors. This will be done by using a partner-scoped token from the BE.

1. POST from the Partner BE to the Latch BE with the user and door information

POST https://rest.latchaccess.com/access/sdk/v1/users

2. HTTP Headers

Authorization: Bearer {{access_token}}

3. HTTP Request Body

{

    "firstName": "<string>",

    "lastName": "<string>",

    "email": "<string>",

    "phone": "<string>",

    "startTime": "<datetime>",  // e.g. "2022-09-30T15:11:02.537Z"

    "endTime": "<datetime>",    // e.g. "2022-09-30T15:11:02.537Z"

    "doorUuids": [

      "<string>",

      ...

    ],

    "shareable": <boolean>,

    "passcodeType": "PERMANENT" | "DAILY" | "DAILY_SINGLE_USE",

    "role": "RESIDENT" | "NON_RESIDENT",

    "shouldNotify": <boolean>

}

4. HTTP Response Body

{

    "userUuid": "<string>",

    "doors": [

      "uuid": "<string>"

      "name": "<string>",

      "type": "DOOR" | "ELEVATOR",

      "buildingUuid": "<string>",

    ]

}

Validation

Note that the role in the request does not bear relevance on the validation. The role field allows clients to classify their understanding of a User's role with respect to a certain Door, but does not imply a certain credential type or shareability. We currently support two role's: RESIDENT and NON_RESIDENT.

In the future though, the role could be used to determine what credential details the Partner Backend has the ability to see. For example, a Partner Backend can see credential details for their own NON_RESIDENT's but not for RESIDENT's as that would be a privacy violation.

Field descriptions

• shouldNotify (default true): controls whenever email notifications are sent to the invited user. The emails include the welcome email and/or the Doorcode email. If set to false no emails are sent. In order to prevent invalid scenarios validations are put in place to prevent the following request situation since it would lead to the user having no way of accessing their Doorcode:
  • shouldNotify: false
  • passcodeType: DAILY or DAILY_SINGLE_USE
  • role: RESIDENT

Results

1. If the request was successful, the Partner BE will receive an HTTP 200 with the following fields:
   • userUuid: Unique identifier of the invited user and the list of doors the user has access to:
     • uuid: Unique-identifier of the door.
     • name: Name of the door.
     • type: Type of door. Possible values: "DOOR" or "ELEVATOR".
     • buildingUuid: Unique-identifier of the building where the door is located.
2. In case of an error, the API will return the following error responses:
   • 400 Bad Request: missing/invalid parameters or invalid door UUIDs.
     ⇒ Check all the parameters are correct and check all the given doors are valid. Ensure at least 1 doorUuid is supplied in the request.
   • 401 Unauthorized: missing or invalid access token.
     ⇒ Check the token hasn't expired and refresh the token if needed.
   • 500 Internal Server Error: there was an unexpected error.
     ⇒ Contact Latch Support

Revoke access

Partners can revoke user access to given doors. This will be done by using a partner-scoped token from the BE.

1. DELETE from the Partner BE to the Latch BE with an empty body request.

DELETE https://rest.latchaccess.com/access/sdk/v1/users/:user/doors/:door

2. HTTP Headers

Authorization: Bearer {{access_token}}

3. HTTP Request Body

<empty>

4. HTTP Response Body

<empty>

5. If the request was successful, the Partner BE will receive an HTTP 200 and an empty body response. In case of an error, the API will return the following error responses:
   • 404 Not Found: invalid user or door UUIDs.
     ⇒ Check the user and door identifiers.
   • 401 Unauthorized: missing or invalid access token.
     ⇒ Check the token hasn't expired and refresh the token if needed.
   • 500 Internal Server Error: there was an unexpected error.
     ⇒ Contact Latch Support

Get user

Partners can fetch a single user. This will be done by using a partner-scoped token from the BE.

1. GET user request from the Partner BE to the Latch BE with a valid user uuid.

GET https://rest.latchaccess.com/access/sdk/v1/users/:user

2. HTTP Headers

Authorization: Bearer {{access_token}}

3. HTTP Request Body

<empty>

4. HTTP Response Body

{

   "email": "<string>",

   "firstName": "<string>",

   "lastName": "<string>",

   "userUuid": "<string>",

   "phone": "<string>"

   "accesses": [

     {

       "doorUuid: "<string>",

       "passcodeType": "<string>",

       "shareable": <boolean>,

       "startTime": "<string>",

       "endTime": "<string>",

       "granter": {

         "type": "<string>",

         "uuid": "<string>",

       },

       "role": "<string>",

       "doorcode": {

         "code": "<string>"          // e.g. "1234567"

         "description": "<string>"

       }

     },

     ...

   ]

}

5. If the request was successful, the Partner BE will receive an HTTP 200 containing a User object, with the following fields:
   • email: Email address associated with the user.
   • firstName: First name of the user.
   • lastName: Last name of the user.
   • userUuid: Unique identifier of the user.
   • phone: Phone number of the user. Can be null.
   • accesses: List of doors the user has access to with the following fields:
     • doorUuid: Unique identifier of the door.
     • passcodeType: Indicates access type. Possible values are PERMANENT, DAILY, DAILY_SINGLE_USE.
     • shareable: Indicates whether user can share access to guests.
     • startTime: Start time of access to door.
     • endTime: End time of access to door.
     • granter: Indicates who granted access to door. Possible values are PARTNER, USER.
     • role: Classifies a type of user. Possible values are RESIDENT, NON_RESIDENT.
     • doorcode: Doorcode object with the following fields:
       • code: 7 digit code for guest access to unlock the door. Can be null.
       • description: A message to explain the code result with the following possible values:
         • VALID: Indicates a valid 7 digit doorcode is returned.
         • COMMUNAL_DOORCODE_CONFLICT: Indicates a user has permanent access to public doors granted by a property manager in Mission Control in a property with the common doorcodes feature enabled. The code field is null.
         • USER_HAS_RESIDENT_ACCESS: Indicates the user has resident access to the door granted via UserKit or Mission Control. The code field is null.
         • USER_HAS_GUEST_ACCESS_CONFLICT: Indicates the user already has guest permanent access to the door granted via Mission Control. The code field is null.
6. In case of an error, the API will return the following error responses:
   • 401 Unauthorized: missing or invalid access token.
7. ⇒ Check the token hasn't expired and refresh the token if needed.
   • 404 Not Found: invalid user.
8. ⇒ Check the user identifier.
   • 500 Internal Server Error: there was an unexpected error.
9. ⇒ Contact Latch Support

Patch access

Partners can update user access to given doors. This will be done by using a partner-scoped token from the BE.

1. PATCH user request from the Partner BE to the Latch BE with valid user and door uuid.

PATCH https://rest.latchaccess.com/access/sdk/v1/users/:user/doors/:door

2. HTTP Headers

Authorization: Bearer {{access_token}}

3. HTTP Request Body

{

   "shareable": <boolean>,

   "endTime": "<string>"

}

4. HTTP Response Body

{

   "email": "<string>",

   "firstName": "<string>",

   "lastName": "<string>",

   "userUuid": "<string>",

   "phone": "<string>"

   "accesses": [

     {

       "doorUuid: "<string>",

       "passcodeType": "<string>",

       "shareable": <boolean>,

       "startTime": "<string>",

       "endTime": "<string>",

       "granter": {

         "type": "<string>",

         "uuid": "<string>",

       },

       "role": "<string>",

       "doorcode": {

         "code": "<string>"          // e.g. "1234567"

         "description": "<string>"

       }

     },

     ...

   ]

}

Field Descriptions

• Keep in mind that if endTime is omitted from the request body, the api will treat it as if the endTime was explicitly set to null. This is expected in order to support requests to remove expiration from access. To keep the existing endTime, simply add it to the request body.

Results

1. If the request was successful, the Partner BE will receive an HTTP 200 containing a User object, with the following fields:
   • email: Email address associated with the user.
   • firstName: First name of the user.
   • lastName: Last name of the user.
   • userUuid: Unique identifier of the user.
   • phone: Phone number of the user. Can be null.
   • accesses: List of doors the user has access to with the following fields:
     • doorUuid: Unique identifier of the door.
     • passcodeType: Indicates access type. Possible values are PERMANENT, DAILY, DAILY_SINGLE_USE.
     • shareable: Indicates whether user can share access to guests.
     • startTime: Start time of access to door.
     • endTime: End time of access to door.
     • granter: Indicates who granted access to door. Possible values are PARTNER, USER.
     • role: Classifies a type of user. Possible values are RESIDENT, NON_RESIDENT.
     • doorcode: Doorcode object with the following fields:
       • code: 7 digit code for guest access to unlock the door. Can be null.
       • description: A message to explain the code result with the following possible values:
         • VALID: Indicates a valid 7 digit doorcode is returned.
         • COMMUNAL_DOORCODE_CONFLICT: Indicates a user has permanent access to public doors granted by a property manager in Mission Control in a property with the common doorcodes feature enabled. The code field is null.
         • USER_HAS_RESIDENT_ACCESS: Indicates the user has resident access to the door granted via UserKit or Mission Control. The code field is null.
         • USER_HAS_GUEST_ACCESS_CONFLICT: Indicates the user already has guest permanent access to the door granted via Mission Control. The code field is null.
2. In case of an error, the API will return the following error responses:
   • 400 Bad Request: invalid request
3. ⇒ Check endTime is after current and start time.
   • 401 Unauthorized: missing or invalid access token.
4. ⇒ Check the token hasn't expired and refresh the token if needed.
   • 404 Not Found: invalid user or door UUIDs.
5. ⇒ Check the user and door identifiers. Also check user has permanent access to the given door.
   • 500 Internal Server Error: there was an unexpected error.
6. ⇒ Contact Latch Support

Buildings API

Get buildings

Partners can fetch a list of their Buildings. This will be done by using a partner-scoped token from the BE.

1. GET request from the Partner BE to the Latch BE with an empty body request

GET https://rest.latchaccess.com/access/sdk/v1/buildings

2. HTTP Headers

Authorization: Bearer {{access_token}}

3. HTTP Request Body

<empty>

4. HTTP Response Body

{

    "buildings": [

      {

         "uuid": "<string>",

         "name": "<string>",

         "address": {

           "addressLine1": "<string>",

           "addressLine2": "<string>",

           "addressLine3": "<string>",

           "city": "<string>",

           "country": "<string>",

           "postalCode": "<string>",

           "state": "<string>"

         }

      },

      ...

    ]

}

5. If the request was successful, the Partner BE will receive an HTTP 200 with the following fields:
   • buildings: List of "buildings" and their metadata. Each entry will include:
     • uuid: Unique-identifier of the building.
     • name: Name of the building.
     • address: Location the building is located.
6. In case of an error, the API will return the following error responses:
   • 401 Unauthorized: missing or invalid access token.
     ⇒ Check the token hasn't expired and refresh the token if needed.
   • 500 Internal Server Error: there was an unexpected error.
     ⇒ Contact Latch Support