Yonomi Interop

## Sections
• [Device Ownership Management](https://developers.yonomi.cloud/devicemanagement/device-ownership-management.md): Claiming Device Ownership Prerequisites PAC client software must have an application that connects directly to device via Bluetooth using the Yonomi Mobile SDK. Application must have feature to request claim token generation. User must have a valid Yonomi installation which they desire to own the device. User must have a valid Yonomi-capable device that is in claimable state (see below section for details). Note: See the Getting Started training guide Training: Preparation for Claiming a Device for assistance in meeting these pre-requisite requirements. Getting Device in Claimable State Device is new from factory Device should already be in a claimable state. Note: If claiming operation results in error saying the device can't be claimed, contact device maker's customer support team for assistance. Device is pre-owned The previous installation must have already unclaimed the device. Note: If the device has not been unclaimed yet and the new device owner has no way to unclaim it from the previous installation, contact device maker's customer support team for assistance. The device must have successfully been Factory Default Reset AFTER having been unclaimed. Note: See device maker documentation on how initiate the Factory Default Reset process from the device itself. Claiming ownership of a device Flow Diagram ClaimOwnershipRequest GraphQL Mutation Claims device to the requested installationId. Request Headers Title Description Title Description Field Name Description DataType Required x-allegion-installation-Id UUID of the installation that user wants device claimed to. ID! true GraphQL Request Body Gql mutation ClaimOwnershipRequest { claimOwnershipRequest(claimToken: $DeviceJWTString!) { deviceId owner { installationId } } } Title Description Title Description Input Name Description DataType Required claimToken The claim token JWT received from the device using the mobile app's bluetooth connection. String! true Possible Claiming Error Responses Title Description Error Code Description DEVICE_RESET_REQUIRED If you receive this code, the claimToken JWT provided is correct and the device is availble to be claimed, but the device is not in Factory Default state. FDR the device (see device maker's documentation) and then retry claiming it. CANNOT_CLAIM If you recieve this code, it means there was an error with the claim process itself such as the claimToken JWT being malformed or invalid, the deviceId in the claimToken JWT not being a valid deviceId, or the deviceId in the claimToken JWT has already been claimed. It is recommended to request a new claimToken from the device and retry claiming, then if the issue recurs contact the device maker customer support team for assistance. Query Owned Devices MyOwnedDevices GraphQL Query Gets a list of deviceIds that are owned by the target installation. Request Headers Title Description Title Description Field Name Description DataType Required x-allegion-installation-Id UUID of the installation that device is currently claimed to. ID! true Request Body Gql mutation MyOwnedDevices { myOwnedDevices } This query has no inputs other than the required header. It will return a list of deviceIds that are currently owned by the installationId included in the header. Relinquishing Device Ownership Relinquishes ownership of the device from current owner and puts the device back in a claimable state so that another installation may take over ownership of the device. Step 1: UnclaimOwnershipRequest GraphQL Mutation Unclaims device from the current owner installationId. Request Headers Title Description Title Description Field Name Description DataType Required x-allegion-installation-Id UUID of the installation that device is currently claimed to. ID! true Request Body Plain text mutation UnclaimOwnershipRequest { unclaimOwnershipRequest(deviceId: 9a8f6104-6c50-476e-90ee-16b9a2dafc8d) { deviceId } } mutation UnclaimOwnershipRequest { unclaimOwnershipRequest(deviceId: 9a8f6104-6c50-476e-90ee-16b9a2dafc8d) { deviceId } } Title Description Title Description Input Name Description DataType Required deviceId uuid of the target device. ID! true Step 2: Reset device to Factory Settings Follow device maker documentation to reset the device to factory default state. Note: New device owners will not be able to claim ownership until the device is in factory default state in order to protect previous owners' sensitive data stored on the device from being readable to a new owner.
• [Device Trait Overview](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait.md): What is Trai t Traits, in the context of the Yonomi Platform (YP), refer to the data schema that describes specific device functionality within the platform. They are designed to capture the core functionality of devices in a standardized manner, making integration more accessible and reducing the effort required to integrate multiple devices. Traits ensure that the functionality of devices within YP can be composed together seamlessly while still allowing for flexibility. Types of Traits There are 2 different types of traits as defined below. These types influence the required flows for interactions defined in a given trait. To determine which type a specific trait is, see the documentation for that specific trait. Standard Trait : All data required for the interaction is fully contained within the interaction payload. Bulk Data Trait : Trait interactions deal with potentially large data sets that can exceed transaction data limits. As such, data is required to be stored in JSON data files and the interaction payload containing the relevant upload/download URL. These traits therefore require additional processes to generate/upload or download/parse data files in addition to the standard interaction processes. Types of Trait Interactions Actions A trait action is a cloud interaction that initiates an update or command at the device. Examples include updating device settings, writing authorized credential data to the device, issuing a remote unlock command, or initiating device firmware update. Actions have a complete lifecycle that is initiated through a synchronous GraphQL Mutation request to YP APIs and completes with asynchronous events published from the device upon completion of the requested action. For information on the Action Lifecycle flow, see the Trait Overview: Device Action Lifecycle documentation. Reported States A trait state is a data field representing a specific property or setting on the device. There are 2 primary interactions that users may have with trait states: Trait State Query : Users may submit synchronous GraphQL Query requests to YP APIs in order to receive information on the current state values that were last reported by the device. State Updated Events : Users may subscribe to receive events webhooks or may query history of the events that are published whenever the device reported states change. For information on each of these trait state interactions, see the Trait Overview: Device Reported State documentation. Notifications A trait notification is an event published by the device to communicate transient information to the user (e.g. low battery, device locked/unlocked audits, etc.). For information on notification events, see the Trait Overview: Device Notifications documentation.
  • [Device Events](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait/device-events.md): Yonomi Platform maintaings logs of all device events that are published, allowing client users to audit device history and/or fetch on-demand information about a device's events. Additionally, clients may subscribe to receiving event webhooks whenever events of the type subscribed to are published to the event logs. Device Event Types Note: The shapes for the following event types are defined in the linked documentation pages that go over the flows where that publish these events. See the linked pages for details and examples. Title Description Event Type Description DEVICE_ACTION_CREATED Event published when a new action is created (see Trait Overview: Device Action Lifecycle ) DEVICE_ACTION_UPDATED Event published when an existing action is updated (see Trait Overview: Device Action Lifecycle ) DEVICE_STATE_UPDATED Event published when device reports an update to a standard trait state ( see Trait Overview: Device Reported State ) DEVICE_BULK_DATA_STATE_UPDATED Event published when device reports an update to a bulk data trait state ( see Trait Overview: Device Reported State ) DEVICE_NOTIFICATION_REPORTED Event published when device reports an info or warning notification ( see Trait Overview: Device Notifications ) Example events that get published for a given action Users may receive many events published for a single action mutation. For example, when sending a LockV1ExcuteLockingAction mutation, users will recive betwen 2 and 6 events total. Below are the events that might be expected for this action request Title Description Event Trigger DEVICE_ACTION_CREATED When action has been created, user will get one of these events. DEVICE_ACTION_UPDATED When action has been either rejected with an error or resolved, user will get one of these events with the appropriate status. DEVICE_STATE_UPDATED If the action results in device changing its lockState, one of these will be emitted for each state change made. If action results in a momentary unlock of the device, state update will publish when device unlocks and again when it automatically relocks. Therefore, up to 2 DEVICE_STATE_UPDATED events are expected. DEVICE_NOTIFICATION_REPORTED The device publishes a notification each time something attempts to change it's lockState to detail what the trigger was and the result. As such, anytime the lockState emits a DEVICE_STATE_UPDATED event, there will be a correspondiing notification giving context on why the state was changed. Therefore, up to 2 DEVICE_NOTIFICATION_REPORTED events are expected. Subscribing to Receive Webhooks To configure webhook subscriptions to Yonomi events, see the Training Project: Create a Webhook Configuration page Querying Event History Required Headers All device event queries require the following header be included. Title Description Title Description FieldName Description Value Required x-allegion-installation-Id UUID of the installation that owns the device. Authentication will validate that bearer token has authorization to mutate against this installationId and that the requested deviceId is owned by that installation. If either fail, request will be rejected. ID! true Available Query Filters Title Description Title Filter Data Type Additional Information eventType string See eventType list above for valid values before dateTime YYYY-MM-DDThh:mm:ss.sssZ after dateTime YYYY-MM-DDThh:mm:ss.sssZ traitName string See individual trait documents for valid values actionId ID Only apply if eventType filters on a Device Action Lifecycle eventType Querying for all events example GraphQL query QueryDeviceEvents ($deviceId: ID!) { device (deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id events (sort: DESCENDING, first: 20) { pageInfo { hasNextPage hasPreviousPage endCursor } edges { node { eventType createdAt ... on DeviceStateUpdatedEvent { deviceId fieldName traitName value createdAt } ... on DeviceBulkDataStateUpdatedEvent { deviceId traitName } ... on DeviceActionCreatedEvent { actionId deviceId traitName actionParameters actionStatus } ... on DeviceActionUpdatedEvent { actionId deviceId actionStatus createdAt errors { code message details } } ... on DeviceNotificationReportedEvent { deviceId notificationName notificationType message sampledAt createdAt traitName details } } } } } } Querying for all events related to a particular trait example GraphQL query QueryDeviceEvents ($deviceId: ID!) { device (deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id events (filter: { traitName: LockV1 }, sort: DESCENDING, first: 20) { pageInfo { hasNextPage hasPreviousPage endCursor } edges { node { eventType createdAt ... on DeviceStateUpdatedEvent { deviceId fieldName traitName value createdAt } ... on DeviceBulkDataStateUpdatedEvent { deviceId traitName } ... on DeviceActionCreatedEvent { actionId deviceId traitName actionParameters actionStatus } ... on DeviceActionUpdatedEvent { actionId deviceId actionStatus createdAt errors { code message details } } ... on DeviceNotificationReportedEvent { deviceId notificationName notificationType message sampledAt createdAt traitName details } } } } } } Querying for all DEVICE_ACTION_UPDATED events related to a particular action example Note: because actionId filter is used, eventType must be DEVICE_ACTION_CREATED or DEVICE_ACTION_UPDATED to successfully get results. GraphQL query QueryDeviceEvents ($deviceId: ID!) { device (deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id events (filter: { eventType: DEVICE_ACTION_UPDATED, actionId: "7eb3629a-a1c3-49f0-89b6-2831d500ac68" }, sort: DESCENDING, first: 20) { pageInfo { hasNextPage hasPreviousPage endCursor } edges { node { eventType createdAt ... on DeviceActionUpdatedEvent { actionId deviceId actionStatus createdAt errors { code message details } } } } } } } Querying for all events within a given dateTime range example GraphQL query QueryDeviceEvents ($deviceId: ID!) { device (deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id events (filter: { before: "2024-12-01T00:00:00.000Z", after: "2024-12-31T23:59:59.999Z" }, sort: DESCENDING, first: 20) { pageInfo { hasNextPage hasPreviousPage endCursor } edges { node { eventType createdAt ... on DeviceStateUpdatedEvent { deviceId fieldName traitName value createdAt } ... on DeviceBulkDataStateUpdatedEvent { deviceId traitName } ... on DeviceActionCreatedEvent { actionId deviceId traitName actionParameters actionStatus } ... on DeviceActionUpdatedEvent { actionId deviceId actionStatus createdAt errors { code message details } } ... on DeviceNotificationReportedEvent { deviceId notificationName notificationType message sampledAt createdAt traitName details } } } } } }
  • [Device Action Lifecycle](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait/action-lifecycle-flows.md): Introduction to Trait Actions A trait action is an interaction that is taken from the cloud to update the device or initiate a command in the device current state. Examples include updating device setting values, writing authorized credential data to the device, issuing a remote unlock command, or iniitating device firmware update. Trait Action Lifecycle Flows The interaction flow throughout the trait action lifecycle varies depending on whether the trait is a standard, or bulk data type trait (See individual trait documentation). Additionally, a standard trait flow may have specific action requests that are “BLE Only Commands” which require additionally processes of connecting to the device via BLE before triggering the command. - Where applicable, individual trait action documentation explicitly calls out that the action requires the “BLE Only Command" flow. Regardless, the action lifecycle consists of 2 parts: the originating synchronous requests made to Yonomi APIs and an asynchronous flow where Yonomi and device communicate and update the action status through published events. Standard Action Lifecycle Flow Standard Action Lifecycle Flow for BLE Only Command Actions Bulk Data Action Lifecycle Flow Submitting Action Requests To initiate an action, the user must submit a GraphQL mutation to the Yonomi Platform. Each action mutation is defined in the individual trait documentation, so refer to those pages for mutation request definitions. Required Headers All trait mutations require the following header be included regardless of which trait / action mutation it is. Title Description Title Description FieldName Description Value Required x-allegion-installation-Id UUID of the installation that owns the device. Authentication will validate that bearer token has authorization to mutate against this installationId and that the requested deviceId is owned by that installation. If either fail, request will be rejected. ID! true Success Response Once request has been submitted and passes validation in Yonomi Platform, an action is created along with an actionId that will be used to correlate any asynchronous events that occur as a result of the action. On successful response, user will get a synchronous response that contains the graphQL response definition submitted with the request this response may contain actionId, deviceId, and/or mutationName. NOTE: While user may submit requests that omit actionId from the response, doing so will prohibit user from tracking any updates to the action status. As such, it is highly recommended that all requests request at least the actionId be returned on successful response. Error Response In case of error with the synchronous request, API will return one of the errors defined here: Trait Overview: Synchronous Request Errors . Action Lifecycle Events See Device Events for information on subscribing to webhooks or submitting event queries. Action Lifecycle Event Shape Examples DEVICE_ACTION_CREATED Event Example Event that is published when the action is created. Plain text { "eventType": "DEVICE_ACTION_CREATED", "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "createdAt": "2024-12-20T14:49:55.000Z", "actionName": "AutoRelockDelaySettingsV1SetAutoRelockDelay", "actionStatus": "PENDING", "actionParameters": { "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitActionArgs": { "autoRelockDelay": 30 } } } DEVICE_ACTION_UPDATED Event Example Event that updates an already created action. Plain text { "eventType": "DEVICE_ACTION_UPDATED", "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "createdAt": "2024-12-20T14:49:55.000Z", "actionStatus": "REJECTED", "errors": [ { "code": "ERR_DATA_FILE_VALIDATION_FAILED", "message": "The provided data file failed validation and could not be uploaded to the device.", "details": { "dataFileValidationErrors": [ { "code": "ARRAY_EXCEEDS_MAX_ITEMS", "message": "Count of objects included in the array exceed maximum allowed for this device.", "details": { "path": [ "credentials", "2000" ], "maxItems": 2000 } } ] } } ] } Action Lifecycle Event Fields Title Description Title Field Name Description Data Type eventType the name of the event String actionId the uuid assigned to the action request ID deviceId the uuid of the device to be acted upon ID installationId the uuid of the installation that has claimed the device being acted upon ID createdAt ISO8601 format UTC timestamp when event was published to Yonomi event log DateTime actionName Name of the Action Mutation submitted in the request String actionStatus Current status of the action request. See table below for values. actionStatusEnum actionParameters The inputs submitted with the mutation request. See individual trait documentation for mutation inputs Object errors Array of applicable error objects that caused failure of the action. See below list of errors for more information eventErrorObjects Array actionStatusEnum Values Title Description Value Description AWAITING_DATA Used on bulk-data trait actions. Action has been created but requires user to upload data file to the provided uploadUrl before action can be communicated to device. PENDING Action has been created. Data has been validated and request has been communicated to device. Pending confirmation from device that request has completed or failed. REJECTED Action is confirmed as having failed. See provided error details for more information. New action request may be submitted, but there is no further process for this action. RESOLVED Action is confirmed as having completed successfully. eventErrorObjects Title Description Title Code Message Details ERR_ACTION_SUPERSEDED Superseding action request was received while this action was pending. --- ERR_INTERNAL_SERVER An unspecified error occurred. --- ERR_INTERNAL_SERVER An unknown error occurred. --- ERR_DEVICE_RESET Device was reset while action was pending. --- ERR_ACTION_NOT_SUPPORTED Device model does not support requested action. --- ERR_ACTION_EXPIRED Action has expired due to communication timeout with device. Check device connectivity status and try again. --- ERR_DATE_IN_PAST Requested dateTime value(s) must not be before current device dateTime. --- ERR_FIRMWARE_SCHEDULE_SEQUENCE Firmware install dateTime must be later than the download dateTime --- ERR_URL_EXPIRED UploadUrl provided for this action has expired without required data file being uploaded. --- ERR_DATA_FILE_VALIDATION_FAILED The provided data file failed validation and could not be uploaded to the device. array(dataFileValidationErrors) ERR_SSID_NOT_FOUND Could not connect to wifi; input SSID could not be found. --- ERR_INVALID_CREDENTIAL Could not connect to wifi; input incorrect network password --- ERR_TIMEOUT Process timed out, please retry. If issue continues to occur, contact support. --- ERR_UNSUPPORTED_SECURITY_PROTOCOL Could not connect to wifi; selected security protocol is not supported. --- ERR_ CONNECTION_FAILURE Could not connect to wifi; Successfully connected to access point, but could not connect to device cloud IoT Hub. Retry connection, and contact support if issue continues. --- ERR_DEAUTHENTICATION Could not connect to wifi due to wifi de-authentication. --- ERR_WIFI_DISASSOCIATED Could not connect to wifi due to wifi disassociation. --- dataFileValidationErrors Objects Title Description Title Code Message Details MISSING_FIELD At least 1 required field is missing from the object shape. path, expected, received INVALID_FIELD Field does not match one of the allowed fields for this object. path INVALID_STRING Value must be a valid, non-empty string. path INVALID_ENUM Value is not a valid enum. path, expected, received INVALID_DATE Value is not a dateTime string conforming to the ISO8601 standard of YYYY-MM-DDThh:mm:ss.sssZ path VALUE_OUT_OF_RANGE Value is not within the acceptable range path, min, max INVALID_CREDENTIAL_VALUE Value is not a valid 16-byte, hexadecimal string with exactly 32 characters. path INVALID_PRIMARY_SCHEDULE_ID Value must match the ‘id’ of a schedule object contained within this data file. path RRULE_CONFIGURATION_ERROR The object ‘recurrenceRule' provided is not an acceptable configuration for the designated 'scheduleType’. path ARRAY_EXCEEDS_MAX_ITEMS Count of objects included in the array exceed maximum allowed for this device. path, maxItems PARSE_FAILED An unknown error occurred while parsing data file. path
  • [Device Reported State](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait/reported-state-flows.md): Introduction to Device Reported States A trait state is a data field that directly represents a property attribute or setting of the physical device. The values in these reported state fields represent the last known state of the device. When device is online, changes to state will be reported in near-real time, but an offline device will report all changes upon re-connection to the cloud. Examples of trait state fields are batteryPercentage, lockedState, and deadboltStatus. Trait Reported State Flows There are 2 primary use cases that determine reported state flows: PACs software needs to query device reported state to verify their device state database matches the device. PACs software needs to be notified / informed when device reported states are updated so that they can inform their users For each of these use cases, when dealing with a bulk data type trait, there may be additional steps required. These are outlined in the followning flow diagrams. Querying Device Reported State Ingesting State Updated Events Reported State Query A user may submit on-demand queries through the Yonomi Platform to get last reported device state information. To do that, a GraphQL query of the device should be submitted. This query should contain a fragment ( e.g. ... on LockV1DeviceTrait ) for each individual trait and each fragment should be tailored to include the trait states the user desires state data for. See individual trait documentation for definition of the data that can be queried for each trait. Required Headers All device state queries require the following header be included regardless which trait / states are being queried. Title Description Title Description FieldName Description Value Required x-allegion-installation-Id UUID of the installation that owns the device. Authentication will validate that bearer token has authorization to mutate against this installationId and that the requested deviceId is owned by that installation. If either fail, request will be rejected. ID! true Request Body Example GraphQL query QueryDevice ($deviceId: ID!) { device (deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") id traits { name ... on LockV1DeviceTrait { state { lockState { reported { value } } } }, ... on AutoRelockDelaySettingsV1DeviceTrait { state { autoRelockDelay { reported { value } } } } } } } Request Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "LockV1", "state": { "lockState": { "reported": { "value": "SECURED" } } } }, { "name": "AutoRelockDelaySettingsV1", "state": { "autoRelockDelay": { "reported": { "value": 30 } } } } ] } } } See Trait Overview: Synchronous Request Errors for information on potential errors that may be returned State Updated Events See Device Events for information on subscribing to webhooks or submitting event queries. State Updated Event Shape Examples DEVICE_STATE_UPDATED Event Event that is published when a reported state is updated for a standard type trait. Plain text { "eventType": "DEVICE_STATE_UPDATED", "id": "5ca466bc-2500-4d8d-a943-0d9245a13c6e", "createdAt": "2024-12-20T14:49:55.000Z", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "traitName": "AutoRelockDelaySettingsV1", "states": [ { "autoRelockDelay": { "reported": { "value": 30 } } } ] } DEVICE_BULK_DATA_STATE_UPDATED Event Event that is published when a reported state is updated for a bulk data type trait Plain text { "eventType": "DEVICE_STATE_UPDATED", "id": "5ca466bc-2500-4d8d-a943-0d9245a13c6e", "createdAt": "2024-12-20T14:49:55.000Z", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "traitName": "credentialsAndSchedulesV1", "states": [ { "downloadUrl": { "reported": { "value": "https://exampleDownloadUrl.com" } }, "downloadUrlExpiresAt": { "reported": { "value": "2024-12-21T14:49:55.000Z" } } } ] } Note: The above is the shape users get for this event when they subscribe and recieved via webhook. YP only maintains reported state data files for last reported state. As such when querying for event history, the states array does not apply. Reported State Updated Event Fields Title Description Title Field Name Description Data Type eventType the name of the event String id the uuid assigned to the published event ID deviceId the uuid of the device that was updated ID installationId the uuid of the installation that has claimed the updated device ID createdAt ISO8601 format UTC timestamp when event was published to Yonomi event log DateTime traitName Name of the trait that defines the updated state(s). See individual trait documentation for available traitNames. String states Array of applicable state fields and values defined for the trait. The shape nested under this field for each individual trait matches the shape nested under the “state” object of that traits' Device State Query GQL response (see example response shape included in the Device Trait documentation. Object Array - See Individual Trait documentation for state object shape
  • [Device Notifications](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait/notification-flows.md): Introduction to Device Notifications A trait notification is an event published by the device to communicate transient information to the user (e.g. low battery, device locked/unlocked audits, etc.). There are 2 different types of notifications: WARNING notifications are critical alerts that require user attention and potentially action to address. An example would be warningBatteryLevel event publishing when battery level is low or critical to warn user to replace batteries. INFO notifications are informational events published for user to know what is happening with their device. An example would be the infoUserAccessLockEvent notification publishing an audit event when a credential is presented to the lock. Trait Notification Flows Notification Reported Events See device events for information on subscribing to webhooks or submitting event queries. DEVICE_NOTIFICATION_REPORTED Event Event that is published when the device publishes a notification regardless of the trait type (standard or bulk data) or notification type (info or warning). Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningBatteryLevel", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "batteryV1", "message": "Device battery level is CRITICAL.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "batteryLevel": "CRITICAL" } } ] } DEVICE_NOTIFICATION_REPORTED Event Fields Title Description Title Field Name Description Data Type eventType the name of the event String category do not use this field, to be deprecated String notificationName the name of the notification that was published. See individual trait documentation for details String notificationType the type of notification (INFO or WARNING) String type do not use this field, to be deprecated String createdAt ISO8601 format UTC timestamp when event was published to Yonomi event log DateTime sampledAt ISO8601 format UTC timestamp when event occurred at the device DateTime installationId the uuid of the installation that has claimed the updated device ID deviceId the uuid of the device that was updated ID traitName Name of the trait that defines the updated state(s). See individual trait documentation for available traitNames. String message user friendly message explaining the notification String id the uuid assigned to the published event ID details Additional fields that apply specifically to that notification. See notification definition on individual trait documentation for applicable details. Object
  • [Synchronous Request Errors](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait/synchronous-request-errors.md): When any trait mutation or query request is submitted to the YP Graph, the request may return a success response that includes the requested response selection set data OR an error response containing one of the following error codes. Title Description code message ACTION_NOT_SUPPORTED Action {{actionName}} is not supported by device {{deviceId}} DEVICE_NOT_FOUND Device {{deviceId}} could not be found. VALUE_OUT_OF_RANGE {{fieldName}} requested value {{value}} is out of range acceptable to device. TIMEOUT_ERROR Request has failed due to server time out. Please retry sending the request. BAD_USER_INPUT <Uses Apollo GraphQL Standard message> FORBIDDEN <Uses Apollo GraphQL Standard message> GRAPHQL_PARSE_FAILED <Uses Apollo GraphQL Standard message> GRAPHQL_VALIDATION_FAILED <Uses Apollo GraphQL Standard message> INTERNAL_SERVER_ERROR An unspecified error has occurred. PERSISTED_QUERY_NOT_FOUND <Uses Apollo GraphQL Standard message> PERSISTED_QUERY_NOT_SUPPORTED <Uses Apollo GraphQL Standard message> UNAUTHENTICATED <Uses Apollo GraphQL Standard message> DEVICE_RESET_REQUIRED Device ownership claiming failed as device is not in factory default state. Please reset device to factory settings before retrying the claim process. CANNOT_CLAIM Device ownership claiming failed as submitted claim token is not valid for a claimable device. Please retry the claim process with a valid claim token.
  • [Device Model Supported Trait Capabilities](https://developers.yonomi.cloud/devicemanagement/overview-introduction-to-trait/device-model-supported-trait-capabilities.md): Device Capability Files Each supported device model has a corresponding capability JSON file that describes the exact Device Trait (e.g., LockV1) operations and values available for that model. Use these files to configure which fields, settings, and notifications your application surfaces for a given device. Capability files reflect Device Trait support based on the latest supported firmware version for each device model. If a device is running an older firmware version, some operations or enum values listed in the file may not be available until the device is updated to the latest firmware. Correlating a Device to Its File Query device.trait.DeviceInfoV1.state.model.reported.value for the connected device and match the returned value against the Model column in the table below to identify the correct capability file. File Contents Each capability file is a JSON document containing the following top-level fields: model — The device model identifier (matches the Device Model column in the table below). modelId — A short identifier for the device hardware model (e.g., Xe360DBRTWFMTD ). Provided as reference context alongside the model field. supportedCapabilities — A map of Device Trait keys to their supported operations, keyed by Device Trait name in PascalCase (e.g., LockV1DeviceTrait ). Each entry contains: queryFields — State fields that can be read for this device. Enum fields include the exact set of values the device can report. Scalar fields (String, Int, DateTime) are listed without value constraints — the device always returns the raw reported value. actionMutations — Mutations that can be invoked on this device. Inputs include the accepted enum values or scalar type. The actionType field identifies the mutation pattern; refer to the Action Mutation Overview for flow diagrams by action type. notificationEvents — Event names the device can emit. What These Files Do Not Include The following are intentionally omitted because they are invariant across all devices and defined in the Device Trait API documentation: UNSUPPORTED and UNKNOWN enum values — These sentinel values are excluded from query field enum lists. Any device may return them in error conditions, but they do not represent supported device states on the happy path and should not drive UI logic. Action mutation response fields — Fields such as actionId , deviceId , and traitName are returned by every mutation on every device. Bulk data mutations (e.g., credential and schedule URL requests) additionally return uploadUrl and uploadUrlExpiresAt . These are documented in the individual Device Trait API pages and do not vary by device model. Query range and length constraints — Device state fields always return the raw value reported by the device. Integer ranges, string lengths, and similar constraints are not applied to reported state and are therefore not included. deviceId action input — Required on every mutation across all devices and models. Defined once in the API documentation rather than repeated per capability file. Accessing These Files Device capability files are not available via API query through the Device Trait interface. Use the hyperlinks in the table below to access each file directly. You may programmatically fetch a file from its URL if your system requires it at runtime; files are safe to cache and are updated only when a new device model version is onboarded or when mapping updates are released. Device Capabilities File Matrix Users with access to the Allegion GitHub repos for downloading mobile SDKs and other documents have access to the below links. If you do not have access, please contact Yonomi Platform Customer Success. Title Description Title Description Device Model Model ID JSON Supported Capabilities File URL File Last Updated xe360arc Xe360AEweRTWFIK xe360arc_Xe360AEweRTWFIK.json 2026-06-22 xe360b-wf Xe360UweRTWFB xe360b-wf_Xe360UweRTWFB.json 2026-06-11 xe360d-wf Xe360UweRTWFD xe360d-wf_Xe360UweRTWFD.json 2026-06-11 xe360ecyl Xe360EweEC xe360ecyl_Xe360EweEC.json 2026-06-11 xe360elc Xe360AEweRTWFIK xe360elc_Xe360AEweRTWFIK.json 2026-06-11 xe360elu Xe360EweRTWFIU xe360elu_Xe360EweRTWFIU.json 2026-06-11 xe360i-wf Xe360UweRTWFI xe360i-wf_Xe360UweRTWFI.json 2026-06-11 xe360mt-wf Xe360DBRTWFMTD xe360mt-wf_Xe360DBRTWFMTD.json 2026-06-11 Device Capabilties File Change Log 2026-06-22 | Added file for xe360arc device model. 2026-06-11 | Initial files published.
• [Device Traits](https://developers.yonomi.cloud/devicemanagement/traits.md): AutoRelockDelaySettingsV1 BatteryV1 BeeperSettingsV1 BleCredentialSettingsV1 BleV1 ConnectivityEventSettingsV1 ConnectivityV1 CredentialsAndSchedulesV1 CredentialsSettingsV1 DeviceInfoV1 DeviceResetV1 DeviceSchedulesV1 DeviceTimeV1 DoorPositionEventSettingsV1 DoorPositionV1 ExtendedAutoRelockDelaySettingsV1 FirmwareV1 ForcedEntryV1 HolidaySchedulesV1 LockEventSettingsV1 LockV1 NoTourV1 PowerSourceV1 ReaderSettingsV1 TimeZoneSettingsV1 WifiSettingsV1
  • [AutoRelockDelaySettingsV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/autorelockdelaysettingsv1-copy-2.md): Information regarding device that supports auto relock delay settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows AutoRelockDelaySettingsV1SetAutoRelockDelay action Modifies the auto relock delay value. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields AutoRelockDelaySettingsV1SetAutoRelockDelayArgs! false AutoRelockDelaySettingsV1SetAutoRelockDelayArgs Fields Title Description Title Description Field Name Description Data Type Nullable autoRelockDelay The amount of time in seconds that the lock waits before relocking after a normal unlock event int! false GQL Examples Request Example Plain text mutation AutoRelockDelaySettingsV1SetAutoRelockDelay { AutoRelockDelaySettingsV1SetAutoRelockDelay( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { autoRelockDelay: 30 } ){ deviceId actionId } } Response Example Plain text { "data": { "AutoRelockDelaySettingsV1SetAutoRelockDelay": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions autoRelockDelay State The amount of time in seconds that the lock waits before relocking after a normal unlock event Data Type: Integer Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on AutoRelockDelaySettingsV1DeviceTrait { name state { autoRelockDelay { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "AutoRelockDelaySettingsV1", "state": { "autoRelockDelay": { "reported": { "value": 30 } } } } ] } } }
  • [BatteryV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/new-trait-template-copy-1.md): Information regarding device that uses battery as sole or one of the power source. Trait Type: Standard Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions batteryLevel State Indicates the battery level based on the reporting done by the device. Does not communicate the percentage the device considers to enter each state. Data Type: Enum Valid Values Title Description Enumerated String Description UNSUPPORTED Device does not report data for this state. NORMAL batteryLevel is sufficient for normal device operation. LOW batteryLevel is getting low, consider replacing batteries soon to prevent loss of device functionality. CRITICAL batteryLevel is critical, replace batteries immediately to prevent loss of device functionality. Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on BatteryV1DeviceTrait{ name state { batteryLevel{ reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "BatteryV1", "state": { "batteryLevel": { "reported": { "value": "NORMAL" } } } } ] } } } Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. infoBatteryPercentage Information on the battery percentage. Details Fields Title Description Title Field Name Description Data Type percentage Battery percentage as an integer. int Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoBatteryPercentage", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "batteryV1", "message": "Current battery level is at 90%", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "percentage": 90 } } ] } warningBatteryLevel Warning on battery level reaching low or critical. Details Fields Title Description Title Field Name Description Data Type status Reported battery level. LOW, CRITICAL Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningBatteryLevel", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "batteryV1", "message": "Device battery level is CRITICAL", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "batteryLevel": “CRITICAL” } } ] }
  • [BeeperSettingsV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/autorelockdelaysettingsv1-trait-copy-2.md): Information regarding the device beeper settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows BeeperSettingsV1SetBeeperSetting action Modify the beeper settings on the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields BeeperSettingsV1SetBeeperSettingArgs! false BeeperSettingsV1SetBeeperSettingArgs Fields Title Description Title Description Field Name Description Data Type Nullable beeperSetting Desired value for the beeperSetting setting. BeeperSettingArgEnums! false BeeperSettingArgEnums Values Title Description Enumerated String Description ON_NORMAL Beeper is on and will sound normally at the device. DISABLED Beeper has been turned off and will not sound at the device. GQL Examples Request Example Plain text mutation BeeperSettingsV1SetBeeperSetting { BeeperSettingsV1SetBeeperSetting( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { beeperSetting: "ON_NORMAL" } ){ deviceId actionId } } Response Example Plain text { "data": { "BeeperSettingsV1SetBeeperSetting": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions beeperSetting State Indicates if the beeper setting is disabled and if not the method used for it. Data Type: Enum Valid Values Title Description Enumerated String Description ON_NORMAL Beeper is on and will sound normally at the device. DISABLED Beeper has been turned off and will not sound at the device. UNSUPPORTED Device does not report values for this field. Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on BeeperSettingsV1DeviceTrait { name state { beeperSetting{ reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "BeeperSettingsV1", "state": { "beeperSetting": { "reported": { "value": "ON_NORMAL" } } } } ] } } }
  • [BleCredentialSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/blecredentialsettingsv1.md): Manage BLE credential reader settings at the device. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows BleCredentialSettingsV1SetBleCredentialSettings action Modify the BLE credential reader settings of the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields BleCredentialSettingsV1SetBleCredentialArgs! false BleCredentialSettingsV1SetBleCredentialArgs Fields Title Description Title Description Field Name Description Data Type Nullable setBleCredentialSettings The desired value for whether the BLE credential reader is enabled. setBleCredentialSettingEnums false bleCredentialPerformance The desired value for the advertising rate of the BLE credential reader. bleCredentialPerformanceEnums false bleCredentialReadingRange The desired value for the BLE credential reader read-range. bleCredentialReadingRangeEnums false setBleCredentialSettingEnums Values Title Description Enumerated String Description ENABLED Mobile bluetooth credential support is enabled. DISABLED Mobile bluetooth credential support is disabled. bleCredentialPerformanceEnums Values Title Description Enumerated String Description MAX BLE credential reader is set to maximum advertising rate. NORMAL BLE credential reader is set to normal advertising rate. bleCredentialReadingRangeEnums Values Title Description Enumerated String Description SHORT BLE credential reader is set to short read range. LONG BLE credential reader is set to long read range. GQL Examples Request Example Gql mutation BleCredentialSettingsV1SetBleCredentialSettings { BleCredentialSettingsV1SetBleCredentialSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { setBleCredentialSettings: “ENABLED”, bleCredentialPerformance: “MAX”, bleCredentialReadingRange: “LONG” } ){ deviceId actionId } } Response Example JSON { "data": { "BleCredentialSettingsV1SetBleCredentialSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions bleMobileCredentialSetting State Current setting value for whether the BLE credential reader is enabled. Data Type: bleMobileCredentialSettingEnums bleMobileCredentialSettingEnums Values Title Description Enumerated String Description ENABLED Mobile bluetooth credential support is enabled. DISABLED Mobile bluetooth credential support is disabled. UNSUPPORTED Device does not report values for this field. bleCredentialPerformance State Current setting value for the advertising rate of the BLE credential reader. Data Type: bleCredentialPerformanceEnums bleCredentialPerformanceEnums Values Title Description Enumerated String Description MAX BLE credential reader is set to maximum advertising rate. NORMAL BLE credential reader is set to normal advertising rate. UNSUPPORTED Device does not report values for this field. bleCredentialReadingRange State Current setting value for the BLE credential reader read-range. Data Type: bleCredentialReadingRangeEnums bleCredentialReadingRangeEnums Values Title Description Enumerated String Description SHORT BLE credential reader is set to short read range. LONG BLE credential reader is set to long read range. UNSUPPORTED Device does not report values for this field. Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on BleCredentialSettingsV1DeviceTrait { name state { bleMobileCredentialSetting { reported { value } } bleCredentialPerformance { reported { value } } bleCredentialReadingRange { reported { value } } } } } } } Response Example JSON { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "BleCredentialSettingsV1", "state": { "bleMobileCredentialSetting": { "reported": { "value": "ENABLED" } }, "bleCredentialPerformance": { "reported": { "value": "MAX" } }, "bleCredentialReadingRange": { "reported": { "value": "LONG" } } } } ] } } }
  • [BleV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/batteryv1-copy-1.md): Information regarding the device BLE system. Trait Type: Standard Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions bleSecureElementVersion State Indicates the secure element version of the BLE subsystem. Data Type: String bleBootloaderVersion State Indicates the boot loader version of the BLE subsystem. Data Type: String bleApplicationVersion State Indicates the boot loaded application version of the BLE subsystem. Data Type: String Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on BleV1DeviceTrait{ name state { bleSecureElementVersion { reported { value } }, bleBootloaderVersion{ reported { value } }, bleApplicationVersion{ reported { value } }, } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "BleV1", "state": { "bleSecureElementVersion": { "reported": { "value": "SE:01.02.16" } }, "bleBootloaderVersion": { "reported": { "value": "BL:02.04.000002" } }, "bleApplicationVersion": { "reported": { "value": "APP:01.00.765924" } } } } ] } } }
  • [ConnectivityEventSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/connectivityeventsettingsv1.md): Information regarding the connectivity event settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows ConnectivityEventSettingsV1SetConnectityEventSettings action Modify writable connectivity event settings states. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields connectivityEventSettingsV1SetConnectityEventSettingsArgs! false ConnectivityEventSettingsV1SetConnectityEventSettingsArgs Fields Title Description Title Description Field Name Description Data Type Nullable receiveWifiConnectionEvents The desired device value for receiveWifiConnectionEvents receiveWifiConnectionEventsEnums! false receiveWifiConnectionEventsEnums Values Title Description Enumerated String Description ENABLED receiveWifiConnectionEvents is enabled. DISABLED receiveWifiConnectionEvents is disabled. GQL Examples Request Example Plain text mutation ConnectivityEventSettingsV1SetConnectityEventSettings { ConnectivityEventSettingsV1SetConnectityEventSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { receiveWifiConnectionEvents: “ENABLED" } ){ deviceId actionId } } Response Example Plain text { "data": { "ConnectivityEventSettingsV1SetConnectityEventSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions receiveWifiConnectionEvents State Setting to determine if notification should publish whenever device connects/disconnects with wifi network. Data Type: receiveWifiConnectionEventsEnums receiveWifiConnectionEventsEnums Values Title Description Enumerated String Description ENABLED receiveWifiConnectionEvents is enabled. DISABLED receiveWifiConnectionEvents is disabled. UNSUPPORTED Device does not report values for this field. Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { name ... on ConnectivityEventSettingsV1DeviceTrait { name state { receiveWifiConnectionEvents { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "ConnectivityEventSettingsV1", "state": { "receiveWifiConnectionEvents": { "reported": { "value": "ENABLED" } } } } ] } } }
  • [ConnectivityV1](https://developers.yonomi.cloud/devicemanagement/traits/connectivityv1.md): Notification events regarding device connectivity to the cloud via any supported communication methods. Trait Type: Standard Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. infoConnectivityStatus Informs if there was event indicating that the device was online or offline at the specified moment. Details Fields Title Description Title Field Name Description Data Type connectivityStatus Informs if the device overall connection status with the cloud regardless of connection type. CONNECTED, DISCONNECTED Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoConnectivityStatus", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "ConnectivityV1", "message": "Device is connected to/from cloud", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "connectivityStatus": "CONNECTED" } } ] } infoBleConnectionFailed Informs if there was event indicating that a mobile device attempted and failed to connect with the device via bluetooth. Details Fields Not applicable to this event. Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoBleConnectionFailed", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "ConnectivityV1", "message": "Attempt to connect mobile bluetooth device failed", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } infoBleConnectivityStatus Informs if there was event indicating that device connected/disconnected with an intermediary mobile device via bluetooth. Details Fields Title Description Title Field Name Description Data Type bleConnectivityStatus Status of connection between device and mobile bluetooth proxy device. CONNECTED, DISCONNECTED Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoBleConnectivityStatus", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "ConnectivityV1", "message": "Mobile device has connected to/from device via bluetooth.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "bleConnectivityStatus": "CONNECTED" } } ] } infoWifiConnectivityStatus Informs if there was event indicating that device connected/disconnected with the active wifi network connection. Details Fields Title Description Title Field Name Description Data Type wifiConnectivityStatus Status of connection between device and active wifi network. CONNECTED, DISCONNECTED Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoWifiConnectivityStatus", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "ConnectivityV1", "message": "Device is connected to/from active wifi network.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "wifiConnectivityStatus": "CONNECTED" } } ] }
  • [CredentialsAndSchedulesV1](https://developers.yonomi.cloud/devicemanagement/traits/credentialsandschedulesv1.md): Manage user credentials and user schedules data on device. Trait Type: Bulk Data CredentialsAndSchedules data files As this is a bulk data trait, interactions will require passing data in separate files rather than as payloads in the API requests and events. The data files passed to Yonomi Platform for writing data to the device as well as files passed from Yonomi Platform for reporting state of the device will have the following schema. Plain text { "credentials": [], "schedules": [] } The “credentials” array may be left empty if the device is not to have any authorized credentials. Otherwise, this array should be populated with credential objects (See the “ Defining CredentialsAndSchedules data objects ” page). The “schedules” array may be populated with Always Active, Temporary, and/or Recurring schedule type objects (See the “ Defining CredentialsAndSchedules data objects ” page). Any scheduleIds referenced by a credential object under the “credentials” array MUST have an associated schedule object under the “schedules” array. When writing data to the device, data files must include ALL credential and schedule objects desired to be on the device (rather than just the objects to be updated) as sending new data will overwrite existing databases on the device. Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows CredentialsAndSchedulesV1RequestCredentialsAndSchedulesURL action Requests uploadUrl to allow writing a new CredentialsAndSchedules data to a device. Upon getting the URL, users must make a PUT request to that URL with data structure as defined in the "CredentialsAndSchedules data files" section on this page. Uploading the data will result in Asynchronous processing of the data file and uploading to the device. Any error or success responses on the action after uploading the data file will be surfaced as DEVICE_ACTION_UPDATED events. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false GQL Examples Request Example Plain text mutation CredentialsAndSchedulesV1RequestCredentialsAndSchedulesURL { CredentialsAndSchedulesV1RequestCredentialsAndSchedulesURL( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" ) { deviceId actionId uploadUrl uploadUrlExpiresAt } } Response Example Plain text { "data": { "CredentialsAndSchedulesV1RequestCredentialsAndSchedulesURL": { "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "uploadUrl": "https://fakefileurl.com", "uploadUrlExpiresAt": "2025-04-25T15:46:18.181Z" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions downloadUrl state Url where data file containing all user credentials and user schedules data reported from device (schema as defined in the "CredentialsAndSchedules data files" section on this page). File includes entire dataset, not just the changes since last report. Data Type: URL downloadUrlExpiresAt state timestamp when the downloadUrl is set to expire. Data Type: string (Value formatted as an ISO 8601 UTC dateTime) Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on CredentialsAndSchedulesV1DeviceTrait { name state { downloadUrl { reported { value } } downloadUrlExpiresAt { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "CredentialsAndSchedulesV1", "state": { "downloadUrl": { "reported": { "value": "https://fakefileurl.com" } }, "downloadUrlExpiresAt": { "reported": { "value": "2025-04-25T15:56:28.513Z" } } } } ] } } }
    • [Defining CredentialsAndSchedules data objects](https://developers.yonomi.cloud/devicemanagement/traits/credentialsandschedulesv1/defining-bulk-data-trait-objects.md): Credentials Objects Credential objects are data elements that nest into the “credentials” array of the CredentialsAndSchedulesV1 data file. These objects define individual credentials that are used to authenticate users at the device. Example Credential Object Schema Plain text { "id": "UniquePacSystemCredentialIdentifier1", "credential": "0AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA1", "active": "ACTIVE", "transportTechnology": "PROX", "function": "NORMAL", "activation": "2023-08-09T09:58:33.099Z", "expiration": "2023-09-09T09:58:33.099Z", "primarySchedules": [ { "id": "UniquePacSystemScheduleIdentifier1" }, { "id": "UniquePacSystemScheduleIdentifier2" } ] } Credential Fields Title Description Title Description Title Description Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string credential Primary credential hexadecimal code recognized by device string! true Must be exactly 32 hexadecimal char. If credential hex code has fewer than 32 char, pad the ending digits with “F” to denote those bits do not apply. active Represents the active / inactive status of a credential enum string! true “ACTIVE” or “INACTIVE” transportTechnology Allows user to add security validation to only allow presented credential if it is the correct technology. enum string! true See transportTechnologyEnum table for values. function Functionality that credential should do at device enum string! true See functionEnum table for values. activation UTC dateTime that credential should start being active string! true "YYYY-MM-DDThh:mm:ss.sssZ" format dateTime value expiration UTC dateTime that credential should expire string! true "YYYY-MM-DDThh:mm:ss.sssZ" format dateTime value primarySchedules Array of schedule objects that dictate when the credential is to be allowed through device. objectArray! true Array of objects like: { "id": "$scheduleId" } . Note: Any schedule referenced in the array must be contained within the same data file as the credential. transportTechnologyEnum Title Description Enum String Description “ANY” Allows credential to be accepted by device no matter what technology it uses “PROX” Allows credential to be accepted by device only if it uses 125Khz Proximity technology “UID” Allows credential to be accepted by device only when credential is a smart credentials' unencrypted UID or serial number. “MIFARE_CLASSIC” Allows credential to be accepted by device only if it uses Mifare Classic technology “MIFARE_DESFIRE” Allows credential to be accepted by device only if it uses Mifare Desfire technology “APPLE_NFC” Allows credential to be accepted by device only if it uses Apple NFC technology “ANDROID_MIFARE2GO” Allows credential to be accepted by device only if it uses Android Mifare-2-Go technology “ALLEGION_BLE” Allows credential to be accepted by device only if it uses Allegion Bluetooth technology functionEnum Title Description Enum String Description “NORMAL” Credential momentarily unlocks a secured device. Device relocks automatically based on the autoRelockDelay settings. Does not function when device is in Frozen mode. “NORMAL_EXTENDED” Credential momentarily unlocks a secured device. Device relocks automatically based on the ExtendedAutoRelockDelay settings. Does not function when device is in Frozen mode. “ONE_TIME_USE” Same function as a NORMAL credential, but only valid for a single use. “ONE_TIME_EXTENDED” Same function as a NORMAL_EXTENDED credential, but only valid for a single use. “PASS_THRU” Credential momentarily unlocks a secured device. Device relocks automatically based on the autoRelockDelay settings. Allows passage even when device is in Frozen mode. “PASS_THRU_EXTENDED” Credential momentarily unlocks a secured device. Device relocks automatically based on the ExtendedAutoRelockDelay settings. Allows passage even when device is in Frozen mode. “TOGGLE” Toggles device between secured and maintained passage modes. “FREEZE” Toggles device between normal and frozen modes. Device will remain in current state (secured, passage, etc) and only change mode between frozen or normal. “LOCKDOWN” Puts device is frozen secured state no matter what state it was in before. “BLOCKED” Credential is blocked and is no longer valid. Schedules Objects Schedule objects are data elements that nest into the “schedules” array of the CredentialsAndSchedulesV1 data file. These objects define individual schedules for credential behaviors (e.g. times when credential is authorized). There are 3 types of schedules that may be used, each having their own shape. Always Active Schedules An Always Active schedule is used when a credential or device behavior has a start dateTime, but then continues perpetually thereafter with no scheduled end. Note: Due to restrictions on many devices this will actually result in the scheduled behavior duration of 23h 59m 59s per day for each day after start dateTime, thus leaving 1s per day when the scheduled behavior does not apply. Example Always Active Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "ALWAYS_ACTIVE", "dtStart": "2024-04-01T08:00:00" } Always Active Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "ALWAYS_ACTIVE" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Temporary Schedules A temporary is used when a credential or device behavior has a start dateTime, but then continues perpetually thereafter until a scheduled end dateTime. Note: Due to restrictions on many devices this will actually result in the scheduled behavior duration of 23h 59m 59s per day for each day after start dateTime, thus leaving 1s per day when the scheduled behavior does not apply up until the schedule expires. Example Temporary Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "TEMPORARY", "dtStart": "2024-04-01T08:00:00", "temporaryRule": { "until": "2024-04-30T17:00:00" } } Temporary Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "TEMPORARY" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value temporaryRule Object field nesting additional fields required for a temporary schedule object! true temporary.until Device local DateTime when schedule expires. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Recurring Schedules A recurring schedule is used when a credential or device behavior needs a complex set of rules to apply it to specific time ranges and/or frequencies. Each recurring schedule starts each occurence at the same time (based on the specified start time) and ends the occurence after a specified duration. There are 4 different types of recurring schedule that allow a user to control the frequency and pattern of each occurence. Note: Recurring Schedules do not support exception rules within the schedule definition. Daily Recurring Schedules A daily recurring schedule applies the occurence continuously every day until the schedule expires (if an until dateTime was given), but it differs from an Always Active or Temporary schedule in that the duration can't have a full day duration. This sort of schedule might be used if the device behavior was to be applied during consistent business hours every day of the week (e.g. 6am to 10pm, 7 days a week) Example Daily Recurring Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T08:00:00", "recurrenceRule": { "duration": 32400, "rrule": { "frequency": "DAILY", "until": "2030-01-01T17:00:00" } } } Daily Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration < 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "DAILY" recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Weekly Recurring Schedules A weekly recurring schedule applies the occurence on the specified days of week for each week until the schedule expires (if an until dateTime was given). This sort of schedule might be used if the device behavior was to be applied during consistent business hours but only on specific days of the week (e.g. 8am to 5pm, Monday through Friday). Example Weekly Recurring Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T08:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "WEEKLY", "byWeekDay": [ { "day": "MO" }, { "day": "TU" }, { "day": "WE" }, { "day": "TH" }, { "day": "FR" } ], "until": "2030-01-01T17:00:00" } } } Weekly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "WEEKLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Monthly Recurring Schedules A monthly recurring schedule applies the occurence on the specified monthDay(s) or specified week of the month for every month until the schedule expires (if an until dateTime was given). This sort of schedule might be used if the device was to be applied consistently on particular days of the month (e.g. 1st and 15th of each month), a specific week of the month (e.g. the 2nd week of each month), and/or specific weekday occurences of the month (e.g. the last occurring Friday of each month). Note: Monthly schedules can recur by weekDay patterns or by monthDay patterns, but they can't have both, see example schema shapes for details. Example Monthly Recurring Schedules Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T08:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "MONTHLY", "byWeekDay": [ { "day": "FR", "nth": -1 } ], "until": "2030-01-01T17:00:00" } } }, { "id": "UniquePacSystemScheduleIdentifier2", "scheduleType": "RECURRING", "dtStart": "2024-04-01T08:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "MONTHLY", "byMonthDay": [ { "day": 1 } ], "until": "2030-01-01T17:00:00" } } } Monthly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule objectArray! true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "MONTHLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.byWeekDay.nth Limits recurrence of the particular weekday to only the single instance that occurs within the nth week of the month. int! true Where nth > 0, week count is from start of month (nth = 1 means first week of month), where nth < 0, week count is from end of month (nth = -1 means last week of the month). Note: All nth values must be the same for a single schedule. recurrenceRule.rrule.byMonthDay Array of objects that define which days of the month the schedule should be active. objectArray! true recurrenceRule.rrule.byMonthDay.day Calendar day of the month that the schedule should be active. int! true 1 to 31 recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Yearly Recurring Schedules A yearly recurring schedule gives the control of a month recurring schedule, but it allows the occurences to occur only in specified months of the year. This sort of schedule might be used to schedule specific occurences that occur less frequently than monthly (e.g. December 25th). Note: Yearly schedules can recur by weekDay patterns or by monthDay patterns, but they can't have both, below details the difference. Example Yearly Recurring Schedules Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T08:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "YEARLY", "byWeekDay": [ { "day": "TH", "nth": -1 }, { "day": "FR", "nth": -1 } ], "byMonth": [ { "month": "NOVEMBER" } ], "until": "2030-01-01T17:00:00" } } }, { "id": "UniquePacSystemScheduleIdentifier2", "scheduleType": "RECURRING", "dtStart": "2024-04-01T08:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "YEARLY", "byMonthDay": [ { "day": 24 }, { "day": 25 } ], "byMonth": [ { "month": "DECEMBER" } ], "until": "2030-01-01T17:00:00" } } } Yearly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "YEARLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.byWeekDay.nth Limits recurrence of the particular weekday to only the single instance that occurs within the nth week of the month. int! true Where nth > 0, week count is from start of month (nth = 1 means first week of month), where nth < 0, week count is from end of month (nth = -1 means last week of the month). Note: All nth values must be the same for a single schedule. recurrenceRule.rrule.byMonthDay Array of objects that define which days of the month the schedule should be active. objectArray! true recurrenceRule.rrule.byMonthDay.day Calendar day of the month that the schedule should be active. int! true 1 to 31 recurrenceRule.rrule.byMonth Array of objects that define which months the schedule should be active. objectArray! true recurrenceRule.rrule.byMonth.month The name of the month that the schedule should be active enum string! true "JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE", "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER" recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value
  • [CredentialSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/credentialsettingsv1.md): Information regarding the device credentials settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows CredentialSettingsV1SetCredentialsSettings action Modify the credentials settings on the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields CredentialSettingsV1SetCredentialsSettingArgs! false CredentialSettingsV1SetCredentialsSettingArgs Fields Title Description Title Description Field Name Description Data Type Nullable mifareClassic Desired value for if support for mifareClassic setting. mifareClassicEnums true mifareDesfire Desired value for if support for mifareDesfire setting. mifareDesfireEnums true mifareDesfireLight Desired value for if support for mifareDesfireLight setting. mifareDesfireLightEnums true mifare2Go Desired value for if support for mifare2Go setting. mifare2GoEnums true androidHce Desired value for if support for androidHce setting. androidHceEnums true appleNFC Desired value for if support for appleNFC setting. appleNFCEnums true iClassCredentials Desired value for if support for iClassCredentials setting. iClassCredentialsEnums true iso14443SecurityMethod Desired value for if support for iso14443SecurityMethod setting. iso14443SecurityMethodEnums true iso15693SecurityMethod Desired value for if support for iso15693SecurityMethod setting. iso15693SecurityMethodEnums true nfcConfigCard Desired value for if support for nfcConfigCard setting. nfcConfigCardEnums true mifareClassicEnums Values Title Description Enumerated String Description ENABLED mifareClassic credentials are accepted at device. DISABLED mifareClassic credentials are not accepted at device. mifareDesfireEnums Values Title Description Enumerated String Description ENABLED mifareDesfire credentials are accepted at device. DISABLED mifareDesfire credentials are not accepted at device. mifareDesfireLightEnums Values Title Description Enumerated String Description ENABLED mifareDesfireLight credentials are accepted at device. DISABLED mifareDesfireLight credentials are not accepted at device. mifare2GoEnums Values Title Description Enumerated String Description ENABLED mifareClassic credentials are accepted at device. DISABLED mifareClassic credentials are not accepted at device. androidHceEnums Values Title Description Enumerated String Description ENABLED androidHce credentials are accepted at device. DISABLED androidHce credentials are not accepted at device. appleNFCEnums Values Title Description Enumerated String Description ENABLED appleNFC credentials are accepted at device. DISABLED appleNFC credentials are not accepted at device. iClassCredentialsEnums Values Title Description Enumerated String Description UID_FORTY_BIT_WITH_PARITY iClassCredentials credentials are accepted at device using UID with 40-bit parity. UID_SIXTYFOUR_BIT_MSB iClassCredentials credentials are accepted at device using UID with 64-bit most-significant-bit first. SYMMETRIC_CRYPTOGRAPHIC_SECURITY iClassCredentials credentials are accepted at device using symmetric cryptographic security. DISABLED iClassCredentials credentials are not accepted at device. iso14443SecurityMethodEnums Values Title Description Enumerated String Description UID_ONLY iso14443SecurityMethod credentials are accepted at device using UID only. SYMMETRIC_CRYPTOGRAPHIC_SECURITY iso14443SecurityMethod credentials are accepted at device using symmetric cryptographic security. DISABLED iso14443SecurityMethod credentials are not accepted at device. iso15693SecurityMethodEnums Values Title Description Enumerated String Description UID iso15693SecurityMethod credentials are accepted at device using UID only. DISABLED iso15693SecurityMethod credentials are not accepted at device. nfcConfigCardEnums Values Title Description Enumerated String Description ENABLED nfcConfigCard credentials are accepted at device. DISABLED nfcConfigCard credentials are not accepted at device. GQL Examples Request Example Plain text mutation CredentialsSettingsV1SetCredentialsSettings { CredentialsSettingsV1SetCredentialsSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { mifareClassic: ENABLED mifareDesfire: ENABLED mifareDesfireLight: ENABLED mifare2Go: ENABLED androidHce: ENABLED appleNFC: ENABLED iClassCredentials: UID_FORTY_BIT_WITH_PARITY iso14443SecurityMethod: UID_ONLY iso15693SecurityMethod: UID nfcConfigCard: ENABLED } ) { deviceId actionId traitName } } Response Example Plain text { "data": { "CredentialsSettingsV1SetCredentialsSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions mifareClassic State Indicates whether the MIFARE classic credential settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED mifareClassic credentials are accepted at device. DISABLED mifareClassic credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. mifareDesfire State Indicates whether the MIFARE DESFire credential settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED mifareDesfire credentials are accepted at device. DISABLED mifareDesfire credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. mifareDesfireLight State Indicates whether the MIFARE DESFire light credential settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED mifareDesfireLight credentials are accepted at device. DISABLED mifareDesfireLight credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. mifare2Go State Indicates whether the MIFARE2Go credential settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED mifare2Go credentials are accepted at device. DISABLED mifare2Go credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. androidHce State Indicates whether the Android HCE credential settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED androidHce credentials are accepted at device. DISABLED androidHce credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. appleNFC State Indicates whether the Apple NFC credential settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED appleNFC credentials are accepted at device. DISABLED appleNFC credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. iClassCredentials State Indicates if the iClass credential setting is disable and if not the method used for it. Data Type: Enum Valid Values Title Description Enumerated Value Description UID_FORTY_BIT_WITH_PARITY iClassCredentials credentials are accepted at device using UID with 40-bit parity. UID_SIXTYFOUR_BIT_MSB iClassCredentials credentials are accepted at device using UID with 64-bit most-significant-bit first. SYMMETRIC_CRYPTOGRAPHIC_SECURITY iClassCredentials credentials are accepted at device using symmetric cryptographic security. DISABLED iClassCredentials credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. iso14443SecurityMethod State Indicates if the ISO 14443 security method setting is disable and if not the method used for it. Data Type: Enum Valid Values Title Description Enumerated Value Description UID_ONLY iso14443SecurityMethod credentials are accepted at device using UID only. SYMMETRIC_CRYPTOGRAPHIC_SECURITY iso14443SecurityMethod credentials are accepted at device using symmetric cryptographic security. DISABLED iso14443SecurityMethod credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. iso15693SecurityMethod State Indicates if the ISO 15693 security method setting is disable and if not the method used for it. Data Type: Enum Valid Values Title Description Enumerated Value Description UID iso15693SecurityMethod credentials are accepted at device using UID only. DISABLED iso15693SecurityMethod credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. nfcConfigCard State Indicates whether the NFC config card settings is enabled or disable for the device. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED nfcConfigCard credentials are accepted at device. DISABLED nfcConfigCard credentials are not accepted at device. UNSUPPORTED Device has not yet reported a value for this field. Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on CredentialsSettingsV1DeviceTrait { name state { mifareClassic { reported { value } } mifareDesfire { reported { value } } mifareDesfireLight { reported { value } } mifare2Go { reported { value } } androidHce { reported { value } } appleNFC { reported { value } } iClassCredentials { reported { value } } iso14443SecurityMethod { reported { value } } iso15693SecurityMethod { reported { value } } nfcConfigCard { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "CredentialsSettingsV1", "state": { "mifareClassic": { "reported": { "value": "ENABLED" } }, "mifareDesfire": { "reported": { "value": "ENABLED" } }, "mifareDesfireLight": { "reported": { "value": "DISABLED" } }, "mifare2Go": { "reported": { "value": "DISABLED" } }, "androidHce": { "reported": { "value": "DISABLED" } }, "appleNFC": { "reported": { "value": "DISABLED" } }, "iClassCredentials": { "reported": { "value": "UID_FORTY_BIT_WITH_PARITY" } }, "iso14443SecurityMethod": { "reported": { "value": "DISABLED" } }, "iso15693SecurityMethod": { "reported": { "value": "UID" } }, "nfcConfigCard": { "reported": { "value": "DISABLED" } } } } ] } } }
  • [DeviceInfoV1](https://developers.yonomi.cloud/devicemanagement/traits/deviceinfov1.md): Information regarding the device information and action to set display name. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows DeviceInfoV1SetDisplayName action Modify the display name of the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields DeviceInfoV1SetDisplayNameArgs! false DeviceInfoV1SetDisplayNameArgs Fields Title Description Title Description Field Name Description Data Type Nullable displayName The desired friendly name assigned to the device. string! false GQL Examples Request Example GraphQL mutation DeviceInfoV1SetDisplayName { DeviceInfoV1SetDisplayName ( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { displayName: “Unit 102A Entrance XE360D" } ){ deviceId actionId } } Response Example Plain text { "data": { "DeviceInfoV1SetDisplayName": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions displayName State Indicates the friendly name assigned to the device. Data Type: string model State Indicates the product model number. Data Type: string revision State Indicates the revision of the product. Data Type: string serialNumber State Indicates the product serial number. Data Type: string mechanicalVariance State Indicates the mechanical chassis variant assigned to the device Data Type: mechVariantEnums mechVariantEnums Values Title Description Enumerated String Description UNSUPPORTED Device has not yet reported a value for this field. WIDE_EXIT Wide-stile exit device smart trim. MORTISE Mortise style smart lock. TUBULAR Tubular style smart lock. MANUAL_DEADBOLT Manual throw smart deadbolt. MANUAL_INTERCONNECT Interconnected lock with manual throw smart deadbolt. manufacturingDate State Indicates the final manufacturing date of the shipped product assembly. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) insideManufacturingDate State Indicates the final manufacturing date of the device inside escutcheon assembly. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) outsideManufacturingDate State Indicates the final manufacturing date of the device outside escutcheon assembly. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) commissionDate State Indicates the first date of the commissioning of the device. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) daysInUse State Indicates the rolling counts of days in use for the product. Data Type: int Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { traits { ... on DeviceInfoV1DeviceTrait { state { displayName { reported { value } } revision { reported { value } } serialNumber { reported { value } } mechanicalVariance { reported { value } } model { reported { value } } manufacturingDate { reported { value } } insideManufacturingDate { reported { value } } outsideManufacturingDate { reported { value } } commissionDate { reported { value } } daysInUse { reported { value } } } name } } id } } Response Example JSON { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "DeviceInfoV1", "state": { "displayName": { "reported": { "value": "Unit 102A Entrance XE360D" } }, "model": { "reported": { "value": "xe360d" } }, "revision": { "reported": { "value": "--" } }, "serialNumber": { "reported": { "value": "A000000000000001" } }, "mechanicalVariance": { "reported": { "value": "TUBULAR" } }, "manufacturingDate": { "reported": { "value": "2024-12-20T14:49:55.859Z" } }, "insideManufacturingDate": { "reported": { "value": "2024-12-20T14:49:55.859Z" } }, "outsideManufacturingDate": { "reported": { "value": "2024-12-20T14:49:55.859Z" } }, "commissionDate": { "reported": { "value": "2024-12-20T14:49:55.859Z" } }, "daysInUse": { "reported": { "value": 29 } } } } ] } } } Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. warningDeviceSupportRequired Warning that device had a failure requiring manual intervention and/or factory support. Details Fields Title Description Title Field Name Description Data Type cause Name of failed device audit that triggered notification. Provided so customer can give to device technical support as needed for diagnostics. string! Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningDeviceSupportRequired", "notificationType": "WARNING", "actionId": "{{actionId}}", "type": "notification reported", "createdAt": "{{UTC dateTime}}", "sampledAt": "{{UTC dateTime}}", "installationId": "{{installationId}}", "deviceId": "{{deviceId}}", "traitName": "DeviceInfoV1", "message": "Device has experienced critical failure and requires support", "id": "{{eventId}}", "details": { "cause": "ipcAuthFail" } } ] }
  • [DeviceResetV1](https://developers.yonomi.cloud/devicemanagement/traits/deviceresetv1.md): Informs if there was a factory-default reset process initiated, successfully completed, or failed on the device. Trait Type: Standard Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. warningDeviceReset Informs if there was a factory-default reset process initiated, successfully completed, or failed on the device. Details Fields Title Description Title Field Name Description Data Type deviceResetStatus Status of device's factory-default reset process INITIATED, FAILED, COMPLETED Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningDeviceReset", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "DeviceResetV1", "message": "Device reset initiated", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "deviceResetStatus": "INITIATED" } } ] }
  • [DeviceSchedulesV1](https://developers.yonomi.cloud/devicemanagement/traits/credentialsandschedulesv1-copy-1.md): Manage device lock/unlock schedules data on device. Trait Type: Bulk Data DeviceSchedules data files As this is a bulk data trait, interactions will require passing data in separate files rather than as payloads in the API requests and events. The data files passed to Yonomi Platform for writing data to the device as well as files passed from Yonomi Platform for reporting state of the device will have the following schema. Note: If a holiday schedule is applied at the same time as a device schedule, the behavior of the holiday schedule takes precedent. Plain text { "deviceSchedules": [] } The “deviceSchedules” array may be left empty if the device is not to have any deviceSchedules. Otherwise, this array should be populated with deviceSchedule objects (See the “ Defining DeviceSchedules data objects ” page). When writing data to the device, data files must include ALL deviceSchedule objects desired to be on the device (rather than just the objects to be updated) as sending new data will overwrite existing databases on the device. Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows DeviceSchedulesV1RequestDeviceSchedulesURL action Requests uploadUrl to allow writing a new deviceSchedules data to a device. Upon getting the URL, users must make a PUT request to that URL with data structure as defined in the "DeviceSchedules data files" section on this page. Uploading the data will result in Asynchronous processing of the data file and uploading to the device. Any error or success responses on the action after uploading the data file will be surfaced as DEVICE_ACTION_UPDATED events. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false GQL Examples Request Example Plain text mutation DeviceSchedulesV1RequestDeviceSchedulesURL { DeviceSchedulesV1RequestDeviceSchedulesURL( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" ) { deviceId actionId uploadUrl uploadUrlExpiresAt } } Response Example Plain text { "data": { "DeviceSchedulesV1RequestDeviceSchedulesURL": { "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "uploadUrl": "https://fakefileurl.com", "uploadUrlExpiresAt": "2025-04-25T15:46:18.181Z" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions downloadUrl state Url where data file containing all device lock/unlock schedules data reported from device. File includes entire dataset, not just the changes since last report. See separate documentation for file requirements Data Type: URL downloadUrlExpiresAt state T imestamp when the downloadUrl is set to expire. Data Type: string (Value formatted as an ISO 8601 UTC dateTime) Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on DeviceSchedulesV1DeviceTrait{ name state { downloadUrl { reported { value } } downloadUrlExpiresAt { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "DeviceSchedulesV1", "state": { "downloadUrl": { "reported": { "value": "https://fakefileurl.com" } }, "downloadUrlExpiresAt": { "reported": { "value": "2025-04-25T15:56:28.513Z" } } } } ] } } }
    • [Defining DeviceSchedules data objects](https://developers.yonomi.cloud/devicemanagement/traits/credentialsandschedulesv1-copy-1/defining-credentialsandschedules-data-objects-copy-1.md): DeviceSchedules Objects DeviceSchedule objects are data elements that nest into the “deviceSchedules” array of the DeviceSchedulesV1 data file. These objects define individual schedules for device behaviors (e.g. times when device automatically unlocks). Only recurring type schedules are allowed for the DeviceSchedules array. A recurring schedule is used when a device behavior needs a complex set of rules to apply it to specific time ranges and/or frequencies. Each recurring schedule starts each occurence at the same time (based on the specified start time) and ends the occurence after a specified duration. There are 4 different types of recurring schedule that allow a user to control the frequency and pattern of each occurence. Note: Recurring Schedules do not support exception rules within the schedule definition. Daily Recurring Schedules A daily recurring schedule applies the occurence continuously every day until the schedule expires (if an until dateTime was given), but it differs from an Always Active or Temporary schedule in that the duration can't have a full day duration. This sort of schedule might be used if the device behavior was to be applied during consistent business hours every day of the week (e.g. 6am to 10pm, 7 days a week) Example Daily Recurring Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 32400, "rrule": { "frequency": "DAILY", "until": "2030-01-01T00:00:00" } } } Daily Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration < 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "DAILY" recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Weekly Recurring Schedules A weekly recurring schedule applies the occurence on the specified days of week for each week until the schedule expires (if an until dateTime was given). This sort of schedule might be used if the device behavior was to be applied during consistent business hours but only on specific days of the week (e.g. 8am to 5pm, Monday through Friday). Example Weekly Recurring Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "WEEKLY", "byWeekDay": [ { "day": "MO" }, { "day": "TU" }, { "day": "WE" }, { "day": "TH" }, { "day": "FR" } ], "until": "2030-01-01T00:00:00" } } } Weekly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "WEEKLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Monthly Recurring Schedules A monthly recurring schedule applies the occurence on the specified monthDay(s) or specified week of the month for every month until the schedule expires (if an until dateTime was given). This sort of schedule might be used if the device was to be applied consistently on particular days of the month (e.g. 1st and 15th of each month), a specific week of the month (e.g. the 2nd week of each month), and/or specific weekday occurences of the month (e.g. the last occurring Friday of each month). Note: Monthly schedules can recur by weekDay patterns or by monthDay patterns, but they can't have both, see example schema shapes for details. Example Monthly Recurring Schedules Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "MONTHLY", "byWeekDay": [ { "day": "FR", "nth": -1 } ], "until": "2030-01-01T00:00:00" } } }, { "id": "UniquePacSystemScheduleIdentifier2", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "MONTHLY", "byMonthDay": [ { "day": 1 } ], "until": "2030-01-01T00:00:00" } } } Monthly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule objectArray! true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "MONTHLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.byWeekDay.nth Limits recurrence of the particular weekday to only the single instance that occurs within the nth week of the month. int! true Where nth > 0, week count is from start of month (nth = 1 means first week of month), where nth < 0, week count is from end of month (nth = -1 means last week of the month). Note: All nth values must be the same for a single schedule. recurrenceRule.rrule.byMonthDay Array of objects that define which days of the month the schedule should be active. objectArray! true recurrenceRule.rrule.byMonthDay.day Calendar day of the month that the schedule should be active. int! true 1 to 31 recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Yearly Recurring Schedules A yearly recurring schedule gives the control of a month recurring schedule, but it allows the occurences to occur only in specified months of the year. This sort of schedule might be used to schedule specific occurences that occur less frequently than monthly (e.g. December 25th). Note: Yearly schedules can recur by weekDay patterns or by monthDay patterns, but they can't have both, below details the difference. Example Yearly Recurring Schedules Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "YEARLY", "byWeekDay": [ { "day": "TH", "nth": -1 }, { "day": "FR", "nth": -1 } ], "byMonth": [ { "month": "NOVEMBER" } ], "until": "2030-01-01T00:00:00" } } }, { "id": "UniquePacSystemScheduleIdentifier2", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "YEARLY", "byMonthDay": [ { "day": 24 }, { "day": 25 } ], "byMonth": [ { "month": "DECEMBER" } ], "until": "2030-01-01T00:00:00" } } } Yearly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "YEARLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.byWeekDay.nth Limits recurrence of the particular weekday to only the single instance that occurs within the nth week of the month. int! true Where nth > 0, week count is from start of month (nth = 1 means first week of month), where nth < 0, week count is from end of month (nth = -1 means last week of the month). Note: All nth values must be the same for a single schedule. recurrenceRule.rrule.byMonthDay Array of objects that define which days of the month the schedule should be active. objectArray! true recurrenceRule.rrule.byMonthDay.day Calendar day of the month that the schedule should be active. int! true 1 to 31 recurrenceRule.rrule.byMonth Array of objects that define which months the schedule should be active. objectArray! true recurrenceRule.rrule.byMonth.month The name of the month that the schedule should be active enum string! true "JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE", "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER" recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value startStateEnum Values Title Description Value Description “SECURED” Device is secured against unauthorized entrance “PASSAGE” Device is unlocked and allows public entrance. “FIRST_PERSON_IN” Device remains secured against unauthorized entrance. Upon the first valid credential being presented, device will unlock and remain in passage state for remaining duration of the schedule occurance. endStateEnum Values Title Description Value Description “SECURED” Device is secured against unauthorized entrance “PASSAGE” Device is unlocked and allows public entrance. "NO_ACTION” Device remains in secured/passage state that it is currently in and does not change states due to end of schedule occurence.
  • [DeviceTimeV1](https://developers.yonomi.cloud/devicemanagement/traits/devicetimev1.md): Notification informs SW Maker when either deviceTime has been updated. Trait Type: Standard Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. infoDeviceTimeUpdated Informs if there was event indicating that changed/reset the device clock. Details Fields Title Description Title Field Name Description Data Type deviceTimeUtc Reported UTC dateTime at device ISO8601 UTC dateTime format string deviceTimeLocal Reported Local dateTime at device ISO8601 Non-UTC dateTime format string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDeviceTimeUpdated", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "DeviceTimeV1", "message": "An update occurred to device time (UTC or Local)", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "deviceTimeUtc": "2024-12-20T14:49:39.663Z", "deviceTimeLocal": "2024-12-20T07:49:39.663" } } ] }
  • [DoorPositionEventSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/doorpositioneventsettingsv1.md): Information regarding the door position event settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows DoorPositionEventSettingsV1SetDoorEventsSettings action Modify writable door position event settings states. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. DoorPositionEventSettingsV1SetDoorEventsSettingsArgs! false DoorPositionEventSettingsV1SetDoorEventsSettingsArgs Fields Title Description Title Description Field Name Description Data Type Nullable doorOpenedEventSettings The desired device value for doorOpenedEventSettings. doorOpenedEventSettingsEnum true doorClosedEventSettings The desired device value for doorClosedEventSettings. doorClosedEventSettingsEnum true doorProppedEventSettings The desired device value for doorProppedEventSettings. doorProppedEventSettingsEnum true doorProppedAlarmThreshold The desired device value for doorProppedAlarmThreshold. Int true doorOpenedEventSettingsEnum Values Title Description Enumerated Value Description ENABLED doorOpenedEventSettings is enabled. DISABLED doorOpenedEventSettings is disabled. doorClosedEventSettingsEnum Values Title Description Enumerated Value Description ENABLED doorClosedEventSettings is enabled. DISABLED doorClosedEventSettings is disabled. doorProppedEventSettingsEnum Values Title Description Enumerated Value Description ENABLED doorProppedEventSettings is enabled. DISABLED doorProppedEventSettings is disabled. GQL Examples Request Example Plain text mutation DoorPositionEventSettingsV1SetDoorEventSettings { DoorPositionEventSettingsV1SetDoorEventSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { doorOpenedEventSettings: ENABLED doorClosedEventSettings: ENABLED doorProppedEventSettings: ENABLED proppedDoorAlertThreshold: 60 } ) { deviceId actionId traitName } } Response Example Plain text { "data": { "DoorPositionEventSettingsV1SetDoorEventSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions doorOpenedEventSettings state Setting to determine if notification should publish when door is opened. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED doorOpenedEventSettings is enabled. DISABLED doorOpenedEventSettings is disabled. UNSUPPORTED Device has not yet reported a value for this field. doorClosedEventSettings state Setting to determine if notification should publish when door is closed. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED doorClosedEventSettings is enabled. DISABLED doorClosedEventSettings is disabled. UNSUPPORTED Device has not yet reported a value for this field. doorProppedEventSettings state Setting to determine if notification should publish when door is propped. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED doorProppedEventSettings is enabled. DISABLED doorProppedEventSettings is disabled. UNSUPPORTED Device has not yet reported a value for this field. doorProppedAlarmThreshold state Setting for amount of time in seconds that door may remain open until it is considered to be propped. Data Type: Int Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on DoorPositionEventSettingsV1DeviceTrait { name state { doorOpenedEventSettings { reported { value } } doorClosedEventSettings { reported { value } } doorProppedEventSettings { reported { value } } proppedDoorAlertThreshold { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "DoorPositionEventSettingsV1", "state": { "doorOpenedEventSettings": { "reported": { "value": "DISABLED" } }, "doorClosedEventSettings": { "reported": { "value": "DISABLED" } }, "doorProppedEventSettings": { "reported": { "value": "DISABLED" } }, "proppedDoorAlertThreshold": { "reported": { "value": 20 } } } } ] } } }
  • [DoorPositionV1](https://developers.yonomi.cloud/devicemanagement/traits/doorpositionv1.md): Information regarding the door position and notification of events recorded by the sensor. Trait Type: Standard Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions doorPosition state Indicates the current value reported by door position sensor. Data Type: enum Valid Values Title Description Enumerated Value Description OPEN doorPosition is open. CLOSED doorPosition is closed. UNSUPPORTED Device has not yet reported a value for this field. Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on DoorPositionV1DeviceTrait { name state { doorPosition { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "DoorPositionV1", "state": { "doorPosition": { "reported": { "value": "OPEN" } } } } ] } } } Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. infoDoorOpened Informs if there was an event from the device indicating that the door was opened. Details Fields Not applicable for this event. Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDoorOpened", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "DoorPositionV1", "message": "Door is opened", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } infoDoorClosed Informs if there was an event from the device indicating that the door was closed. Details Fields Not applicable for this event. Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDoorClosed", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "DoorPositionV1", "message": "Door is closed", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } infoDoorPropped Informs if there was an event from the device if the door position sensor senses that the door was propped. Details Fields Not applicable for this event. Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDoorPropped", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "DoorPositionV1", "message": "Door is propped", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] }
  • [ExtendedAutoRelockDelaySettingsV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/autorelockdelaysettingsv1-trait-copy-1.md): Information regarding device that supports auto relock delay settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows ExtendedAutoRelockDelaySettingsV1SetExtendedAutoRelockDelay Action Modifies the auto relock delay value. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields ExtendedAutoRelockDelaySettingsV1SetExtendedAutoRelockDelayArgs! false ExtendedAutoRelockDelaySettingsV1SetExtendedAutoRelockDelayArgs Fields Title Description Title Description Field Name Description Data Type Nullable extendedAutoRelockDelay The amount of time in seconds that the lock waits before relocking after an extended unlock event int! false GQL Examples Request Example Plain text mutation ExtendedAutoRelockDelaySettingsV1SetExtendedAutoRelockDelay { ExtendedAutoRelockDelaySettingsV1SetExtendedAutoRelockDelay( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { extendedAutoRelockDelay: 90 } ){ deviceId actionId } } Response Example Plain text { "data": { "ExtendedAutoRelockDelaySettingsV1SetExtendedAutoRelockDelay": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions extendedAutoRelockDelay State The amount of time in seconds that the lock waits before relocking after an extended unlock event Data Type: Integer Device State Query GQL Examples Note: See Overview: Device Reported State for more information on reported state flows. Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on ExtendedAutoRelockDelaySettingsV1DeviceTrait { name state { extendedAutoRelockDelay { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "ExtendedAutoRelockDelaySettingsV1", "state": { "extendedAutoRelockDelay": { "reported": { "value": 90 } } } } ] } } }
  • [FirmwareV1](https://developers.yonomi.cloud/devicemanagement/traits/firmwarev1.md): Information regarding the device firmware and actions to update/modify the value. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows FirmwareV1ScheduleLatestFirmwareUpdate action Schedule when to download and install the latest production ready firmware version available for the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields FirmwareV1ScheduleLatestFirmwareUpdateArgs! false FirmwareV1ScheduleLatestFirmwareUpdateArgs Fields Title Description Title Description Field Name Description Data Type Nullable scheduledAt UTC dateTime when the device should initiate installation of the latest firmware. string! Note: String must be ISO8601 UTC format date time false downloadAt The desired value for the advertising rate of the BLE credential reader. If provided, value must be before the scheduledAt value. If omitted, process will download and immediately install at the scheduled time. string Note: String must be ISO8601 UTC format date time true GQL Examples Request Example GraphQL mutation FirmwareV1ScheduleLatestFirmwareUpdate { FirmwareV1ScheduleLatestFirmwareUpdate( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { scheduledAt: “2024-12-20T14:49:55.000Z”, downloadAt: "2024-12-20T14:00.000Z" } ){ deviceId actionId } } Response Example Plain text { "data": { "FirmwareV1ScheduleLatestFirmwareUpdate": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } FirmwareV1InstallLatestFirmwareUpdate action Trigger immediate download and install of the latest production ready firmware version available for the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false GQL Examples Request Example GraphQL mutation FirmwareV1InstallLatestFirmwareUpdate { FirmwareV1InstallLatestFirmwareUpdate( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" ){ deviceId actionId } } Response Example Plain text { "data": { "FirmwareV1InstallLatestFirmwareUpdate": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions firmwareVersion State Indicates the firmware installed on the device. Data Type: string firmwareDownloadScheduledAt State Indicates the time the latest firmware update is scheduled to be installed at. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) firmwareInstallScheduledAt State Indicates the time the latest firmware update is scheduled to be installed at. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) firmwareInstalledAt State Indicates the UTC DateTime the latest firmware was installed at. Data Type: string (Note: String contents will contain a ISO8601 UTC format date time value) Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { name ... on FirmwareV1DeviceTrait { name state { firmwareVersion { reported { value } } firmwareDownloadScheduledAt { reported { value } } firmwareInstallScheduledAt { reported { value } } firmwareInstalledAt { reported { value } } } } } } } Response Example JSON { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "FirmwareV1", "state": { "firmwareVersion": { "reported": { "value": "90.3.5806" } }, "firmwareDownloadScheduledAt": { "reported": { "value": "2024-12-20T14:00.000Z" } }, "firmwareInstallScheduledAt": { "reported": { "value": "2024-12-20T14:49:55.000Z" } }, "firmwareInstalledAt": { "reported": { "value": "2024-12-20T14:49:55.859Z" } } } } ] } } }
  • [ForcedEntryV1](https://developers.yonomi.cloud/devicemanagement/traits/forcedentryv1.md): Forced entry notification from the device. Trait Type: Standard Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. warningForcedEntryDetected Informs if there was an event from the device when a forced entry is detected. Details Fields Does not apply to this event. Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningForcedEntryDetected", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "ForcedEntryV1", "message": "Forced entry detected", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] }
  • [HolidaySchedulesV1](https://developers.yonomi.cloud/devicemanagement/traits/deviceschedulesv1-copy-1.md): Manage holiday lock/unlock schedules data on device. Trait Type: Bulk Data HolidaySchedules data files As this is a bulk data trait, interactions will require passing data in separate files rather than as payloads in the API requests and events. The data files passed to Yonomi Platform for writing data to the device as well as files passed from Yonomi Platform for reporting state of the device will have the following schema. Note: If a holiday schedule is applied at the same time as a device schedule, the behavior of the holiday schedule takes precedent. Plain text { "holidaySchedules": [] } The “holidaySchedules” array may be left empty if the device is not to have any holidaySchedules. Otherwise, this array should be populated with holidaySchedule objects (See the “ Defining HolidaySchedules data objects ” page). When writing data to the device, data files must include ALL holidaySchedule objects desired to be on the device (rather than just the objects to be updated) as sending new data will overwrite existing databases on the device. Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows HolidaySchedulesV1RequestHolidaySchedulesURL action Requests uploadUrl to allow writing a new holidaySchedules data to a device. Upon getting the URL, users must make a PUT request to that URL with data structure as defined in the "HolidaySchedules data files" section on this page. Uploading the data will result in Asynchronous processing of the data file and uploading to the device. Any error or success responses on the action after uploading the data file will be surfaced as DEVICE_ACTION_UPDATED events. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false GQL Examples Request Example Plain text mutation HolidaySchedulesV1DeviceTrait { HolidaySchedulesV1DeviceTrait( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" ) { deviceId actionId uploadUrl uploadUrlExpiresAt } } Response Example Plain text { "data": { "HolidaySchedulesV1DeviceTrait": { "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "uploadUrl": "https://fakefileurl.com", "uploadUrlExpiresAt": "2025-04-25T15:46:18.181Z" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions downloadUrl state Url where data file containing all device lock/unlock schedules data reported from device. File includes entire dataset, not just the changes since last report. See separate documentation for file requirements Data Type: URL downloadUrlExpiresAt state T imestamp when the downloadUrl is set to expire. Data Type: string (Value formatted as an ISO 8601 UTC dateTime) Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on HolidaySchedulesV1DeviceTrait{ name state { downloadUrl { reported { value } } downloadUrlExpiresAt { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "HolidaySchedulesV1", "state": { "downloadUrl": { "reported": { "value": "https://fakefileurl.com" } }, "downloadUrlExpiresAt": { "reported": { "value": "2025-04-25T15:56:28.513Z" } } } } ] } } }
    • [Defining HolidaySchedules data objects](https://developers.yonomi.cloud/devicemanagement/traits/deviceschedulesv1-copy-1/defining-deviceschedules-data-objects-copy.md): HolidaySchedules Objects HolidaySchedule objects are data elements that nest into the “holidaySchedules” array of the HolidaySchedulesV1 data file. These objects define individual schedules for holidays that overrule scheduled HolidaySchedules. Only recurring type schedules are allowed for the HolidaySchedules array. A recurring schedule is used when a device behavior needs a complex set of rules to apply it to specific time ranges and/or frequencies. Each recurring schedule starts each occurence at the same time (based on the specified start time) and ends the occurence after a specified duration. There are 4 different types of recurring schedule that allow a user to control the frequency and pattern of each occurence. Note: Recurring Schedules do not support exception rules within the schedule definition. Daily Recurring Schedules A daily recurring schedule applies the occurence continuously every day until the schedule expires (if an until dateTime was given), but it differs from an Always Active or Temporary schedule in that the duration can't have a full day duration. This sort of schedule might be used if the device behavior was to be applied during consistent business hours every day of the week (e.g. 6am to 10pm, 7 days a week) Example Daily Recurring Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 32400, "rrule": { "frequency": "DAILY", "until": "2030-01-01T00:00:00" } } } Daily Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration < 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "DAILY" recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Weekly Recurring Schedules A weekly recurring schedule applies the occurence on the specified days of week for each week until the schedule expires (if an until dateTime was given). This sort of schedule might be used if the device behavior was to be applied during consistent business hours but only on specific days of the week (e.g. 8am to 5pm, Monday through Friday). Example Weekly Recurring Schedule Object Schema Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "WEEKLY", "byWeekDay": [ { "day": "MO" }, { "day": "TU" }, { "day": "WE" }, { "day": "TH" }, { "day": "FR" } ], "until": "2030-01-01T00:00:00" } } } Weekly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "WEEKLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Monthly Recurring Schedules A monthly recurring schedule applies the occurence on the specified monthDay(s) or specified week of the month for every month until the schedule expires (if an until dateTime was given). This sort of schedule might be used if the device was to be applied consistently on particular days of the month (e.g. 1st and 15th of each month), a specific week of the month (e.g. the 2nd week of each month), and/or specific weekday occurences of the month (e.g. the last occurring Friday of each month). Note: Monthly schedules can recur by weekDay patterns or by monthDay patterns, but they can't have both, see example schema shapes for details. Example Monthly Recurring Schedules Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "MONTHLY", "byWeekDay": [ { "day": "FR", "nth": -1 } ], "until": "2030-01-01T00:00:00" } } }, { "id": "UniquePacSystemScheduleIdentifier2", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "MONTHLY", "byMonthDay": [ { "day": 1 } ], "until": "2030-01-01T00:00:00" } } } Monthly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object! true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule objectArray! true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "MONTHLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.byWeekDay.nth Limits recurrence of the particular weekday to only the single instance that occurs within the nth week of the month. int! true Where nth > 0, week count is from start of month (nth = 1 means first week of month), where nth < 0, week count is from end of month (nth = -1 means last week of the month). Note: All nth values must be the same for a single schedule. recurrenceRule.rrule.byMonthDay Array of objects that define which days of the month the schedule should be active. objectArray! true recurrenceRule.rrule.byMonthDay.day Calendar day of the month that the schedule should be active. int! true 1 to 31 recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value Yearly Recurring Schedules A yearly recurring schedule gives the control of a month recurring schedule, but it allows the occurences to occur only in specified months of the year. This sort of schedule might be used to schedule specific occurences that occur less frequently than monthly (e.g. December 25th). Note: Yearly schedules can recur by weekDay patterns or by monthDay patterns, but they can't have both, below details the difference. Example Yearly Recurring Schedules Plain text { "id": "UniquePacSystemScheduleIdentifier1", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "YEARLY", "byWeekDay": [ { "day": "TH", "nth": -1 }, { "day": "FR", "nth": -1 } ], "byMonth": [ { "month": "NOVEMBER" } ], "until": "2030-01-01T00:00:00" } } }, { "id": "UniquePacSystemScheduleIdentifier2", "scheduleType": "RECURRING", "dtStart": "2024-04-01T15:00:00", "recurrenceRule": { "duration": 86399, "rrule": { "frequency": "YEARLY", "byMonthDay": [ { "day": 24 }, { "day": 25 } ], "byMonth": [ { "month": "DECEMBER" } ], "until": "2030-01-01T00:00:00" } } } Yearly Recurring Schedule Fields Title Description Title Description Title Field Name Description Data Type Required Validation Info id PAC System unique identifier allowing cross-system correlation string! true Can be any unique, non-empty string startState Lock state to be applied when schedule starts enum string! true See startStateEnum table at bottom of this page for values. endState Lock state to be applied when schedule ends enum string! true See endStateEnum table at bottom of this page for values. scheduleType Defines type of schedule which changes the validation requirements for additional schedule data fields enum string! true "RECURRING" dtStart Device local DateTime when schedule should go into effect. string! true "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value recurrenceRule Object field nesting additional fields required for a recurring schedule object true recurrenceRule.duration The duration in seconds that each occurrence should be active from the time of day matching that given in “dtStart”. int! true 1 <= duration <= 86399 recurrenceRule.rrule Object field nesting r-rule fields required for a recurring schedule object true recurrenceRule.rrule.frequency The frequency by which the r-rule pattern repeats enum string! true "YEARLY" recurrenceRule.rrule.byWeekDay Array of objects that define which days of the week the schedule should be active. objectArray! true recurrenceRule.rrule.byWeekDay.day The day of week that a schedule occurrence should be active. enum string! true “SU”, “MO”, “TU”, “WE”, “TH”, “FR”, “SA” recurrenceRule.rrule.byWeekDay.nth Limits recurrence of the particular weekday to only the single instance that occurs within the nth week of the month. int! true Where nth > 0, week count is from start of month (nth = 1 means first week of month), where nth < 0, week count is from end of month (nth = -1 means last week of the month). Note: All nth values must be the same for a single schedule. recurrenceRule.rrule.byMonthDay Array of objects that define which days of the month the schedule should be active. objectArray! true recurrenceRule.rrule.byMonthDay.day Calendar day of the month that the schedule should be active. int! true 1 to 31 recurrenceRule.rrule.byMonth Array of objects that define which months the schedule should be active. objectArray! true recurrenceRule.rrule.byMonth.month The name of the month that the schedule should be active enum string! true "JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE", "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER" recurrenceRule.rrule.until Device local DateTime when schedule expires. string! false "YYYY-MM-DDThh:mm:ss.sss" local format dateTime value startStateEnum Values Title Description Value Description “HOLIDAY_SECURED” Device is secured against unauthorized entrance. HolidaySchedule state trump states applied by device schedules at the same time. “HOLIDAY_PASSAGE” Device is unlocked and allows public entrance. HolidaySchedule state trump states applied by device schedules at the same time. “HOLIDAY_PASSAGE_WITH_FIRST_PERSON_IN” Device remains secured against unauthorized entrance. Upon the first valid credential being presented, device will unlock and remain in passage state for remaining duration of the schedule occurance. HolidaySchedule state trump states applied by device schedules at the same time. endStateEnum Values Title Description Value Description “SECURED” Device is secured against unauthorized entrance “PASSAGE” Device is unlocked and allows public entrance. "NO_ACTION” Device remains in secured/passage state that it is currently in and does not change states due to end of schedule occurence.
  • [LockEventSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/lockeventsettingsv1.md): Information regarding the device beeper settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows LockEventSettingsV1SetLockSettings action Modify writable lock settings states. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. LockEventSettingsV1SetLockSettingsArgs! false LockEventSettingsV1SetLockSettingsArgs Fields Title Description Title Description Field Name Description Data Type Nullable unauthorizedUserEventEnabled Desired value for the unauthorizedUserEventEnabled setting. unauthorizedUserEventEnabledEnum true rexEventEnabled Desired value for the rexEventEnabled setting. rexEventEnabledEnum true interiorLockBlinkingEnabled Desired value for the interiorLockBlinkingEnabled setting. interiorLockBlinkingEnabledEnum true powerFailLockMode Desired value for the powerFailLockMode setting. powerFailLockModeEnum true blockConstructionModeEnabled Desired value for the blockConstructionModeEnabled setting. blockConstructionModeEnabledEnum true doubleTapEnabled Desired value for the doubleTapEnabled setting. doubleTapEnabledEnum true keyOverrideEventEnabled Desired value for the keyOverrideEventEnabled setting. keyOverrideEventEnabledEnum true bruteForceMitigationSetting Desired value for the bruteForceMitigationSetting setting. bruteForceMitigationSettingEnum true unauthorizedUserEventEnabledEnum Values Title Description Enumerated Value Description ENABLED unauthorizedUserEventEnabled will publish notification. DISABLED unauthorizedUserEventEnabled will not publish notification. rexEventEnabledEnum Values Title Description Enumerated Value Description ENABLED rexEventEnabled will publish notification. DISABLED rexEventEnabled will not publish notification. interiorLockBlinkingEnabledEnum Values Title Description Enumerated Value Description NORMALBLINKENABLED Interior LED blinks normally when device is secured. RAPIDBLINKENABLED Interior LED blinks rapidly when device is secured. DISABLED Interior LED does not blink when device secured. powerFailLockModeEnum Values Title Description Enumerated Value Description AS_IS Device will remain in whichever state it was in when power was lost. FAILSECURE Device will always revert to secured state on loss of power. FAILPASSAGE Device will always revert to passage state on loss of power. blockConstructionModeEnabledEnum Values Title Description Enumerated Value Description ENABLED Device blockConstruction mode is enabled. DISABLED Device blockConstruction mode is disabled. doubleTapEnabled Values Title Description Enumerated Value Description ENABLED Device doubleTapEnabled mode is enabled. DISABLED Device doubleTapEnabled mode is disabled. keyOverrideEventEnabledEnum Values Title Description Enumerated Value Description ENABLED keyOverrideEventEnabled will publish notification. DISABLED keyOverrideEventEnabled will not publish notification. bruteForceMitigationSettingEnum Values Title Description Enumerated Value Description ENABLED Device will block credential authentications under a brute force attack scenario. DISABLED Device will not block credential authentications under a brute force attack scenario. GQL Examples Request Example Plain text mutation LockEventSettingsV1SetLockSettings { LockEventSettingsV1SetLockSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { unauthorizedUserEventEnabled: ENABLED rexEventEnabled: ENABLED interiorLockBlinkingEnabled: NORMALBLINKENABLED powerFailLockMode: AS_IS blockConstructionModeEnabled: ENABLED doubleTapEnabled: ENABLED keyOverrideEventEnabled: ENABLED bruteForceMitigationSetting: ENABLED } ) { deviceId actionId traitName } } Response Example Plain text { "data": { "LockEventSettingsV1SetLockSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions unauthorizedUserEventEnabled state Setting to determine if notification should publish when unauthorized user attempts to gain entry. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED unauthorizedUserEventEnabled will publish notification. DISABLED unauthorizedUserEventEnabled will not publish notification. UNSUPPORTED Device has not yet reported a value for this field. rexEventEnabled state Setting to determine if notification should publish when request to exit switch is triggered. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED rexEventEnabled will publish notification. DISABLED rexEventEnabled will not publish notification. UNSUPPORTED Device has not yet reported a value for this field. interiorLockBlinkingEnabled state Setting that determines how the device LED blinks when device is secured. Data Type: Enum Valid Values Title Description Enumerated Value Description NORMALBLINKENABLED Interior LED blinks normally when device is secured. RAPIDBLINKENABLED Interior LED blinks rapidly when device is secured. DISABLED Interior LED does not blink when device secured. UNSUPPORTED Device has not yet reported a value for this field. powerFailLockMode state Setting that determines which state lock will default to upon loss of power. Data Type: Enum Valid Values Title Description Enumerated Value Description AS_IS Device will remain in whichever state it was in when power was lost. FAILSECURE Device will always revert to secured state on loss of power. FAILPASSAGE Device will always revert to passage state on loss of power. UNSUPPORTED Device has not yet reported a value for this field. blockConstructionModeEnabled state Setting that determines if device blockConstruction mode is enabled to prevent device from being put into construction mode. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED Device blockConstruction mode is enabled. DISABLED Device blockConstruction mode is disabled. UNSUPPORTED Device has not yet reported a value for this field. doubleTapEnabled state Setting that determines if device doubleTap mode is enabled to allow normal credential to toggle device secured/passage state when double tapped to reader. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED Device doubleTapEnabled mode is enabled. DISABLED Device doubleTapEnabled mode is disabled. UNSUPPORTED Device has not yet reported a value for this field. keyOverrideEventEnabled state Setting to determine if notification should publish when entry was gained via key override. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED keyOverrideEventEnabled will publish notification. DISABLED keyOverrideEventEnabled will not publish notification. UNSUPPORTED Device has not yet reported a value for this field. bruteForceMitigationSetting state Setting to determine if device should block credential authentications under a brute force attack scenario. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED Device will block credential authentications under a brute force attack scenario. DISABLED Device will not block credential authentications under a brute force attack scenario. UNSUPPORTED Device has not yet reported a value for this field. Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on LockEventSettingsV1DeviceTrait { name state { unauthorizedUserEventEnabled { reported { value } } rexEventEnabled { reported { value } } interiorLockBlinkingEnabled { reported { value } } powerFailLockMode { reported { value } } blockConstructionModeEnabled { reported { value } } doubleTapEnabled { reported { value } } keyOverrideEventEnabled { reported { value } } bruteForceMitigationSetting { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "LockEventSettingsV1", "state": { "unauthorizedUserEventEnabled": { "reported": { "value": "DISABLED" } }, "rexEventEnabled": { "reported": { "value": "UNSUPPORTED" } }, "interiorLockBlinkingEnabled": { "reported": { "value": "RAPIDBLINKENABLED" } }, "powerFailLockMode": { "reported": { "value": "FAILSECURE" } }, "blockConstructionModeEnabled": { "reported": { "value": "DISABLED" } }, "doubleTapEnabled": { "reported": { "value": "DISABLED" } }, "keyOverrideEventEnabled": { "reported": { "value": "ENABLED" } }, "bruteForceMitigationSetting": { "reported": { "value": "DISABLED" } } } } ] } } }
  • [LockV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/autorelockdelaysettingsv1-copy-1.md): Information regarding devices that have latch and/or deadbolt, actions to modify the device, and notification when an event occurred related to the lock or deadbolt status. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows LockV1SetLockMode action Modifies the lockMode state. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields LockV1LockModeArgs! false LockV1LockModeArgs Fields Title Description Title Description Field Name Description Data Type Nullable lockMode the function mode setting to be applied to the device lockModeActionEnum! false lockModeActionEnum Values Title Description Enumerated String Description OFFICE Device is normally secure. Inside trim always allows free egress. Interior push button may be used to select a passage or secured status. Meets need for lockdown function for safety and security. NOTE: Valid toggle credentials on the exterior may also be used to change status. PRIVACY Device is normally secure. Inside trim always allows free egress. Interior push button or thumbturn may be used to select a privacy status. The interior push button will disable normal electronic access from the exterior. Opening the door, pressing the interior push button a second time, or turning the thumbturn deactivates the privacy status. STOREROOM Device is normally secure. Inside trim always allows free egress. Valid toggle credentials on the exterior may be used to change to a passage or secured status. APARTMENT Device is normally secure. Inside trim always allows free egress. Inside push button or thumbturn may be used to select a passage or secured status. Opening the door, pressing the inside push button, or turning the thumbturn causes the device to toggle unsecured. While toggled unsecured, the device can only be secured while the door is closed by pressing the interior push button, turning the thumbturn, or using a normal credential on the exterior. Normal electronic access from the exterior is always allowed. Request Example Plain text mutation LockV1SetLockMode { LockV1SetLockMode( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { lockMode: OFFICE } ){ deviceId actionId } } Response Example Plain text { "data": { "LockV1SetLockMode": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } LockV1ExecuteLockingAction Commands lock to perform the appropriate lock state change as if a user presented a credential matching the lockingAction input. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields LockV1ExecuteLockActionArgs! false LockV1ExecuteLockActionArgs Fields Title Description Title Description Field Name Description Data Type Nullable lockingAction the desired type of action to be performed on current lock state. lockingActionEnums! false lockingActionEnums Values Title Description Enumerated String Description NORMAL Generally, when device is in SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on autoRelockDelay setting (see AutoRelockDelaySettingsV1 Trait). NORMAL_EXTENDED Generally, when device is in SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on extendedAutoRelockDelay setting (see ExtendedAutoRelockDelaySettingsV1 Trait). PASS_THRU Generally, when device is in SECURED or FROZEN_SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on autoRelockDelay setting (see AutoRelockDelaySettingsV1 Trait). PASS_THRU_EXTENDED Generally, when device is in SECURED or FROZEN_SECURED state, device is put into MOMENTARILY_UNLOCK state and automatically relocks after amount of time based on autoRelockDelay setting (see ExtendedAutoRelockDelaySettingsV1 Trait). TOGGLE Generally, when device is in a SECURED or PASSAGE state, device toggles between SECURE and PASSAGE states. LOCK_DOWN Generally, no matter what starting state the device is in, device will be put into FROZEN_SECURED state. FREEZE Generally, toggles device between a FROZEN state and the corresponding normal state (e.g. FROZEN_SECURED and SECURED or FROZEN_PASSAGE and PASSAGE) Request Example Plain text mutation LockV1ExecuteLockingAction { LockV1ExecuteLockingAction( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { lockingAction: NORMAL } ){ deviceId actionId } } Response Example Plain text { "data": { "LockV1ExecuteLockingAction": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions lockMode State The currently set lock function (e.g. Office). Data Type: Enum Valid Values Title Description Enumerated String Description UNSUPPORTED Device does not report data for this state. OFFICE Device is normally secure. Inside trim always allows free egress. Interior push button may be used to select a passage or secured status. Meets need for lockdown function for safety and security. NOTE: Valid toggle credentials on the exterior may also be used to change status. PRIVACY Device is normally secure. Inside trim always allows free egress. Interior push button or thumbturn may be used to select a privacy status. The interior push button will disable normal electronic access from the exterior. Opening the door, pressing the interior push button a second time, or turning the thumbturn deactivates the privacy status. STOREROOM Device is normally secure. Inside trim always allows free egress. Valid toggle credentials on the exterior may be used to change to a passage or secured status. APARTMENT Device is normally secure. Inside trim always allows free egress. Inside push button or thumbturn may be used to select a passage or secured status. Opening the door, pressing the inside push button, or turning the thumbturn causes the device to toggle unsecured. While toggled unsecured, the device can only be secured while the door is closed by pressing the interior push button, turning the thumbturn, or using a normal credential on the exterior. Normal electronic access from the exterior is always allowed. lockState State The currently security state of the device (e.g. Secured). See published state table documentation for information on how device should behave based on the selected mode, current state, and event conditions that occur. Data Type: Enum Valid Values Title Description Enumerated String Description UNKNOWN Device reports that lock state is unknown. MOMENTARY_UNLOCK Device reports that lock state is momentarily unlocked. SECURED Device reports that lock state is secured. PASSAGE Device reports that lock state is passage. FROZEN_SECURED Device reports that lock state is frozen secured. FROZEN_PASSAGE Device reports that lock state is frozen passage. FROZEN_NORMAL Device reports that lock state is frozen normal. HOLIDAY_RESTRICTED Device reports that lock state is holiday restricted. PRIVACY_SECURED Device reports that lock state is privacy secured. UNSUPPORTED Device has not reported lock state, it is not supported by the device's current firmware. deadboltState State The current deadbolt state (e.g. retracted). Data Type: Enum Valid Values Title Description Enumerated String Description UNSUPPORTED Device does not report data for this state. LOCKED Deadbolt is extended UNLOCKED Deadbolt is retracted JAMMED Deadbolt is jammed UNKNOWN Device can't determine deadbolt position ipbState State The current interior push button state (e.g. activated) Data Type: Enum Valid Values Title Description Enumerated String Description UNSUPPORTED Device does not report data for this state. ACTIVATED Internal push button is activated DEACTIVATED Internal push button is de-activated totalMotorCycles State The total number of cycles lock motor has completed over life of device Data Type: Int Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on LockV1DeviceTrait { name state { lockMode { reported { value } } lockState { reported { value } } deadboltState { reported { value } } ipbState { reported { value } } totalMotorCycles { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "LockV1", "state": { "lockMode": { "reported": { "value": "OFFICE" } }, "lockState": { "reported": { "value": "SECURED" } }, "deadboltState": { "reported": { "value": "UNSUPPORTED" } }, "ipbState": { "reported": { "value": "UNSUPPORTED" } }, "totalMotorCycles": { "reported": { "value": 1055 } } } } ] } } } Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. warningUnauthorzedUserEvent Warning that an unauthorized user attempted to gain access. Details Fields Title Description Title Field Name Description Data Type credentialPresented Information on the triggering credential. string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningUnauthorizedUserEvent", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A warningUnauthorizedUserEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "credentialPresented": "AAAAAAAAAAAAAAA1" } } ] } infoUserAccessLockEvent Events related to valid credentials being presented to the lock. Details Fields Title Description Title Field Name Description Data Type cause Information on the event cause string effect Information on the resulting lockState string credentialId Information on the triggering credential. string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoUserAccessLockEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoUserAccessLockEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "cause": "Normal User Access", "effect": "Passage", "credentialId": "AAAAAAAAAAAAAAA1" } } ] } infoDeviceScheduleEvent Events related to device schedule. Details Fields Title Description Title Field Name Description Data Type cause Information on the event cause string effect Information on the resulting lockState string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDeviceScheduleEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoDeviceScheduleEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "cause": "Auto Unlock Event", "effect": "Passage" } } ] } infoHolidayScheduleEvent Events related to holiday schedule. Details Fields Title Description Title Field Name Description Data Type cause Information on the event cause string effect Information on the resulting lockState string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoHolidayScheduleEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoHolidayScheduleEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "cause": "Holiday Passage Time Event", "effect": "Passage" } } ] } infoCloudCommandEvent Events related to cloud command that modifies the lockStatus. Details Fields Title Description Title Field Name Description Data Type cause Information on the event cause string effect Information on the resulting lockState string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoCloudCommandEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoCloudCommandEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "cause": "Remote Normal User Access Command", "effect": "Passage" } } ] } infoDeviceEvent Events related to manual operation of the device. Details Fields Title Description Title Field Name Description Data Type cause Information on the event cause string effect Information on the resulting lockState string Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDeviceEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoDeviceEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "cause": "Internal Push Button Active", "effect": "Privacy On" } } ] } infoKeyOverrideEvent Events related to key override operation. Details Fields Not applicable to this event Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoKeyOverrideEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoKeyOverrideEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } infoRexEvent Events related to request to exit operation. Details Fields Not applicable to this event Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoRexEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoRexEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } infoBlockConstructionModeEvent Events related to blockConstructionMode setting changes. Details Fields Title Description Title Field Name Description Data Type blockConstructionModeState Status of the blockConstructionMode setting ENABLED, DISABLED Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoBlockConstructionModeEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "A infoBlockConstructionModeEvent event occurred at device.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "blockConstructionModeState": "ENABLED" } } ] } warningBruteForceAttackIdentified Warning that lock detected a brute force attack and has initiated mitigations. Details Fields Not applicable to this event Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningBruteForceAttackIdentified", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "Device has detected a brute force attack. Credential authentication has been blocked.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } infoBruteForceAttackResolved Events related to a previously detected brute force attack having stopped and device deactivating mitigations. Details Fields Not applicable to this event Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoBruteForceAttackResolved", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "Device is no longer under brute force attack. Credential authentication has been unblocked.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] } warningMotorFailed Warning that lock motor failed to change lockState as expected. Details Fields Title Description Title Field Name Description Data Type motorFailureType Status of the blockConstructionMode setting FAILED_TO_LOCK, FAILED_TO_UNLOCK Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "warningMotorFailed", "notificationType": "WARNING", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "lockV1", "message": "Device motor state mismatch found during lock/unlock operation.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "motorFailureType": "FAILED_TO_UNLOCK" } } ] }
  • [NoTourV1 Trait](https://developers.yonomi.cloud/devicemanagement/traits/notourv1.md): Information about the device's configuration settings to read Schlage ENGAGE No Tour credentials and the actions to set them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows. NoTourV1SetNoTourState Enables or disables the No Tour capability for enabled devices. Mutation Inputs Input Name Description Data Type Nullable deviceId UUID of the device to which the mutation should apply ID! false noTourState The enabled/disabled state of the device's No Tour capability enum (ENABLED or DISABLED)! false GQL Examples Request Example GraphQL mutation NoTourV1SetNoTourState { NoTourV1SetNoTourState( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", traitActionArgs: { noTourState: "ENABLED" } ) { deviceId actionId } } Response Example Plain text { "data": { "NoTourV1SetNoTourState": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } NoTourV1ConfigNoTour Sets the No Tour configuration settings of the enabled device. Action Pre-Requisites Once the following have been met, the client may submit this action according to the linked action lifecycle flow. Client MUST have a site set up in the Schlage ENGAGE system that supports No Tour. Client MUST obtain the key of the Schlage ENGAGE No Tour site to which the device should be associated. Client MUST generate a HEX string containing the SHA-256 hash of the Schlage ENGAGE siteKey value for input into the mutation. Client MUST encrypt the Schlage ENGAGE siteKey value for input into the mutation according to the encryption requirements laid out below. Client MUST generate a noTourDoorId and correlate it to the deviceId. The ID must be an integer from 0 to 65535 and must be unique to each device correlated to the Schlage ENGAGE siteKey (in YP or ENGAGE systems). Site Key Encryption Requirements Encrypt using the following public key: Plain text -----BEGIN PUBLIC KEY----- MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5A1AVahduKCiCBrOgEhk ksTYf/zgDiv2CTsP8rbp1/8PWzVbA1jC3BHQkDwq/fm3x5ld5eIy52b0dG0sTyL5 G96chBiYtNXnqBlO9ZcNHpPu7Z0GzRKCBHUlV1xqBH8S22m70CMVQVb5mZ8DY1ZO Q5DBbUx5IZVDqzEhku7ISv7u2XeRiGEzlTEdr5FEwMmZWGLAAj+B5bQeqH8Gumfc SVmfTJ7rI5WpbkhAUada2tRGZcPJVOIsJMk27yCv4rBXvGkVl8dyeuypSckkh2Em 2KXZug77BV/u2VjbvnFhNK7CBzwq6C0GwfZtpqgiyPy3HFqPGf4+b3uGbdQkIBEr heAKMRi56R03lFGStA1HCiIQ6guMI1aPOT/pBDYSpGi6wrSOf/+fsfKXrnZHyF/D OvWa88cSu+OsvV560b2hWuqINB1LwbWWomHGYxRq3h+h/4vgMReQnpLb9J+4brY8 VoiqooRwKLYeIfCJNcjCC3pa3shpFL+Ql46TqoKqljH/Jxh/LmHOk4x6ee/pkYNQ 3lLV1JF0G+LAnvskYOtBl0okwLqlyekZqOrw8FNGz63S97D/FfcFlK+1zwUwXNAY nsnL32PP6tYNjcVSkhUj03RjKSiBiEwLRzgTB9ePlqT5n144dwK5y0QRbCIlVXwI YbVGkNKy1OaBJEUVW85Rzc8CAwEAAQ== -----END PUBLIC KEY----- -----BEGIN PUBLIC KEY----- MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5A1AVahduKCiCBrOgEhk ksTYf/zgDiv2CTsP8rbp1/8PWzVbA1jC3BHQkDwq/fm3x5ld5eIy52b0dG0sTyL5 G96chBiYtNXnqBlO9ZcNHpPu7Z0GzRKCBHUlV1xqBH8S22m70CMVQVb5mZ8DY1ZO Q5DBbUx5IZVDqzEhku7ISv7u2XeRiGEzlTEdr5FEwMmZWGLAAj+B5bQeqH8Gumfc SVmfTJ7rI5WpbkhAUada2tRGZcPJVOIsJMk27yCv4rBXvGkVl8dyeuypSckkh2Em 2KXZug77BV/u2VjbvnFhNK7CBzwq6C0GwfZtpqgiyPy3HFqPGf4+b3uGbdQkIBEr heAKMRi56R03lFGStA1HCiIQ6guMI1aPOT/pBDYSpGi6wrSOf/+fsfKXrnZHyF/D OvWa88cSu+OsvV560b2hWuqINB1LwbWWomHGYxRq3h+h/4vgMReQnpLb9J+4brY8 VoiqooRwKLYeIfCJNcjCC3pa3shpFL+Ql46TqoKqljH/Jxh/LmHOk4x6ee/pkYNQ 3lLV1JF0G+LAnvskYOtBl0okwLqlyekZqOrw8FNGz63S97D/FfcFlK+1zwUwXNAY nsnL32PP6tYNjcVSkhUj03RjKSiBiEwLRzgTB9ePlqT5n144dwK5y0QRbCIlVXwI YbVGkNKy1OaBJEUVW85Rzc8CAwEAAQ== -----END PUBLIC KEY----- Algorithm: RSA with 4096‑bit modulus (RSA‑4096). Padding: RSA‑OAEP with SHA‑256 and MGF1 using SHA‑256. Label = None. Input encoding: plaintext UTF‑8 bytes of the exact value to be encrypted (no padding, case changes, or newline). Output format: ciphertext bytes encoded as lowercase hex, no 0x prefix, no spaces/newlines. With RSA‑4096 the ciphertext is 512 bytes → 1024 hex characters. Mutation Inputs Input Name Description Data Type Nullable noTourDoorId 2-byte No Tour identifier associated with the device. Must be unique for all devices within a given siteKey . Int (0 to 65535)! false noTourGroupIds Array of integers used to assign the device to one or more groups of potentially many devices. When included in the request, the input must have an array containing 1 to 16 integers, each integer may be from 0 to 65535. Array true noTourEncryptedSiteKey Object containing the encrypted value and SHA-256 hash of the Schlage ENGAGE siteKey. NoTourEncryptedSiteKeyObject! false NoTourEncryptedSiteKeyObject Fields Field Name Description Data Type Nullable encryptedValue The HEX string output from encrypting the Schlage ENGAGE siteKey (see Action Pre‑Requisites above). HEX String (length = 1024 characters)! false originalDataHash The HEX string output from encoding a SHA-256 hash of the Schlage ENGAGE siteKey . Used to validate that the YP decrypted value matches the original siteKey . HEX String (length = 64 characters)! false GQL Examples Request Example GraphQL mutation NoTourV1ConfigNoTour { NoTourV1ConfigNoTour( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { noTourDoorId: 65535 noTourGroupIds: [0, 65535] noTourEncryptedSiteKey: { encryptedValue: "{{encryptedSiteKey}}" originalDataHash: "{{SHA256Hash}}" } } ) { deviceId actionId traitName } } Response Example Plain text { "data": { "NoTourV1ConfigNoTour": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions noTourDoorId State Unique 2-byte identifier associated with the device. Must be unique for all devices within a given siteKey in both the YP and Schlage ENGAGE systems. DataType : Integer noTourGroupIds State Array of 1 to 16 items. Each item indicates a unique ID that assigns the device to one or more No Tour groups. DataType : Array of Integers noTourActiveSector State Sector of the credential to which No Tour data is written. For Schlage ENGAGE compatibility, this is always Sector 2. DataType : String noTourSha256HashSiteKey State SHA‑256 hash of the decrypted siteKey value written to the device. This can be compared to the SHA‑256 hash of the original siteKey value to confirm that the value written to the device matches the correct siteKey . DataType : String noTourState State The enabled/disabled state of the device's No Tour capability. DataType : String noTourRemainingCredentials State The remaining number of No Tour credentials that may be written to the device. DataType : Integer Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: null) { traits { ... on NoTourV1DeviceTrait { name state { noTourDoorId { reported { value } } noTourGroupIds { reported { value } } noTourActiveSector { reported { value } } noTourSha256HashSiteKey { reported { value } } noTourState { reported { value } } noTourRemainingCredentials { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "NoTourV1", "state": { "noTourDoorId": { "reported": { "value": 65535 } }, "noTourGroupIds": { "reported": { "value": [0, 65535] } }, "noTourActiveSector": { "reported": { "value": "SECTOR_2" } }, "noTourSha256HashSiteKey": { "reported": { "value": "{SHA256HashEncodedHexString}" } }, "noTourState": { "reported": { "value": "ENABLED" } }, "noTourRemainingCredentials": { "reported": { "value": 0 } } } } ] } } }
  • [PowerSourceV1](https://developers.yonomi.cloud/devicemanagement/traits/powersourcev1.md): Information regarding the power source of the device. Trait Type: Standard Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions powerSource state Indicates the power source the device is currently on. Data Type: enum Valid Values Title Description Enumerated Value Description BATTERY Device is battery powered. LINE_POWER Device has hardwired power source. POWER_OVER_ETHERNET Device is powered over ethernet according to 802.3af standard. POWER_OVER_ETHERNET_PLUS Device is powered over ethernet according to 802.3at standard. UNKNOWN Device has no power source specified. UNSUPPORTED Device has not yet reported a value for this field. Device State Query GQL Examples Request Example Plain text query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on PowerSourceV1DeviceTrait { name state { powerSource { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "PowerSourceV1", "state": { "powerSource": { "reported": { "value": "BATTERY" } } } } ] } } } Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. infoJumpStartPowerEvent Information on events related to device being powered on via the usb-c port. Details Fields Not applicable to this event. Event Example Plain text { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoJumpStartPowerEvent", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "PowerSourceV1", "message": "An unknown power source has been plugged into device's USB-C Port.", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": {} } ] }
  • [ReaderSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/readersettingsv1.md): Information regarding the device reader settings and action to modify them. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows ReaderSettingsV1SetReaderSettings action Modify the reader settings on the device. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. ReaderSettingsV1SetReaderSettingsArgs! false ReaderSettingsV1SetReaderSettingsArgs Fields Title Description Title Description Field Name Description Data Type Nullable antiPassbackDuration The desired anti passback duration of the device. Int true noTour The desired noTour setting on the device. noTourEnum true noTourEnum Values Title Description Enumerated Value Description ENABLED noTour setting is enabled. DISABLED noTour setting is disabled. GQL Examples Request Example Plain text mutation ReaderSettingsV1SetReaderSettings { ReaderSettingsV1SetReaderSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { noTour: ENABLED, antiPassbackDuration: 10 } ) { deviceId actionId traitName } } Response Example Plain text { "data": { "ReaderSettingsV1SetReaderSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions antiPassbackDuration state Indicates the anti passback duration of the device. Data Type: Int noTour state Indicates if the device no tour settings is enabled or disabled. Data Type: Enum Valid Values Title Description Enumerated Value Description ENABLED noTour setting is enabled. DISABLED noTour setting is disabled. UNSUPPORTED Device has not yet reported a value for this field. Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on ReaderSettingsV1DeviceTrait { name state { antiPassbackDuration { reported { value } } noTour { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "ReaderSettingsV1", "state": { "antiPassbackDuration": { "reported": { "value": 0 } }, "noTour": { "reported": { "value": "DISABLED" } } } } ] } } }
  • [TimeZoneSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/timezonesettingsv1.md): Information regarding device timezone settings, action to modify the settings and notifications when the device experience a time update. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows TimeZoneSettingsV1SetTimeZoneOffset action Modify writable timezone settings state. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. setTimeZoneOffsetArgs! false Argument Fields Title Description Title Description Field Name Description Data Type Nullable timeZoneOffset The desired timezone offset value the device should use to determine the local time. int true dstSetting Should daylight savings time be enabled or disabled. dstSettingEnum true dstStart The day and time the daylight savings time is expected to start. MDWH Format is based on device expectation where M = Month (1 = Jan, …), D = day of week (0 = Sunday, …), W = Week of month (1=1st, ..5 = last), and H = hour. US default = 3022 string true dstEnd The day and time the daylight savings time is expected to end. MDWH Format is based on device expectation where M = Month (1 = Jan, …), D = day of week (0 = Sunday, …), W = Week of month (1=1st, ..5 = last), and H = hour. US default = B012 string true dstOffset The value representing number of seconds that daylight savings time offsets. int true dstSettingEnum Values Title Description Enumerated Value Description ENABLED Daylight Savings Time is enabled on the device. DISABLED Daylight Savings Time is disabled on the device. GQL Examples Request Example Plain text mutation TimeZoneSettingsV1SetTimeZoneOffset { TimeZoneSettingsV1SetTimeZoneOffset( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { timeZoneOffset: -25200 dstSetting: ENABLED dstStart: "3022" dstEnd: "B012" dstOffset: 3600 } ) { deviceId actionId traitName } } Response Example Plain text { "data": { "TimeZoneSettingsV1SetTimeZoneOffset": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions timeZoneOffset state Indicates the timezone offset value the device is using to determine the local time. Data Type: int dstSetting state Indicates whether daylight savings time is enabled or disabled. Data Type: enum Valid Values Title Description Enumerated Value Description ENABLED Daylight Savings Time is enabled on the device. DISABLED Daylight Savings Time is disabled on the device. UNSUPPORTED Device has not yet reported a value for this field. dstStart state The day and time the daylight savings time is expected to start. MDWH Format is based on device expectation where M = Month (1 = Jan, …), D = day of week (0 = Sunday, …), W = Week of month (1=1st, ..5 = last), and H = hour. US default = 3022 Data Type: string dstEnd state The day and time the daylight savings time is expected to end. MDWH Format is based on device expectation where M = Month (1 = Jan, …), D = day of week (0 = Sunday, …), W = Week of month (1=1st, ..5 = last), and H = hour. US default = B012 Data Type: string dstOffset state The value representing number of seconds that daylight savings time offsets. Data Type: int Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on TimeZoneSettingsV1DeviceTrait { name state { timeZoneOffset { reported { value } } dstSetting { reported { value } } dstStart { reported { value } } dstEnd { reported { value } } dstOffset { reported { value } } } } } } } Response Example Plain text { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "TimeZoneSettingsV1", "state": { "timeZoneOffset": { "reported": { "value": -25200 } }, "dstSetting": { "reported": { "value": "ENABLED" } }, "dstStart": { "reported": { "value": "3022" } }, "dstEnd": { "reported": { "value": "B012" } }, "dstOffset": { "reported": { "value": 3600 } } } } ] } } }
  • [WifiSettingsV1](https://developers.yonomi.cloud/devicemanagement/traits/wifisettingsv1.md): Settings and configuration information for device Wifi capabilities. Trait Type: Standard Action Mutations Note: See Overview: Device Action Lifecycle for more information on action flows WifiSettingsV1SetWifiConnectionSettings action Modify the wifiConnectivitySetting value. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. WifiSettingsV1SetWifiConnectionSettingsArgs! false WifiSettingsV1SetWifiConnectionSettingsArgs Fields Title Description Title Description Field Name Description Data Type Nullable wifiConnectivitySetting Device setting to enable / disable wifi functionality of the device wifiConnectivitySettingEnum false Enum Values Title Description Enumerated Value Description ENABLED Device wifi connectivity is enabled. DISABLED Device wifi connectivity is disabled. GQL Examples Request Example Gql mutation WifiSettingsV1SetWifiConnectionSettings { WifiSettingsV1SetWifiConnectionSettings( deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" traitActionArgs: { wifiConnectivitySetting: ENABLED } ) { deviceId actionId traitName } } Response Example JSON { "data": { "WifiSettingsV1SetWifiConnectionSettings": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } WifiSettingsV1ConnectStandardAccessPoint action Allows user to link to an access point using 802.11 without enterprise authentication protocol. Note: This mutation is a BLE Only command and requires the additional steps of establishing a secure BLE connection to the device before submitting the mutation as shown in the overview pages for action lifecycle. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. WifiSettingsV1ConnectStandardAccessPointArgs! false WifiSettingsV1ConnectStandardAccessPointArgs Fields Title Description Title Description Field Name Description Data Type Nullable ssid Network ssid that is desired to connect device to. string false password Network password used to connect device to network. Note: Password value should be the value that was encrypted via BLE Connection to device prior to submitting request. string false encryptionAlgorithm Protocol that access point is set to use when encrypting/decrypting communications. encryptionAlgorithmEnum false Enum Values Title Description Enumerated Value Description WPA2 Connected to wifi access point using WPA2 encyption protocol. WPA3 Connected to wifi access point using WPA3 encyption protocol. GQL Examples Request Example Gql mutation WifiSettingsV1ConnectStandardAccessPoint { WifiSettingsV1ConnectStandardAccessPoint( deviceId: 9a8f6104-6c50-476e-90ee-16b9a2dafc8d traitActionArgs: { ssid: "myNetworkName" password: "mobileEncryptedPassword" encryptionAlgorithm: WPA2 } ) { deviceId actionId traitName } } Response Example JSON { "data": { "WifiSettingsV1ConnectStandardAccessPoint": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } WifiSettingsV1ConnectEnterpriseAccessPoint action Allows user to link to an access point using 802.11 with enterprise authentication protocol. Note: This mutation is a BLE Only command and requires the additional steps of establishing a secure BLE connection to the device before submitting the mutation as shown in the overview pages for action lifecycle. Mutation Inputs Title Description Title Description Input Name Description Data Type Nullable deviceId uuid of the device to which mutation should apply ID! false traitActionArgs See table below for specific fields. WifiSettingsV1ConnectEnterpriseAccessPointArgs! false WifiSettingsV1ConnectStandardAccessPointArgs Fields Title Description Title Description Field Name Description Data Type Nullable ssid Network ssid that is desired to connect device to. string false password Network password used to connect device to network. Note: Password value should be the value that was encrypted via BLE Connection to device prior to submitting request. string false username Username that device should use to connect to enterprise access point. string false encryptionAlgorithm Protocol that access point is set to use when encrypting/decrypting communications. encryptionAlgorithmEnum false Enum Values Title Description Enumerated Value Description WPA2 Connected to wifi access point using WPA2 encyption protocol. GQL Examples Request Example Gql mutation WifiSettingsV1ConnectEnterpriseAccessPoint { WifiSettingsV1ConnectEnterpriseAccessPoint( deviceId: 9a8f6104-6c50-476e-90ee-16b9a2dafc8d traitActionArgs: { ssid: "myNetworkName" password: "mobileEncryptedPassword" username: "userName" encryptionAlgorithm: WPA2 } ) { deviceId actionId traitName } } Response Example JSON { "data": { "WifiSettingsV1ConnectEnterpriseAccessPoint": { "actionId": "7eb3629a-a1c3-49f0-89b6-2831d500ac68", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d" } } } Reported States Note: See Overview: Device Reported State for more information on reported state flows. State Definitions wifiBootVersion state Current wifi subsystem bootloader version used on device. Data Type: string wifiAppVersion state Current wifi subsystem app version used on device. Data Type: string wifiConnectivitySetting state Device setting to enable / disable wifi functionality of the device. Data Type: enum Valid Values Title Description Enumerated Value Description ENABLED Device wifi connectivity is enabled. DISABLED Device wifi connectivity is disabled. UNSUPPORTED Device has not yet reported a value for this field. macAddress state Wifi MAC Address. Data Type: string lanIpAddress state LAN Wifi IP Address. Data Type: string activeSsid state Information on the ssid of the active connected wifi network. Data Type: string activeSignalStrength state Information on the signal strength of the active connected wifi network. Signal strength reported using RSSI values (-dBm) Data Type: int activeAccessPointType state Information on the type (enterprise or non-enterprise) of access point that the device is currently set to link to. Data Type: enum Valid Values Title Description Enumerated Value Description NO_ACTIVE_LINK Device has not yet reported a value for this field. ENTERPRISE Device active connection uses enterprise access point. NON_ENTERPRISE Device active connection uses non-enterprise access point. activeEncryptionAlgorithm state The encryption algorithm that the device is currently set to use in communication with the linked access point. Data Type: enum Valid Values Title Description Enumerated Value Description NO_ACTIVE_LINK Device has not yet reported a value for this field. WPA2 Connected to wifi access point using WPA2 encyption protocol. WPA3 Connected to wifi access point using WPA3 encyption protocol. activeEnterpriseUsername state Information on the username the device is set to use in connecting with the linked access point. Data Type: string Device State Query GQL Examples Request Example GraphQL query Device { device(deviceId: "9a8f6104-6c50-476e-90ee-16b9a2dafc8d") { id traits { ... on WifiSettingsV1DeviceTrait { name state { wifiBootVersion { reported { value } } wifiAppVersion { reported { value } } wifiConnectivitySetting { reported { value } } lanIpAddress { reported { value } } macAddress { reported { value } } activeSsid { reported { value } } activeSignalStrength { reported { value } } activeAccessPointType { reported { value } } activeEnterpriseUsername { reported { value } } activeEncryptionAlgorithm { reported { value } } } } } } } Response Example JSON { "data": { "device": { "id": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traits": [ { "name": "WifiSettingsV1", "state": { "wifiBootVersion": { "reported": { "value": "2.8.3.1" } }, "wifiAppVersion": { "reported": { "value": "2.8.2.0.27" } }, "wifiConnectivitySetting": { "reported": { "value": "ENABLED" } }, "lanIpAddress": { "reported": { "value": "10.x.x.x" } }, "macAddress": { "reported": { "value": "FA:16:3E:7A:2B:9C" } }, "activeSsid": { "reported": { "value": "myNetworkName" } }, "activeSignalStrength": { "reported": { "value": -45 } }, "activeAccessPointType": { "reported": { "value": "NON_ENTERPRISE" } }, "activeEnterpriseUsername": { "reported": { "value": "" } }, "activeEncryptionAlgorithm": { "reported": { "value": "WPA2" } } } } ] } } } Notification Events Note: See Overview: Device Notifications for more information on notfication event flows. infoDailyWifiConnects Periodic information on times device connected to Wifi in last 24 hours. Details Fields Title Description Title Field Name Description Data Type connectsQuantity Amount of times device has connected to wifi in last 24 hours. int Event Example JSON { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDailyWifiConnects", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "WifiSettingsV1", "message": "Total number of wifiConnect events that occurred in the last 24 hours", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "connectsQuantity": 2 } } ] } infoDailyWifiDisconnects Periodic information on times device connected to Wifi in last 24 hours. Details Fields Title Description Title Field Name Description Data Type disconnectsQuantity Amount of times device has disconnected from wifi in last 24 hours. int Event Example JSON { "eventType": "DEVICE_NOTIFICATION_REPORTED", "notifications": [ { "category": "notification", "notificationName": "infoDailyWifiDisconnects", "notificationType": "INFO", "type": "notification reported", "createdAt": "2024-12-20T14:49:55.000Z", "sampledAt": "2024-12-20T14:49:39.663Z", "installationId": "819cd607-aede-482e-9aa0-8b65d420e300", "deviceId": "9a8f6104-6c50-476e-90ee-16b9a2dafc8d", "traitName": "WifiSettingsV1", "message": "Total number of wifiDisconnect events that occurred in the last 24 hours", "id": "92197db2-63a4-4832-9a20-59dd188b6504", "details": { "disconnectsQuantity": 2 } } ] }
    • [WiFi error messages](https://developers.yonomi.cloud/devicemanagement/traits/wifisettingsv1/wifi-error-messages.md): While setting up a device with a WiFi connection, different types of errors may be encountered. The table below describes the error conditions and the error messages that will be returned via webhook. Note: the error messages contain error codes (all possibilities relating to each condition are listed in the table) relating to underlying error details that can be helpful to Allegion for further troubleshooting. Please report these codes if you contact Allegion on this topic. These error messages are published in the DEVICE_ACTION_UPDATED event - if the action to connect to wifi fails, the rejection event will return the error that is applicable. Title Description Error condition Error message Device encountered an issue initialising the connection Internal device error. Please try again. (Error: 1, 13, 22, 23, 24, 30) n.b. only one error code is reported per error message, depending on the error details. Errors in the SSID, Password, and/or Username Invalid Network Credentials. Please try again. (Error: 3, 9, 19, 20) n.b. only one error code is reported per error message, depending on the error details. A request for IP configuration fails due to the AP not being connected Network Error. IP not connected. (Error: 16) A request to acquire an IP fails Network Error. Failed to acquire IP. (Error: 4) The Access Point is not found Network Error. Access point not found. (Error: 18) Authentication fails during the join process Network Error. Authentication failed. (Error: 21) A de-authentication is received from the Access Point Network Error. Network de-authentication. (Error: 25) The WPA or WPA2 4-way handshake fails Network Error. WPA or WPA2 handshake failed. (Error: 26) The SAE or WPA3 authentication fails Network Error. SAE or WPA3 authentication failed. (Error: 27) The selected channel or band is invalid or not supported Network Error. Channel or band is invalid or not supported. (Error: 28) The maximum number of clients is exceeded on the Access Point Network Error. Max number of clients exceeded. (Error: 29) The security mode or type is invalid or not supported Network Error. Security mode or type is invalid. (Error: 31)