UniFi Access API Docs

English

繁體中文

English

繁體中文

Appearance

User ​

The APIs here are designed for managing users, including handling their basic information and assigning NFC cards, PIN codes, and access policies to them.

Schemas ​

ParameterTypeDescription
IdStringIdentity ID of the user.
first_nameStringFirst name of the user.
last_nameStringLast name of the user.
full_nameStringFull name of the user.
aliasStringPreferred name of the user.
user_emailStringEmail of the user. UniFi Access Requirement: 1.22.16 or later
email_statusStringThe status of the user's email.
phoneStringContact phone number of the user.
employee_numberStringEmployee number of the user.
onboard_timeIntegerUser onboarding date.
nfc_cardsArray[Object]Token associated with the bound NFC card.
nfc_cards[].idStringDisplay ID of the NFC card.
nfc_cards[].tokenStringUnique NFC card token.
license_plates[].idStringUnique ID of the license plate.
license_plates[].credentialStringLicense plate number.
license_plates[].credential_typeStringType of credential, should be "license".
license_plates[].credential_statusStringStatus of the credential enum credential_status {active, deactivate}.
pin_codeObjectToken associated with the bound PIN code.
pin_code.tokenStringThe user's PIN hash code credential for unlocking a door.
access_policy_idsArray<String]Collection of the access policy ID.
access_policiesArray[Object]All policies assigned to the user.
statusStringenum status {ACTIVE, PENDING, DEACTIVATED} ACTIVE: The user account is in active status. PENDING: A new admin account has been invited by the SSO account, but the invitation has not been accepted. DEACTIVATED: The account has been deactivated.
touch_passArray[Object]Touch Pass assigned to the user, A user can only be assigned one TouchPass.

User Registration ​

This API allows you to register a new user.

Request URL: /api/v1/developer/users
Permission Key: edit:user
Method: POST

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Body ​

ParameterRequiredTypeDescriptionExampleHow to Get It?
first_nameTStringFirst name of the user.
last_nameTStringLast name of the user.
user_emailFStringEmail of the user. UniFi Access Requirement: 1.22.16 or later
employee_numberFStringEmployee number of the user. Omit this parameter if it doesn't need to be updated.
onboard_timeFIntegerUser onboarding date.1689150139

Response Body ​

See Response Schema for full field definitions.

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success",
  "data": {
    "first_name": "Fist Name",
    "last_name": "Last Name",
    "id": "37f2b996-c2c5-487b-aa22-8b453ff14a4b",
    "user_email": "example@*.com"
  }
}

Request Sample ​

The request body should be a JSON object containing the following fields:

bash
curl '{host}/api/v1/developer/users'
-H 'Authorization: Bearer wHFmHR*****kD6wHg'
-H 'accept: application/json'
-H 'content-type: application/json'
--data-raw \
{
    "first_name":"H",
    "last_name":"L",
    "employee_number":"100000",
    "onboard_time":1689150139,
    "user_email":"example@*.com"
}'
--insecure

Update User ​

This API allows you to update user details.

Request URL: /api/v1/developer/users/:id
Permission Key: edit:user
Method: PUT

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionExample
idTStringIdentity ID of the user.348e868e-534a-4ace-ba77-ce80394e31e3

Request Body ​

ParameterRequiredTypeDescriptionExampleHow to Get It?
first_nameFStringFirst name of the user.
last_nameFStringLast name of the user.
user_emailFStringEmail of the user. UniFi Access Requirement: 1.22.16 or later
employee_numberFStringEmployee number of the user.
onboard_timeFIntegerUser onboarding date.1689150139
statusFStringStatus of the user."ACTIVE" "DEACTIVATED"

Response Body ​

See Response Schema for full field definitions.

Response Sample ​

json
{
  "code": "SUCCESS",
  "data": null,
  "msg": "success"
}

Request Sample ​

The request body should be a JSON object containing the following fields:

bash
curl -XPUT '{host}}/api/v1/developer/user'  
-H 'Authorization:Bearer wHFmHR*****kD6wHg'  
-H 'accept:application/json'  
-H 'content-type:application/json'  
--data-raw {'  
    "first_name":"H",  
    "last_name":"L",  
    "employee_number":"",  
    "user_email":"example@*.com",  
    "pin_code":"",  
    "onboard_time":1689150139,  
    "status":"ACTIVE"  
}  
--insecure

Fetch User ​

This API allows you to fetch user details.

