KISI Holiday calendars API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Holiday calendars 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: Holiday calendars
paths:
  /holiday_calendars/{region}/holidays:
    get:
      operationId: fetchHolidays
      summary: Fetch holidays
      tags:
      - Holiday calendars
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: region
        in: path
        schema:
          type: string
        description: Specifies the region
        required: true
      - name: year
        in: query
        schema:
          type: string
        description: Specifies the year
        required: true
      - name: observed
        in: query
        schema:
          type: boolean
        description: Specifies the observance
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  title: Holiday
                  properties:
                    date:
                      type: string
                      format: date
                      description: The date of the holiday
                    name:
                      type: string
                      description: The name of the holiday
                  required:
                  - date
                  - name
                  additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /holiday_calendars/regions:
    get:
      operationId: fetchRegions
      summary: Fetch regions
      tags:
      - Holiday calendars
      security:
      - Kisi-Login: []
      - OAuth2: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                patternProperties:
                  ? ar|at|au|br|bg|ca|us|ch|cl|co|cr|cy|cz|dk|de|ee|es|fi|fr|gb|ge|gr|hr|hk|hu|ie|il|in|is|it|ke|kr|kz|li|lt|lv|ma|mc|mx|nl|lu|no|nz|pe|ph|pl|pt|ro|ru|se|tn|tr|ua|za|jp|vn|sg|my|th|ng
                  : type: object
                    title: Holiday Calendar Region
                    properties:
                      alpha2:
                        type: string
                        enum:
                        - AR
                        - AT
                        - AU
                        - BR
                        - BG
                        - CA
                        - US
                        - CH
                        - CL
                        - CO
                        - CR
                        - CY
                        - CZ
                        - DK
                        - DE
                        - EE
                        - ES
                        - FI
                        - FR
                        - GB
                        - GE
                        - GR
                        - HR
                        - HK
                        - HU
                        - IE
                        - IL
                        - IN
                        - IS
                        - IT
                        - KE
                        - KR
                        - KZ
                        - LI
                        - LT
                        - LV
                        - MA
                        - MC
                        - MX
                        - NL
                        - LU
                        - 'NO'
                        - NZ
                        - PE
                        - PH
                        - PL
                        - PT
                        - RO
                        - RU
                        - SE
                        - TN
                        - TR
                        - UA
                        - ZA
                        - JP
                        - VN
                        - SG
                        - MY
                        - TH
                        - NG
                        description: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
                      alpha3:
                        type: string
                        enum:
                        - ARG
                        - AUT
                        - AUS
                        - BRA
                        - BGR
                        - CAN
                        - USA
                        - CHE
                        - CHL
                        - COL
                        - CRI
                        - CYP
                        - CZE
                        - DNK
                        - DEU
                        - EST
                        - ESP
                        - FIN
                        - FRA
                        - GBR
                        - GEO
                        - GRC
                        - HRV
                        - HKG
                        - HUN
                        - IRL
                        - ISR
                        - IND
                        - ISL
                        - ITA
                        - KEN
                        - KOR
                        - KAZ
                        - LIE
                        - LTU
                        - LVA
                        - MAR
                        - MCO
                        - MEX
                        - NLD
                        - LUX
                        - NOR
                        - NZL
                        - PER
                        - PHL
                        - POL
                        - PRT
                        - ROU
                        - RUS
                        - SWE
                        - TUN
                        - TUR
                        - UKR
                        - ZAF
                        - JPN
                        - VNM
                        - SGP
                        - MYS
                        - THA
                        - NGA
                        description: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
                      name:
                        type: string
                        description: Name of the region, typically country
                      continent:
                        type: string
                        description: The continent of the region
                      country_code:
                        type: string
                        description: The country code of this region
                      world_region:
                        type: string
                        description: The world region encompassing this region
                      subregions:
                        type: object
                        patternProperties:
                          .+:
                            type: object
                            properties:
                              code:
                                type: string
                                description: The subregion code
                              name:
                                type: string
                                description: The subregion name
                            description: Different keys for different regions
                            required:
                            - code
                            - name
                    required:
                    - alpha2
                    - alpha3
                    - name
                    - continent
                    - country_code
                    - world_region
                    - subregions
                    additionalProperties: false
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Errors:
      description: Schema describing validation errors.
      type: object
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            email:
            - can't be blank or invalid
            password:
            - can't be blank
      required:
      - errors
    Error:
      description: Schema describing errors.
      type: object
      properties:
        error:
          type: string
          description: The error message.
          example: Wrong email address or password.
        code:
          type: string
          description: An identifier of the error.
          example: afc516
      required:
      - error
      - code
  securitySchemes:
    Webhook-Signature:
      type: apiKey
      in: header
      name: X-Signature
      description: 'Authorize using a signature of the request body. The signature is a HMAC-SHA256 hash of the request body using a secret key. <br><br>E.g. `X-Signature: 123`'
    Kisi-Login:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorize using a login. Prefix the value with `KISI-LOGIN`<br><br>Example: `Authorization: KISI-LOGIN 123`'
    Kisi-Access-Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorize using an access key. Prefix the value with `KISI-ACCESS-KEY`<br><br>Example: `Authorization: KISI-ACCESS-KEY 123`'
    Kisi-Group-Link:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorize using a group link. Prefix the value with `KISI-GROUP-LINK`<br><br>Example: `Authorization: KISI-GROUP-LINK 123`'
    Kisi-Service:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorize using a service. Prefix the value with `KISI-SERVICE`<br><br>Example: `Authorization: KISI-SERVICE 123`'
    OAuth2Basic:
      type: http
      scheme: basic
      description: Username is the client id. Password is the client secret.
    OAuth2:
      type: oauth2
      description: 'OAuth access tokens are sent as bearer tokens. Example: `Authorization: Bearer youraccesstoken`'
      flows:
        authorizationCode:
          authorizationUrl: https://api.kisi.io/oauth/authorize
          tokenUrl: https://api.kisi.io/oauth/token
          scopes: {}