KISI Locks API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Locks API
  description: "## Introduction\n\nWelcome to the Kisi API documentation. Before you read further, please read\nthe general [Kisi Docs portal](https://docs.kisi.io/).\n\n<!-- theme: info -->\n> If you want to be notified by email about updates to our API, please subscribe to our\n> [newsletter](https://2e2bc.share.hsforms.com/2OsdqtC8xRHGQ2yaS16AF7w).\n\n### Format\n\nThe Kisi API supports JSON only, so please set `Accept` and `Content-Type`\nto `application/json`. All requests and responses will use JSON as the\nformat for any data encompassed in the body of requests and responses.\n\n```http\n<METHOD> <URL> HTTP/1.1\nAccept: application/json\nContent-Type: application/json\n```\n\n### Authentication\n\nMost calls to the API will require an authenticated user. If such a user\nis not present, you will receive a 401 response.\nFor more information about authentication, see the [Kisi Docs portal](https://docs.kisi.io/api/get_started/add_necessary_headers).\n\nAPI calls must be made using HTTPS. Any calls made over plain HTTP will fail.\n\n### Rate limits\n\nFor authenticated API requests, you can make up to 5 requests per second,\nper user. Note that the limit applies per user, so requests made using\ndifferent logins for the same user share the same quota.\n\nFor unauthenticated requests, you can make up to 5 requests per second, per\nIP address.\n\nThe following endpoints have custom rate limits:\n\n| Endpoint                   | Limit            |\n|----------------------------|------------------|\n| `POST /event_sets`         | 1 per second     |\n| `POST /signed_upload_urls` | 1 per 10 seconds |\n\nIf you exceed the rate limit, a 429 response will be returned.\n\nSome best practices:\n- If you're making requests for a single user, do so serially, *not* concurrently.\n- If you're making a large number of requests for a single user, wait at least one second between each request.\n\nWe reserve the right to change these limits as needed to ensure availability.\n\n### Deprecations\n\nIn the event that some part of the API has to be deprecated, we do the following:\n\n  1. Return the `Deprecation` header with the date of when the endpoint is deprecated.\n  2. Return the `Sunset` header with the date of when the endpoint can be expected to not function anymore.\n  3. When the `Sunset` date is reached, the endpoint may go away at any time.\n\nWe recommend listening to these headers to avoid disruptions.\n\n### Error codes\n\nSome endpoints return an error code and a message. In the table below all error codes are listed.\n\n| Error code | Message                                                                                         |\n|------------|-------------------------------------------------------------------------------------------------|\n| `afc507`   | The authentication link is not valid.                                                           |\n| `afc546`   | Invalid Two Factor backup code.                                                                 |\n| `faa9ff`   | The card is not activated.                                                                      |\n| `faa9ef`   | The card was not found.                                                                         |\n| `afc496`   | Access denied.                                                                                  |\n| `f29aef`   | Your link is invalid.                                                                           |\n| `afc516`   | Wrong email address or password.                                                                |\n| `afc536`   | Invalid Two Factor verification code.                                                           |\n| `afc526`   | Please provide a Two Factor verification code.                                                  |\n| `afc516`   | The two factor pin is invalid                                                                   |\n| `ffffff`   | An unexpected issue occured.                                                                    |\n| `fcd8ef`   | Access denied.                                                                                  |\n| `fcd8ff`   | Access disabled.                                                                                |\n| `cabbeb`   | A card with the same identifiers was already enrolled.                                          |\n| `bb4fff`   | Please authorize Kisi for Bluetooth.                                                            |\n| `bb5bff`   | No nearby Kisi reader found. Try enabling Bluetooth on your device.                             |\n| `bb4bff`   | Please enable Bluetooth.                                                                        |\n| `a7793f`   | Please authorize Kisi for location services.                                                    |\n| `a3799f`   | Please enable your location services.                                                           |\n| `a3793f`   | Please enable your location services.                                                           |\n| `f298cf`   | The place has disabled all links for you.                                                       |\n| `f298df`   | Your access rights for this place do not include links.                                         |\n| `f298bf`   | Your access right is invalid.                                                                   |\n| `f01337`   | Your group's access rights for this place do not include apps.                                  |\n| `34bd8f`   | Your device is not the primary one.                                                             |\n| `facced`   | Unable to decode the certificate.                                                               |\n| `bbb99f`   | Your location is not valid.                                                                     |\n| `bbb93f`   | The location of the lock is invalid.                                                            |\n| `a3995f`   | You are too far away.                                                                           |\n| `bb4faa`   | You're not close enough to the door.                                                            |\n| `bbc93f`   | In-app access is disabled by the organization. Please tap your phone against the reader.        |\n| `34ffaa`   | Your access is not allowed at this moment, please try again later.                              |\n| `f35ade`   | Your access is no longer valid.                                                                 |\n| `f398de`   | Your access is invalid.,                                                                        |\n| `f358de`   | Your access is not yet valid, please try again later.                                           |\n| `fad334`   | An error occurred permitting the the elevator stop.                                             |\n| `fad121`   | The elevator stop was not found.                                                                |\n| `fad122`   | The elevator stop was not configured.                                                           |\n| `fad123`   | The elevator stops are locked down.                                                             |\n| `fad124`   | The elevator stop was on schedule.                                                              |\n| `fad002`   | The place is currently locked down.                                                             |\n| `ff420a`   | The door has no assigned Kisi controller.                                                       |\n| `fad001`   | The door is currently locked down.                                                              |\n| `fad105`   | The door is improperly configured.                                                              |\n| `fad10e`   | The door could not be found.                                                                    |\n| `fad110`   | The door is already scheduled to be unlocked.                                                   |\n| `fad137`   | The access was denied by the zone.                                                              |\n| `fad146`   | The third party zone was overriden but it is still armed.                                       |\n| `fad10f`   | An error occurred connecting to the wireless lock.                                              |\n| `fad106`   | An error occurred finding the wireless lock.                                                    |\n| `fad107`   | The wireless lock is offline.                                                                   |\n| `fad112`   | An unlock is already in progress for the wireless lock.                                         |\n| `fac001`   | The Kisi controller is currently unavailable.                                                   |\n| `fac002`   | The Kisi controller is currently unavailable.                                                   |\n| `fac003`   | The Kisi device is currently unavailable.                                                       |\n| `fac004`   | The Kisi device is currently unavailable.                                                       |\n| `fad108`   | The Kisi controller is not yet configured.                                                      |\n| `ecc123`   | The Kisi controller encountered an unhandled error.                                             |\n| `fbc000`   | The Kisi controller firmware is being updated. This will take a few seconds. Please retry then. |\n| `aaa345`   | The zone has no assigned zone controller.                                                       |\n| `fad126`   | The zone could not be found.                                                                    |\n| `fad129`   | The alarm controller is currently unavailable.                                                  |\n| `adf234`   | An error occurred resetting the zone.                                                           |\n| `fad144`   | The third party alarm is still in violation.                                                    |\n| `abbb11`   | The integration partner experienced an error.                                                   |\n| `abcc11`   | An integration partner resource could not be found.                                             |\n| `abdd11`   | The communication with the integration partner failed.                                          |\n| `abee11`   | Authorization with the integration partner failed.                                              |\n| `abfe11`   | The integration is not acceptable                                                               |\n| `abff11`   | The integration is disabled.                                                                    |\n"
  contact:
    name: Kisi Support
    email: support@getkisi.com