Request URL: /api/v1/developer/users/:id
Permission Key: view:user
Method: GET

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionExample
idTStringIdentity ID of the user.348e868e-534a-4ace-ba77-ce80394e31e3

Query Parameters ​

ParameterRequiredTypeDescriptionExample
expand[]FBooleanDetermine whether to return the access policies assigned to a user (Optional).expand|=access_policy

Response Body ​

See Response Schema for full field definitions.

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": {
        "access_policies": [
            {
                "id": "edbc80df-3698-49fd-8b53-f1867f104947",
                "name": "test",
                "resources": [
                    {"id": "d5573467-d6b3-4e8f-8e48-8a322b91664a", "type": "door_group"},
                    {"id": "5c496423-6d25-4e4f-8cdf-95ad5135188a", "type": "door_group"},
                    {"id": "6ff875d2-af87-470b-9cb5-774c6596afc8", "type": "door"}
                ],
                "schedule_id": "73facd6c-839e-4521-a4f4-c07e1d44e748"
            }
        ],
        "access_policy_ids": ["edbc80df-3698-49fd-8b53-f1867f104947"],
        "employee_number": "",
        "first_name": "******",
        "id": "17d2f099-99df-429b-becb-1399a6937e5a",
        "last_name": "L",
        "user_email": "example@*.com",
        "touch_pass": {
            "activated_at": {},
            "bundles": [
                {
                    "bundle_id": "caf6bd5b-6b8d-409a-b500-977a0f02b181",
                    "bundle_status": "SUSPENDED",
                    "device_id": "device-id-1",
                    "device_name": "Example Android",
                    "device_type": 20,
                    "source": "google"
                }
            ],
            "card_id": "70A3-2FAD-181B-4CC9",
            "card_name": "Test",
            "expired_at": {},
            "id": "c83b69ff-1992-4e7f-9287-1e6a161adeea",
            "last_activity": "2025-04-10T00:46:20+08:00",
            "status": "SUSPENDED",
            "user_avatar": "",
            "user_email": "example@ui.com",
            "user_id": "3e763e5d-6804-437d-ae8d-3fee74119b80",
            "user_name": "Example Name",
            "user_status": "ACTIVE"
        },
        "nfc_cards": [
            {"id": "100001", "token": "d27822fc682b478dc637c6db01813e465174df6e54ca515d8427db623cfda1d0", "type": "ua_card"}
        ],
        "license_plates": [
            {"credential": "jq178", "credential_status": "active", "credential_type": "license", "id": "5cac1825-f5e9-410d-a32e-a1fb9fc83b92"}
        ],
        "onboard_time": 1689047588,
        "pin_code": {"token": "5f742ee4424e5a7dd265de3461009b9ebafa1fb9d6b15018842055cc0466ac56"},
        "status": "ACTIVE"
    },
    "msg": "success"
}

Request Sample ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/api/v1/developer/users/348e868e-534a-4ace-ba77-ce80394e31e3? expand[]=access_policy'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Fetch All Users ​

This API allows you to fetch all users.

Request URL: /api/v1/developer/users
Permission Key: view:user
Method: GET

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Query Parameters ​

ParameterRequiredTypeDescriptionExample
expand[]FBooleanDetermine whether to return the access policies assigned to a user (Optional).expand|=access_policy
page_numFStringCurrent page number in the pagination.1
page_sizeFStringNumber of users per page.25

Response Sample ​

