v3/Access API's

Create Access for Employee

Overview

This API endpoint allows you to create a new access schedule for an employee, specifying access type, schedule, and hierarchical access locations (site, building, floor, room, bed). The employee can be identified by ID or contact (email/phone).

The access_locations field uses a hierarchical array structure with support for wildcards ("*") at any level (site, building, floor, room, bed) to flexibly grant access to all or specific resources. Each rule can specify any combination of these levels, and wildcards mean access to everything below that level.

Endpoint Details

Method

POST

URL

https://api.mosler.in/api/v3/access/employee

Authentication

Headers

Name	Type	Required	Description
`apikey`	`string`	Yes	Your API key for authentication
`Content-Type`	`string`	Yes	`application/json`

Request Body

Name	Type	Required	Description
`ref_id`	`string`	Yes	Reference ID (8-12 alphanumeric chars)
`type`	`string`	Yes	Schedule type (`PERMANENT` or `TIMED`)
`access_type`	`string`	No	Access type (`EKEY` by default)
`startDate`	`string`	Cond.	ISO date string (required for `TIMED`, auto-set for `PERMANENT`)
`endDate`	`string`	Cond.	ISO date string (required for `TIMED`, auto-set for `PERMANENT`)
`contact`	`string`	No	Employee email or phone (at least one of `emp_id` or `contact` is required)
`emp_id`	`string`	No	Employee ObjectId (at least one of `emp_id` or `contact` is required)
`access_locations`	`array`	Yes	Array of access location rules (see below)

Access Location Rule (Hierarchical with Wildcards)

Each object in the access_locations array represents a rule. You can specify any combination of the following fields. Use "*" as a wildcard to indicate "all" at that level. If a level is omitted, it is not considered in the rule.

Name	Type	Required	Description
`site_id`	`string`	No	Site ObjectId or `"*"` for all sites
`building_id`	`string`	No	Building ObjectId or `"*"` for all buildings
`floor_id`	`string`	No	Floor ObjectId or `"*"` for all floors
`room_id`	`string`	No	Room ObjectId or `"*"` for all rooms
`bed_id`	`string`	No	Bed ObjectId or `"*"` for all beds

Rules:

Specify only the levels relevant to your access rule.
Use "*" for any field to indicate all resources at that level and below.
For example, { "site_id": "*" } gives access to everything in all sites, { "building_id": "B1", "room_id": "*" } gives access to all rooms in building B1, etc.

Use Cases & Examples

1. Access to All Beds in All Rooms in a Site

"access_locations": [
  { "site_id": "SITE_ID_1", "building_id": "*", "floor_id": "*", "room_id": "*", "bed_id": "*" }
]

2. Access to All Beds in a Building

"access_locations": [
  { "building_id": "BUILDING_ID_1", "floor_id": "*", "room_id": "*", "bed_id": "*" }
]

3. Access to All Beds on a Floor

"access_locations": [
  { "floor_id": "FLOOR_ID_1", "room_id": "*", "bed_id": "*" }
]

4. Access to All Beds in a Room

"access_locations": [
  { "room_id": "ROOM_ID_1", "bed_id": "*" }
]

5. Access to a Specific Bed in a Room

"access_locations": [
  { "room_id": "ROOM_ID_1", "bed_id": "BED_ID_1" }
]

6. Access to Specific Beds in Different Rooms

"access_locations": [
  { "room_id": "ROOM_ID_1", "bed_id": "BED_ID_1" },
  { "room_id": "ROOM_ID_2", "bed_id": "BED_ID_2" }
]

7. Access to All Beds in All Rooms on a Floor

"access_locations": [
  { "floor_id": "FLOOR_ID_1", "room_id": "*", "bed_id": "*" }
]

8. Access to a Room but Not to Any Beds

"access_locations": [
  { "room_id": "ROOM_ID_1" }
]

9. Access Across Multiple Sites

"access_locations": [
  { "site_id": "SITE_ID_1", "building_id": "*", "floor_id": "*", "room_id": "*", "bed_id": "*" },
  { "site_id": "SITE_ID_2", "building_id": "*", "floor_id": "*", "room_id": "*", "bed_id": "*" }
]

10. Access to Everything (Superuser)

"access_locations": [
  { "site_id": "*", "building_id": "*", "floor_id": "*", "room_id": "*", "bed_id": "*" }
]

Full Request Example

{
    "ref_id": "EMP123456",
    "type": "TIMED",
    "access_type": "EKEY",
    "startDate": "2025-07-03T09:00:00.000Z",
    "endDate": "2025-07-10T18:00:00.000Z",
    "contact": "employee@example.com",
    "access_locations": [
        {
            "site_id": "6530f9dce0c1bd73ded0d1be",
            "building_id": "*",
            "floor_id": "*",
            "room_id": "*",
            "bed_id": "*"
        },
        {
            "room_id": "6530f9dce0c1bd73ded0d1bf",
            "bed_id": "6530f9dce0c1bd73ded0d1c0"
        },
        {
            "room_id": "6530f9dce0c1bd73ded0d1bg",
            "bed_id": "6530f9dce0c1bd73ded0d1c1"
        }
    ]
}

Response Format

Success Response

Name	Type	Description
`success`	`boolean`	Always `true` for successful responses
`message`	`string`	Success message
`data`	`object`	Object containing created access details

Success Example

{
    "success": true,
    "message": "Employee access created successfully",
    "data": {
        "employee_id": "6530f9dce0c1bd73ded0d1aa",
        "schedule_id": "6530f9dce0c1bd73ded0d1bb",
        "access_type": "EKEY",
        "startDate": "2025-07-03T09:00:00.000Z",
        "endDate": "2025-07-10T18:00:00.000Z",
        "locations": [
            {
                "site": { "name": "Delhi", "_id": "6530f9dce0c1bd73ded0d1be" },
                "room": { "name": "101", "_id": "6530f9dce0c1bd73ded0d1bf" },
                "bed": { "name": "Bed 1", "_id": "6530f9dce0c1bd73ded0d1c0" }
            }
        ]
    }
}

Error Response Example

{
    "error": "Validation failed",
    "details": [
        {
            "path": ["startDate"],
            "message": "startDate is required for TIMED schedule type"
        }
    ]
}