servers:
- url: https://api.kisi.io
  description: Kisi Production
tags:
- name: Locks
paths:
  /locks:
    get:
      operationId: fetchLocks
      summary: Fetch locks
      description: 'Returns a list of locks.


        When authenticating with a GroupLink, a subset of the Lock resource is returned.

        '
      tags:
      - Locks
      security:
      - Kisi-Login: []
      - OAuth2: []
      - Kisi-Group-Link: []
      - Kisi-Access-Key: []
      parameters:
      - name: ids
        in: query
        schema:
          type: string
        description: Filter by object IDs
      - name: query
        in: query
        schema:
          type: string
        description: 'Filter by a freetext string. Properties searched: `name`

          '
      - name: floor_id
        in: query
        schema:
          type: integer
        description: Filter by floor ID
      - name: place_id
        in: query
        schema:
          type: integer
        description: Filter by place ID
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 250
        description: The number of objects to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          maximum: 20000
        description: The number of objects to offset
      - name: configured
        in: query
        schema:
          type: boolean
        description: Filter by whether the lock has been configured.
      - name: online
        in: query
        schema:
          type: boolean
        description: Filter by whether the lock is online.
      - name: unlocked
        in: query
        schema:
          type: boolean
        description: Filter by whether the lock is unlocked or locked.
      - name: locked_down
        in: query
        schema:
          type: boolean
        description: Filter by whether the lock is locked down.
      - name: favorite
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '*'
        description: 'Include favorite status in response and/or filter by it.


          `*` - include `favorite` field in response<br>

          `true` - include `favorite` field in response and return favorites<br>

          `false` - include `favorite` field in response and return non-favorites<br>

          '
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - favorite
          - name
          - -name
        description: 'Sort the results. Prepend `-` to sort in reverse order.


          `favorite` - sort by favorite, most recent favorites first<br>

          `name` - sort by lock name, alphabetically

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  oneOf:
                  - type: object
                    title: Lock - when authenticated by group link
                    properties:
                      id:
                        type: integer
                        description: The ID of the lock
                      configured:
                        type: boolean
                        description: Whether the lock has been configured.
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the lock
                      locked_down_since:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: 'Since when the lock has been locked down.

                          '
                      locked_down:
                        type: boolean
                        description: 'Whether the lock is locked down. When locked down the lock is locked for everyone.

                          '
                      name:
                        type: string
                        description: The name of the lock
                      online:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the lock is online.
                      open:
                        type: boolean
                        description: Whether the lock is open
                      unlocked_until:
                        deprecated: true
                        type:
                        - string
                        - 'null'
                        format: date-time
                      unlocked:
                        type: boolean
                        description: Whether the lock is unlocked.
                      place_id:
                        type: integer
                        description: The place ID of the lock
                      place:
                        type: object
                        title: Place
                        description: The place of the lock
                        properties:
                          id:
                            type: integer
                            description: The ID of the place
                          name:
                            type: string
                            description: The name of the place
                          latitude:
                            type:
                            - number
                            - 'null'
                            format: float
                            description: The latitude of the place
                          longitude:
                            type:
                            - number
                            - 'null'
                            format: float
                            description: The longitude of the place
                        required:
                        - id
                        - name
                        - latitude
                        - longitude
                        additionalProperties: false
                    required:
                    - id
                    - configured
                    - description
                    - locked_down_since
                    - locked_down
                    - name
                    - online
                    - open
                    - unlocked_until
                    - unlocked
                    - place_id
                    - place
                    additionalProperties: false
                  - type: object
                    title: Lock
                    properties:
                      id:
                        type: integer
                        description: The ID of the lock
                      resource_type:
                        type: string
                        description: The resource type of the lock
                        const: Lock
                      created_at:
                        type: string
                        format: date-time
                        description: When the lock was created
                      updated_at:
                        type: string
                        format: date-time
                        description: When the lock was updated
                      configured:
                        type: boolean
                        description: Whether the lock has been configured.
                      description:
                        type:
                        - string
                        - 'null'
                        description: The description of the lock
                      first_to_arrive_required_until:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: Until when the first to arrive trigger is required to be satisfied.
                      first_to_arrive_satisfied:
                        type: boolean
                        description: Whether the first to arrive condition is currently satisfied.
                      latitude:
                        type:
                        - number
                        - 'null'
                        format: float
                        description: The latitude of the lock.
                      locked_down:
                        type: boolean
                        description: 'Whether the lock is locked down. When locked down the lock is locked for everyone.

                          '
                      locked_down_since:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: 'Since when the lock has been locked down.

                          '
                      longitude:
                        type:
                        - number
                        - 'null'
                        format: float
                        description: The longitude of the lock.
                      name:
                        type: string
                        description: The name of the lock
                      on_scheduled_unlock:
                        type: boolean
                        description: If the lock is on a scheduled unlock.
                      online:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the lock is online.
                      open:
                        type: boolean
                        description: Whether the lock is open
                      order_id:
                        type:
                        - integer
                        - 'null'
                        description: 'The position of the lock, determining the sort order of the locks.

                          '
                      unlocked:
                        type: boolean
                        description: Whether the lock is unlocked.
                      geofence_restriction_enabled:
                        type:
                        - boolean
                        - 'null'
                        description: 'Whether the lock is geofence restricted. Geofence restriction enforces that users may only unlock when they are near the lock.

                          '
                      geofence_restriction_radius:
                        type: number
                        description: The radius of the geofence restriction.
                      reader_restriction_enabled:
                        type:
                        - boolean
                        - 'null'
                        description: 'Whether reader restriction is enabled. Reader restriction enforces that users may only unlock when standing in front of the door.

                          '
                      time_restriction_enabled:
                        type:
                        - boolean
                        - 'null'
                        description: 'Whether the lock is time restricted. Time restriction enforces that users may only unlock at specific hours.

                          '
                      time_restriction_time_zone:
                        type:
                        - string
                        - 'null'
                        example: Europe/London
                        description: 'What time zone the time restriction applies to.

                          '
                      favorite:
                        type: boolean
                        description: 'Whether the lock is marked as a favorite by the user. Only shown if requested.

                          '
                      place_id:
                        type: integer
                        description: The place ID of the lock
                      place:
                        type: object
                        title: Place
                        description: The place of the lock
                        properties:
                          id:
                            type: integer
                            description: The ID of the place
                          name:
                            type: string
                            description: The name of the place
                          latitude:
                            type:
                            - number
                            - 'null'
                            format: float
                            description: The latitude of the place
                          longitude:
                            type:
                            - number
                            - 'null'
                            format: float
                            description: The longitude of the place
                        required:
                        - id
                        - name
                        - latitude
                        - longitude
                        additionalProperties: false
                      floor_id:
                        type:
                        - integer
                        - 'null'
                        description: The floor ID of the lock
                      groups_count:
                        deprecated: true
                        type: integer
                      unlocked_until:
                        deprecated: true
                        type:
                        - string
                        - 'null'
                        format: date-time
                    required:
                    - id
                    - resource_type
                    - created_at
                    - updated_at
                    - configured
                    - description
                    - first_to_arrive_required_until
                    - first_to_arrive_satisfied
                    - latitude
                    - locked_down
                    - locked_down_since
                    - longitude
                    - name
                    - on_scheduled_unlock
                    - online
                    - open
                    - order_id
                    - unlocked
                    - geofence_restriction_enabled
                    - geofence_restriction_radius
                    - reader_restriction_enabled
                    - time_restriction_enabled
                    - time_restriction_time_zone
                    - place_id
                    - place
                    - floor_id
                    - groups_count
                    - unlocked_until
                    additionalProperties: false
          headers:
            X-Collection-Range:
              description: 'Pagination information for offset based pagination. `start-end` represents the range

                of items requested. `total` represents the total count of items. If there is a total

                of 15 items and an offset of 10 and limit of 10 is used, the resulting header is:

                `10-19/15`.

                '
              schema:
                type: string
                pattern: ^(?<start>\d+)-(?<end>\d+)/(?<total>\d+)$
              example: 0-9/200
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createLock
      summary: Create lock
      tags:
      - Locks
      security:
      - Kisi-Login: []
      - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: Lock
              properties:
                lock:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the lock
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the lock
                    latitude:
                      type:
                      - number
                      - 'null'
                      format: float
                      description: The latitude of the lock.
                    longitude:
                      type:
                      - number
                      - 'null'
                      format: float
                      description: The longitude of the lock.
                    geofence_restriction_enabled:
                      type:
                      - boolean
                      - 'null'
                      description: 'Whether the lock is geofence restricted. Geofence restriction enforces that users may only unlock when they are near the lock.

                        '
                    reader_restriction_enabled:
                      type:
                      - boolean
                      - 'null'
                      description: 'Whether reader restriction is enabled. Reader restriction enforces that users may only unlock when standing in front of the door.

                        '
                    time_restriction_enabled:
                      type:
                      - boolean
                      - 'null'
                      description: 'Whether the lock is time restricted. Time restriction enforces that users may only unlock at specific hours.

                        '
                    order_id:
                      type:
                      - integer
                      - 'null'
                      description: 'The position of the lock, determining the sort order of the locks.

                        '
                    floor_id:
                      type:
                      - integer
                      - 'null'
                      description: The floor ID of the lock
                    place_id:
                      type: integer
                      description: The place ID of the lock
                    favorite:
                      type: boolean
                      description: 'Whether the lock is marked as a favorite by the user. Only shown if requested.

                        '
                  required:
                  - name
                  - place_id
              required:
              - lock
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                oneOf:
                - type: object
                  title: Lock - when authenticated by group link
                  properties:
                    id:
                      type: integer
                      description: The ID of the lock
                    configured:
                      type: boolean
                      description: Whether the lock has been configured.
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the lock
                    locked_down_since:
                      type:
                      - string
                      - 'null'
                      format: date-time
                      description: 'Since when the lock has been locked down.

                        '
                    locked_down:
                      type: boolean
                      description: 'Whether the lock is locked down. When locked down the lock is locked for everyone.

                        '
                    name:
                      type: string
                      description: The name of the lock
                    online:
                      type:
                      - boolean
                      - 'null'
                      description: Whether the lock is online.
                    open:
                      type: boolean
                      description: Whether the lock is open
                    unlocked_until:
                      deprecated: true
                      type:
                      - string
                      - 'null'
                      format: date-time
                    unlocked:
                      type: boolean
                      description: Whether the lock is unlocked.
                    place_id:
                      type: integer
                      description: The place ID of the lock
                    place:
                      type: object
                      title: Place
                      description: The place of the lock
                      properties:
                        id:
                          type: integer
                          description: The ID of the place
                        name:
                          type: string
                          description: The name of the place
                        latitude:
                          type:
                          - number
                          - 'null'
                          format: float
                          description: The latitude of the place
                        longitude:
                          type:
                          - number
                          - 'null'
                          format: float
                          description: The longitude of the place
                      required:
                      - id
                      - name
                      - latitude
                      - longitude
                      

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kisi/refs/heads/main/openapi/kisi-locks-api-openapi.yml