json
{
"code": "SUCCESS",
"data": [ 
{
"access_policies": [ 
{
"id": "73f15cab-c725-4a76-a419-a4026d131e96",
"name": "Default Admin Policy",
"resources": [ 
{
"id": "d5573467-d6b3-4e8f-8e48-8a322b91664a",
"type": "door_group"
},
{
"id": "5c496423-6d25-4e4f-8cdf-95ad5135188a",
"type": "door_group"
}
],
"schedule_id": "73facd6c-839e-4521-a4f4-c07e1d44e748"
}
],
"access_policy_ids": [ 
"73f15cab-c725-4a76-a419-a4026d131e96"
],
"employee_number": "", 
"first_name": "UniFi",
"id": "83569f9b-0096-48ab-b2e4-5c9a598568a8",
"last_name": "User",
"touch_pass": { 
"activated_at": {}, 
"bundles": [ 
{
"bundle_id": "caf6bd5b-6b8d-409a-b500-977a0f02b181",
"bundle_status": "SUSPENDED",
"device_id": "device-id-1",
"device_name": "Example Android",
"device_type": 20,
"source": "google"
}
],
"card_id": "70A3-2FAD-181B-4CC9",
"card_name": "Test",
"expired_at": {},
"id": "c83b69ff-1992-4e7f-9287-1e6a161adeea",
"last_activity": "2025-04-10T00:46:20+08:00",
"status": "SUSPENDED", 
"user_avatar": "",
"user_email": "example@ui.com",
"user_id": "3e763e5d-6804-437d-ae8d-3fee74119b80",
"user_name": "Example Name",
"user_status": "ACTIVE"
},
"user_email": "",
"nfc_cards": [],
"license_plates": [
    {
        "credential": "jq178",
        "credential_status": "active",
        "credential_type": "license",
        "id": "5cac1825-f5e9-410d-a32e-a1fb9fc83b92"
    }
],
"onboard_time": 0,
"pin_code": null,
"status": "ACTIVE"
},
{
"access_policies": [
    {
        "id": "c1682fb8-ef6e-4fe2-aa8a-b6f29df753ff",
        "name": "policy_1690272668035",
        "resources": [
            {
                "id": "6ff875d2-af87-470b-9cb5-774c6596afc8",
                "type": "door"
            }
        ],
        "schedule_id": "0616ef06-b807-4372-9ae0-7a87e12e4019"
    }
],
"access_policy_ids": [
    "c1682fb8-ef6e-4fe2-aa8a-b6f29df753ff"
],
"employee_number": "",
"first_name": "Tttttt",
"id": "3a3ba57a-796e-46e0-b8f3-478bb70a114d",
"last_name": "Tttt",
"nfc_cards": [],
"onboard_time": 1689048000,
"pin_code": null,
"status": "ACTIVE"
}
],
"msg": "success",
"pagination": {
    "page_num": 1,
    "page_size": 97,
    "total": 97
}
}

Request Sample ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/api/v1/developer/users?page_num=1&page_size=25&expand[]=access_policy'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Assign Access Policy to User ​

Request URL: /api/v1/developer/users/:id/access_policies
Permission Key: edit:user
Method: PUT

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
access_policy_idsTArray:StringCollection of multiple policy IDs.Get it from the API /api/v1/developer/access_policies

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
### Assign access policies to user
curl -XPUT '{host}/api/v1/developer/users/38857332-7a5e-4bb6-8837-651b2a47cea5/access_policies' \
-H 'Authorization: Bearer wHFmHR*****kD6wHg' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
--data-raw '{ "access_policy_ids": ["03895c7f-9f53-4334-812b-5db9c122c109", "3b6bcb0c-7498-44cf-8615-00a96d824cbe"] }' \
--insecure
bash
### Remove all access policies from user
curl -XPUT '{host}/api/v1/developer/users/38857332-7a5e-4bb6-8837-651b2a47cea5/access_policies' \
-H 'Authorization: Bearer wHFmHR******kD6wHg' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
--data-raw '{ "access_policy_ids": [] }' \
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Assign NFC Card to User ​

Request URL: /api/v1/developer/users/:id/nfc_cards
Permission Key: edit:user
Method: PUT

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
tokenTStringToken of the NFC card.Get it from the API /api/v1/developer/nfc_cards sessions/{session_id}
force_addFBooleanDetermine whether to overwrite an NFC card that has already been assigned.true or false

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPUT '{host}/api/v1/developer/users/17d2f099-99df-429b-becb-1399a6937e5a/nfc_cards'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--data-raw {'  
    "token": "d27822fc682b478dc637c6db01813e465174df6e54ca515d8427db623cfda1d0",  
    "force_add": true}

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Unassign NFC Card from User ​

Request URL: /api/v1/developer/users/:id/nfc_cards/delete
Permission Key: edit:user
Method: PUT

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
tokenTStringToken of the NFC card.Get it from the API /api/v1/developer/users

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XDELETE '{host}/api/v1/developer/users/17d2f099-99df-429b-becb-1399a6937e5a/nfc_cards/delete'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
-d '{  
    "token": "d27822fc682b478dc637c6db01813e465174df6e54ca515d8427db623cfda1d0"  
}  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Assign PIN Code to User ​

Request URL: /api/v1/developer/users/:id/pin_codes
Permission Key: edit:user
Method: PUT

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
pin_codeTStringGenerate a PIN code for the user to unlock doors.Get it from the API /api/v1/developer/pin_codes

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPUT '{host}/api/v1/developer/users/17d2f099-99df-429b-becb-1399a6937e5a/pin_codes'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--data-raw {'  
    "pin_code": "57301208"  
}  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Unassign PIN Code from User ​

Request URL: /api/v1/developer/users/:id/pin_codes
Permission Key: edit:user
Method: DELETE

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XDELETE '{host}/api/v1/developer/users/17d2f099-99df-429b-becb-1399a6937e5a/pin_codes'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Create User Group ​

Request URL: /api/v1/developer/user_groups
Permission Key: edit:user
Method: POST
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
nameTStringName of the group.
up_idFStringParent group ID (Optional)Get it from the API /api/v1/developer/user_groups

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPOST '{host}/api/v1/developer/user_groups'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--data-raw {'  
    "name": "Group Name",  
    "up_id": "013d05d3-7262-4908-ba69-badbbbfb8f5a6"  
}  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Fetch All User Groups ​

Request URL: /api/v1/developer/user_groups
Permission Key: view:user
Method: GET
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/api/v1/developer/developer/user_groups'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": [ 
        {
        "full_name": "Group Name",
        "id": "75011ee6-b7ab-4927-9d9f-dd08ef0a3199",
        "name": "Group Name",
        "up_id": "a27899fc-a2d1-4797-8d4d-86118f8555f3",
        "up_ids": [
            "a27899fc-a2d1-4797-8d4d-86118f8555f3"
        ]
        }
    ],
    "msg": "success"
}

Fetch User Group ​

Request URL: /api/v1/developer/user_groups/:id
Permission Key: view:user
Method: GET
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/api/v1/developer/developer/user_groups/75011ee6-b7ab-4927-9d9f-dd08ef0a3199'  
-H 'Authorization: Bearer wHFmHR*****KD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": {
        "full_name": "Group Name",
        "id": "75011ee6-b7ab-4927-9d9f-dd08ef0a3199",
        "name": "Group Name",
        "up_id": "a27899fc-a2d1-4797-8d4d-86118f8555f3",
        "up_ids": [
            "a27899fc-a2d1-4797-8d4d-86118f8555f3"
        ]
    },
    "msg": "success"
}

Update User Group ​

Request URL: /api/v1/developer/user_groups/:id
Permission Key: edit:user
Method: PUT
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
nameTStringName of the group.
up_idFStringParent group IDGet it from the API /api/v1/developer/user_groups

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPUT '{host}/api/v1/developer/user_groups/75011ee6-b7ab-4927-9d9f-dd08ef0a3199'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--data-raw {'  
    "name": "Group Name",  
    "up_id": "013d05d3-7262-4908-ba69-badbbb8f5a6"  
}  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Delete User Group ​

Request URL: /api/v1/developer/user_groups/:id
Permission Key: edit:user
Method: DELETE
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XDELETE '{host}/api/v1/developer/developer/user_groups/75011ee6-b7ab-4927-9d9f-dd08ef0a3199'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Assign User to User Group ​

Request URL: /api/v1/developer/user_groups/:id/users
Permission Key: edit:user
Method: POST
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
TArray:StringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPOST '{host}/api/v1/developer/user_groups/75011ee6-b7ab-4927-9d9f-dd08ef0a3199/users' \
-H 'Authorization: Bearer wHFmHR******kD6wHg' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
--data-raw '["7c6e9102-acb7-4b89-8ed4-7561e6fb706c", "fd63bc4c-52e0-4dbf-a699-e1233339c73b"]' \
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Unassign User from User Group ​

Request URL: /api/v1/developer/user_groups/:id/users/delete
Permission Key: edit:user
Method: POST
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
TArray:StringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPOST '{host}/api/v1/developer/user_groups/75011ee6-b7ab-4927-9d9f-dd08ef0a3199/users/delete' \
-H 'Authorization: Bearer wHFmHR*****kD6wHg' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
--data-raw '["7c6e9102-acb7-4b89-8ed4-7561e6fb706c", "fd63bc4c-52e0-4dbf-a699-e1233339c73b"]' \
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Fetch Users in a User Group ​

This API allows you to fetch only the users in a user group, excluding any subgroups.

Request URL: /api/v1/developer/user_groups/:id/users
Permission Key: view:user
Method: GET
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Response Body ​

See Response Schema for full field definitions.

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/api/v1/developer/user_groups/23676a54-382e-4121-AA80-878d2d9bacaa/users'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": [
        {"alias": "", "avatar_relative_path": "", "email": "*@*.com", "email_status": "UNVERIFIED", "employee_number": "1000000", "first_name": "", "full_name": "", "id": "27aa91ac-2924-43d4-82e1-24b6a570d29e", "last_name": "Chen", "onboard_time": 1689150139, "phone": "", "status": "ACTIVE", "user_email": "", "username": ""}
    ],
    "msg": "success"
}

Fetch All Users in a User Group ​

This API allows you to fetch all users in a user group, including those in subgroups.

Request URL: /api/v1/developer/user_groups/:id/users/all
Permission Key: view:user
Method: GET
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Response Body ​

See Response Schema for full field definitions.

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}'/api/v1/developer/user_groups/23676a54-382e-4121-AA80-878d2d9bacaa/users/all'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": [ 
        {
            "alias": "", 
            "avatar_relative_path": "", 
            "email": "@*.com", 
            "email_status": "UNVERIFIED", 
            "employee_number": "1000000", 
            "first_name": "", 
            "full_name": "", 
            "id": "27aa91ac-2924-43d4-82e1-24b6a570d29e", 
            "last_name": "Chen", 
            "onboard_time": 1689150139, 
            "phone": "", 
            "status": "ACTIVE", 
            "user_email": "", 
            "username": ""
        }
    ],
    "msg": "success"
}

Fetch the Access Policies Assigned to a User ​

This API allows you to fetch the access policies assigned to a user.

Request URL: /api/v1/developer/users/:id/access_policies
Permission Key: view:user
Method: GET
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Query Parameters ​

ParameterRequiredTypeDescriptionExample
only_user_policiesFBooleanIf 'only_user_policies' is set to false, all policies of the group the user belongs to are displayed. If set to true, only the policies assigned directly to the user are shown.only_user_policies=true

Response Body ​

See Response Schema for full field definitions.

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/users/27aa91ac-2924-43d4-82e1-24b6a570d29e/access_policies? only_user_policies=false' -H 'Authorization: Bearer wHFmHR*****kD6wHg' -H 'accept: application/json' -H 'content-type: application/json' --insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "data": [
    {
      "id": "89a4ca95-1502-4ae7-954f-d986b67afe5c",
      "name": "Default Site Policy",
      "resources": [
        {
          "id": "fd2a06e2-81af-4cf4-9bd5-8bceb5e7b7d7",
          "type": "door_group"
        }
      ],
      "schedule_id": "6b79d12a-2a6e-4463-949c-f1a98fff40d2"
    },
    {
      "id": "bbe48a65-2ac1-4bf6-bd65-bc8f9ee7fb75",
      "name": "Access Policy Name",
      "resources": [],
      "schedule_id": "f7414bcd-f0cc-4d3e-811a-b5ac75f7ddb8"
    }
  ],
  "msg": "success"
}

Assign Access Policy to User Group ​

This API is used to assign access policies to a user group.

Request URL: /api/v1/developer/user_groups/:id/access_policies
Permission Key: edit:user
Method: PUT
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
access_policy_idsTArray:StringIdentity ID of the access policy.Get it from the API /api/v1/developer/access_policies

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XPUT '{host}/user_groups/23676a54-382e-4121-AA80-878d2d9bacaa/access_policies'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--data '{
    "access_policy_ids": [  
        "bbe48a65-2ac1-4bf6-bd65-bc8f9ee7fb75"  
    ]  
}  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "data": null,
  "msg": "success"
}

Fetch the Access Policies Assigned to a User Group ​

This API allows you to fetch the access policies assigned to a user group.

Request URL: /api/v1/developer/user_groups/:id/access_policies
Permission Key: view:user
Method: GET
UniFi Access Requirement: 2.2.6 or later
API version: v1

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user group.Get it from the API /api/v1/developer/user_groups

Response Body ​

See Response Schema for full field definitions.

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/user_groups/23676a54-382e-4121-AA80-878d2d9bacaa/access_policies'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "data": [
    {
      "id": "89a4ca95-1502-4ae7-954f-d986b67afe5c",
      "name": "Default Site Policy",
      "resources": [
        {
          "id": "fd2a06e2-81af-4cf4-9bd5-8bceb5e7b7d7",
          "type": "door_group"
        }
      ],
      "schedule_id": "6b79d12a-2a6e-4463-949c-f1a98fff40d2"
    },
    {
      "id": "bbe48a65-2ac1-4bf6-bd65-bc8f9ee7fb75",
      "name": "Access Policy Name",
      "resources": [],
      "schedule_id": "f7414bcd-f0cc-4d3e-811a-b5ac75f7ddb8"
    }
  ],
  "msg": "success"
}

Delete User ​

This API allows you to delete a user whose status is disabled.

Request URL: /api/v1/developer/users/:id
Permission Key: edit:user
Method: DELETE
UniFi Access Requirement: 3.1.30 or later
API version: v1
Note: Only users with a disabled can be deleted.

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringIdentity ID of the user.Get it from the API /api/v1/developer/users

Request Sample: Shell/cURL ​

The request body should be a JSON object containing the following fields:

bash
curl -XDELETE '{host}/api/v1/developer/developer/users/348e868e-534a-4ace-ba77-ce80394e31e3'  
-H 'Authorization: Bearer wHFmHR*****kD6wHg'  
-H 'accept: application/json'  
-H 'content-type: application/json'  
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "msg": "success"
}

Search Users ​

This API allows you to fetch all users.

Request URL: /api/v1/developer/users/search
Permission Key: view:user
Method: GET
UniFi Access Requirement: 3.1.30 or later

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Query Parameters ​

ParameterRequiredTypeDescriptionExample
keywordFStringDetermine whether to return the access policies assigned to a user (Optional).keyword=Name
user_idFStringSupport filtering by multiple user Identity IDs.user_id=472cabd2-0634-4e85-9e8d-5a73b500516a&user_id=21472b1d-aa3a-4f2c-855e-0ec3dcaaeb5a
only_adminFBooleanFilter to display only admin users.only_admin=false
statusFStringSupport filtering by multiple user statuses.status=ACTIVE&status=DEACTIVATED&status=PENDING
page_numFStringCurrent page number in the pagination.1
page_sizeFStringNumber of users per page.25

Response Body ​

See Response Schema for full field definitions.

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": [
        {
            "alias": "",
            "avatar_relative_path": "/avatar/186b07b1-fa13-49b5-8954-399d1b9c5285",
            "email": "User1@*.com",
            "email_status": "VERIFIED",
            "employee_number": "",
            "first_name": "Name",
            "full_name": "Full Name",
            "id": "472cabd2-0634-4e85-9e8d-5a73b500516a",
            "last_name": "Last Name",
            "nfc_cards": [],
            "onboard_time": 0,
            "phone": "",
            "pin_code": null,
            "status": "ACTIVE",
            "user_email": "User1@*.com",
            "username": ""
        }
    ],
    "msg": "success"
}

Request Sample ​

The request body should be a JSON object containing the following fields:

bash
curl -XGET '{host}/api/v1/developer/users/search?keyword=Name&user_id=472cabd2-0634-4e85-9e8d-5a73b500516a&user_id=21472b1d-AA3a-4f2c-855e-0ec3dcaaeb5a&only_admin=false&status=ACTIVE&status=DEACTIVATED&page_size=10&page_num=1' -H 'Authorization: Bearer wHFmHR*****kD6wHg' -H 'accept: application/json' -H 'content-type: application/json' --insecure

Assign Touch Pass to User ​

This API assigns a suspended or inactive Touch Pass to a specific user.

Request URL: /api/v1/developer/users/:user_id/touch_passes/:touch_pass_id
Permission Key: edit:user
Method: PUT
UniFi Access Requirement: Version 3.2.20 or later

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionExample UUIDHow to Get It?
user_idTStringID of the user assigned to the Touch Pass.cadb8707-a2c1-4407-a904-24868bf4aad9Get it from API /api/v1/developer/users
touch_pass_idTStringTouch Pass ID.e9a8e5ad-0afd-4abf-a9ce-9535df6bc00dGet it from API /api/v1/developer/credentials/touch_passes/assignable

Response Body ​

ParameterTypeDescription
idStringTouch Pass ID.
card_idStringCard ID associated with Touch Pass.
card_nameStringCard name or alias.
statusStringenum status {PENDING} Touch Pass status after being assigned.
last_activityStringTimestamp of the last activity (ISO 8601 format).
bundlesArrayReserved for future use. Currently always an empty array.
user_idStringID of the user assigned to the Touch Pass.
user_nameStringFull name of the user.
user_emailStringEmail address of the user.
user_statusStringStatus of the user's account (empty if unavailable).
user_avatarStringURL of the user's avatar image (empty if unavailable).

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": {
        "bundles": [], "card_id": "104D-2E7D-0CF9-45B9",
        "card_name": "", "id": "e9a8e5ad-0afd-4abf-a9ce-9535df6bc00d",
        "last_activity": "2025-04-09T18:44:47+08:00",
        "status": "PENDING",
        "user_avatar": "", "user_email": "example@ui.com",
        "user_id": "cadb8707-a2c1-4407-a904-24868bf4aad9",
        "user_name": "Example Name",
        "user_status": ""
    },
    "msg": "success"
}

Request Sample ​

bash
curl --location --request PUT '{host}/api/v1/developer/users/cadb8707-a2c1-4407-a904-24868bf4aad9/touch_passes/e9a8e5ad-0afd-4abf-a9ce-9535df6bc00d' \
--header 'Authorization: Bearer wHFmHR*****kD6wHg' \
--data ''

Unassign Touch Pass from User ​

This API unassigns a Touch Pass from a specific user.

Request URL: /api/v1/developer/users/:user_id/touch_passes/:touch_pass_id
Permission Key: edit:user
Method: DELETE
UniFi Access Requirement: Version 3.2.20 or later

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionExample UUIDHow to Get It?
user_idTStringID of the user to unassign the Touch Pass from.cadb8707-a2c1-4407-a904-24868bf4aad9Get it from API /api/v1/developer/users
touch_pass_idTStringID of the Touch Pass to unassign.e9a8e5ad-0afd-4abf-a9ce-9535df6bc00dGet it from API /api/v1/developer/credentials/touch_passes

Response Body ​

ParameterTypeDescription
idStringTouch Pass ID.
card_idStringCard ID associated with Touch Pass.
card_nameStringCard name or alias.
statusStringenum status {SUSPENDED, INACTIVE} Touch Pass status after being unassigned.
last_activityStringTimestamp of the last activity (ISO 8601 format).
bundlesArrayReserved for future use. Currently always an empty array.
user_idStringEmpty string after unassignment.
user_nameStringEmpty string after unassignment.
user_emailStringEmpty string after unassignment.
user_avatarStringEmpty string after unassignment.
user_statusStringenum user_status {ACTIVE, PENDING} Status of the user at the time of unassignment.

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": {
        "bundles": [],
        "card_id": "104D-2E7D-0CF9-45B9",
        "card_name": "",
        "id": "e9a8e5ad-0afd-4abf-a9ce-9535df6bc00d",
        "last_activity": "2025-04-09T18:46:27+08:00",
        "status": "INACTIVE",
        "user_avatar": "",
        "user_email": "",
        "user_id": "",
        "user_name": "",
        "user_status": "ACTIVE"
    },
    "msg": "success"
}

Request Sample ​

bash
curl --location --request DELETE 'https://192.168.1.1:12445/api/v1/developer/users/cadb8707-a2c1-4407-a904-24868bf4aad9/touch_passes/e9a8e5ad-0afd-4abf-a9ce-9535df6bc00d' \
--header 'Authorization: Bearer wHFmHR*****kD6wHg' \
--data ''

Batch Assign Touch Passes to Users ​

This API allows assigning unassigned Touch Passes to users using their email addresses.

Request URL: /api/v1/developer/users/touch_passes/assign
Permission Key: edit:user
Method: PUT
UniFi Access Requirement: Version 3.2.20 or later

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Body ​

ParameterRequiredTypeDescriptionHow to Get It?
idsTArray of StringsList of user IDs to assign Touch Passes to.Get it from API /api/v1/developer/users
emailsFObject (Map)Email of the user.

Response Body ​

ParameterTypeDescription
idStringTouch Pass ID.
card_idStringCard ID associated with Touch Pass.
card_nameStringCard name or alias.
statusStringenum status {PENDING} Touch Pass status after being assigned.
last_activityStringTimestamp of the last activity (ISO 8601 format).
bundlesArrayReserved for future use. Currently always an empty array.
user_idStringID of the user assigned to the Touch Pass.
user_nameStringFull name of the user.
user_emailStringEmail address of the user.
user_statusStringStatus of the user's account (empty if unavailable).
user_avatarStringURL of the user's avatar image (empty if unavailable).

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": [
        {
            "bundles": [],
            "card_id": "05FD-99C6-1876-4EF9",
            "card_name": "",
            "id": "fdb79d4-c113-4893-9a3b-b61836b5108d",
            "last_activity": "2025-04-09T13:40:28+08:00",
            "status": "PENDING",
            "user_avatar": "https://192.168.1.1/proxy/users/public/avatar/5b7e0cef-dba1-415b-8ee7-7efb440645c1",
            "user_email": "example@ui.com",
            "user_id": "ed34ad8b-9d34-48a8-b110-0ddc5f1e6055",
            "user_name": "Example Name",
            "user_status": ""
        }
    ],
    "msg": "success"
}

Request Sample ​

bash
curl --location --request PUT \
'https://192.168.1.1:12445/api/v1/developer/users/touch_passes/assign' \
--header 'Authorization: Bearer wHFmHR*****kD6wHg' \
--header 'Content-Type: application/json' \
--data '{
    "ids": ["ed34ad8b-9d34-48a8-b110-0ddc5f1e6055"],
    "emails": {
        "ed34ad8b-9d34-48a8-b110-0ddc5f1e6055": "example@ui.com"
    }
}'

Assign License Plate Numbers to User ​

This API allows you to assign one or more license plate numbers to a specific user.

Request URL: /api/v1/developer/users/:id/license_plates
Permission Key: edit:user
Method: PUT
UniFi Access Requirement: Version 3.3.10 or later

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringBearer Token required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringUnique ID of the userGet it from /api/v1/developer/users

Request Body ​

An array of license plate strings to assign to the user.

ParameterRequiredTypeDescription
-TArray of StringsList of license plate numbers

Request Sample: Shell/cURL ​

bash
curl --location --request PUT 'https://192.168.1.1:12445/api/v1/developer/users/d0beeccd-0f5e-4606-9d6e-764e19685e27/license_plates' \
--header 'Authorization: Bearer vPUhdytCPDvt/+dSLlGTjw' \
--header 'Content-Type: application/json' \
--data '["abcd5", "efge36"]' \
--insecure

Response Sample ​

json
{
  "code": "SUCCESS",
  "data": null,
  "msg": "success"
}

Unassign License Plate Numbers from User ​

This API allows you to unassign a license plate number from a user.

Request URL: /api/v1/developer/users/:user_id/license_plates/:license_plate_id
Permission Key: edit:user
Method: DELETE
UniFi Access Requirement: Version 3.3.10 or later

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionExample UUIDHow to Get It?
user_idTStringID of the user to unassign the license plate number from.d0beecccd-0f5e-4606-9d6e-764e19685e27Get it from API /api/v1/developer/users
licenseplate_idTStringID of the license plate number to unassign.74f3c466-c564-4035-aebd-fd383ebebcc6aGet it from API /api/v1/developer/users

Request Sample: Shell/cURL ​

bash
curl --location --request DELETE 'https://192.168.1.1:12445/api/v1/developer/users/d0beeecd-0f5e-4606-9d6e-764e19685e27/license_plates/74f3c466-c564-4035-aebd-fd383ebebcc6a' \
--header 'Authorization: Bearer vPUhdtCPDvt/+dSLlGTjw'

Response Sample ​

json
{
  "code": "SUCCESS",
  "data": null,
  "msg": "success"
}

Upload User Profile Picture ​

This API allows you to upload a profile picture for a user.

Request URL: /api/v1/developer/users/:id/avatar
Permission Key: edit:user
Method: POST
UniFi Access Requirement: Version 3.3.10 or later
Note: Updating the profile picture is supported only for local users. UI Account users must update their profile picture through the UI Account interface (https://account.ui.com/).

Request Header ​

ParameterRequiredTypeDescription
AuthorizationTStringToken required for authentication and access control.

Request Path ​

ParameterRequiredTypeDescriptionHow to Get It?
idTStringUnique ID of the user.Get it from /api/v1/developer/users

Request Body (Multipart Form) ​

ParameterRequiredTypeDescription
fileTFileProfile picture image file to upload.

Request Sample: Shell/cURL ​

bash
curl --location 'https://192.168.1.1:12445/api/v1/developer/users/d0beeccd-0f5e-4606-9d6e-764e19685e27/avatar' \
--header 'Authorization: Bearer vPUhdytCPDvt/+dSLlGTjw' \
--form 'file=@"./fa8134ba-352a-4499-ab62-713618388148.jpeg'" --insecure

Response Sample ​

json
{
    "code": "SUCCESS",
    "data": {
        "avatar_url": "https://192.168.1.1/proxy/users/public/avatar/d0beecccd-0f5e-4606-9d6e-764e19685e27"
    },
    "msg": "success"
}