PMS Open API

Last Updated on : 2025-05-30 01:56:03download

This article introduces the API interfaces for property management system integration.

API List

Request method	API	Description
POST	/v1.0/hotel/pms/checkin	Check-in
PUT	/v1.0/hotel/pms/checkout	Check-out
PUT	/v1.0/hotel/pms/change-room	Change room
PUT	/v1.0/hotel/pms/renew	Extend stay
POST	/v1.0/hotel/pms/checkin/guest	Add room occupant
PUT	/v1.0/hotel/pms/checkin/guest	Modify room occupant
DELETE	/v1.0/hotel/pms/checkin/guest	Delete room occupant
POST	/v1.0/hotel/pms/rooms	Add rooms
DELETE	/v2.0/hotel/pms/rooms	Delete rooms
POST	/v1.0/hotel/pms/rooms/sync	Synchronization of all room information
GET	/v1.0/hotel/pms/face/picture/score	Get face photo score
POST	/v1.0/hotel/pms/face/picture	Upload face picture at check-in machine
PUT	/v1.0/iot-02/pms/customers	Personnel information push
GET	/v1.0/iot-02/pms/customers	Get personnel information by page

Check in

API Description

When a customer checks in in the PMS system, the check-in information is synchronized to the SaaS platform.

API Address

POST /v1.0/hotel/pms/checkin

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Check-in details	BODY

data description

Parameter	Type	Position	Description	Mandatory
checkin_id	String	BODY	Customer check-in unique ID	Yes
room_no	String	BODY	Room number, maximum length is 10 characters	Yes
building	String	BODY	Building, maximum length is 10 characters	No
floor	String	BODY	Floor, maximum length is 10 characters	No
checkin_time	Long	BODY	Check in time, standard 13-bit timestamp	Yes
checkout_time	Long	BODY	Check out time, standard 13-bit timestamp	Yes
cust_name	String	BODY	Name of room occupant	Yes
gender	String	BODY	Gender of room occupant `0`：Female `1`：Male	Yes
phone_no	String	BODY	Mobile phone number of room occupant	Yes
email	String	BODY	Email address of room occupant	No
id_card_no	String	BODY	Check-in person’s ID number	Yes
id_card_type	String	BODY	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	Yes
face_picture_url	String	BODY	Face photo URL path	No

There may be a batch check-in scenario, and the data may be multiple data pushes in the same message body, so it is an object data. If room_no + floor + building in the data are the same, it means that multiple people live in the same room.
checkin_id is the unique identification of each guest, and the hotel can perform various business operations on the guests through this identification.

Request Example

POST  {url}/v1.0/hotel/pms/checkin

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14136",
            "room_no":"2703",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ"
        },
        {
            "checkin_id":"14137",
            "room_no":"2703",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
 "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Check out

API Description

When a customer checks out in the PMS system, the check-out information is synchronized to the SaaS platform.

API Address

PUT /v1.0/hotel/pms/checkout

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Check out details	BODY

data description

Parameter	Type	Mandatory	Description	Position
checkin_id	String	Yes	Customer check-in unique ID	BODY
departure_time	Long	Yes	Check out time, standard 13-bit timestamp	BODY
id_card_no	String	Yes	Check-in person’s ID number	BODY
id_card_type	String	Yes	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	BODY
phone_no	Long	Yes	User mobile phone number	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

PUT  /v1.0/hotel/pms/checkout

    "hotel_code":"800884",
    "data":[
        {
            "departure_time":1565568000000,
            "checkin_id":"14136",
            "phone_no":"XXXXXXXXXXX",
            "id_card_no":"XXXXXXXXXXX",
            "id_card_type":"SFZ"
        },
        {
            "departure_time":1565568000000,
            "checkin_id":"14137",
            "phone_no":"XXXXXXXXXXX",
            "id_card_no":"XXXXXXXXXXX",
            "id_card_type":"SFZ"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Room change

API Description

When the PMS system has a customer changing rooms, the room changing information will be synchronized to the SaaS platform.

API Address

PUT /v1.0/hotel/pms/change-room

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Room change details	BODY

data description

Parameter	Type	Mandatory	Description	Position
new_checkin_id	String	Yes	Customer check-in new unique ID	BODY
old_checkin_id	String	Yes	Customer check-in old unique ID	BODY
room_no	String	Yes	Room number, maximum length is 10 characters	BODY
building	String	No	Building, maximum length is 10 characters	BODY
floor	String	No	Floor, maximum length is 10 characters	BODY
checkin_time	Long	Yes	Check in time, standard 13-bit timestamp	BODY
checkout_time	Long	Yes	Check out time, standard 13-bit timestamp	BODY
cust_name	String	Yes	Name of room occupant	BODY
gender	Integer	Yes	Gender of room occupant `0`：Female `1`：Male	BODY
phone_no	String	Yes	User mobile phone number	BODY
id_card_no	String	Yes	Check-in person’s ID number	BODY
id_card_type	String	Yes	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	BODY

If checkin_id does not change after changing the room, keep new_checkin_id and old_checkin_id the same.

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

PUT  /v1.0/hotel/pms/change-room

{
    "hotel_code":"800884",
    "data":[
        {
            "new_checkin_id":"14136",
            "old_checkin_id":"14136",
            "room_no":"2705",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxxx",
            "id_card_type":"SFZ"
        },
        {
            "new_checkin_id":"14136",
            "old_checkin_id":"14136",
            "room_no":"2705",
            "checkin_time":1565507286000,
            "checkout_time":1565589600000,
            "gender":1,
            "cust_name":"xxx",
            "phone_no":"xxxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxxx",
            "id_cardt_type":"SFZ"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

 {
     "code":500,
     "msg":"System error, please contact the admin",
     "success":false,
     "t":1561378856383
 }

Extend stay

API Description

When the PMS system has a customer who continues to live, the information on the continued stay will be synchronized to the SaaS platform.

API Address

PUT /v1.0/hotel/pms/renew

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Extend stay details	BODY

data description

Parameter	Type	Mandatory	Description	Position
checkin_id	String	Yes	Customer check-in unique ID	BODY
id_card_no	String	Yes	Check-in person’s ID number	BODY
id_card_type	String	Yes	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	BODY
checkout_time	Long	Yes	Actual departure time, standard 13-digit timestamp	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

PUT /v1.0/hotel/pms/checkout

{
    "hotel_code":"800884",
    "data":[
        {
            "checkout_time":1565568000000,
            "id_card_no":"xxxxx",
            "id_card_type":"SFZ",
            "checkin_id":"14136"
        },
        {
            "checkout_time":1565568000000,
            "id_card_no":"xxxxx",
            "id_card_type":"SFZ",
            "checkin_id":"14137"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Add room occupant

API Description

When a new occupant is added to the room in PMS system, the occupant information will be synchronized to the SaaS platform.

API Address

POST /v1.0/hotel/pms/checkin/guest

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Detailed information of the occupant	BODY

data description

Parameter	Type	Position	Description	Mandatory
checkin_id	String	BODY	Customer check-in unique ID	Yes
room_no	String	BODY	Room number, maximum length is 10 characters	Yes
building	String	BODY	Building, maximum length is 10 characters	No
floor	String	BODY	Floor, maximum length is 10 characters	No
checkin_time	Long	BODY	Check in time, standard 13-bit timestamp	Yes
checkout_time	Long	BODY	Check out time, standard 13-bit timestamp	Yes
cust_name	String	BODY	Name of room occupant	Yes
gender	String	BODY	Gender of room occupant `0`：Female `1`：Male	Yes
phone_no	String	BODY	Mobile phone number of room occupant	Yes
id_card_no	String	BODY	Check-in person’s ID number	Yes
id_card_type	String	BODY	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	Yes
face_picture_url	String	BODY	Face photo URL path	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

POST /v1.0/hotel/pms/checkin/guest

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14138",
            "room_no":"2705",
            "checkin_time":1576055286000,
            "checkout_time":1576216800000,
            "cust_name":"xxx",
            "gender":1,
            "phone_no":"xxxxxxxxxxx",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type": "SFZ"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Modify room occupant

API Description

When the PMS system has customer information modified, the customer information will be synchronized to the SaaS platform.

API Address

PUT /v1.0/hotel/pms/checkin/guest

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Detailed information of the occupant	BODY

data description

Parameter	Type	Mandatory	Description	Position
checkin_id	String	Yes	Customer check-in unique ID	BODY
cust_name	String	Yes	Name of room occupant	BODY
id_card_no	String	Yes	Check-in person’s ID number	BODY
id_card_type	String	Yes	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	BODY
gender	Integer	Yes	Gender of room occupant `0`：Female `1`：Male	BODY
new_phone_no	String	Yes	New mobile phone number of room occupant	BODY
old_phone_no	String	Yes	Old mobile phone number of room occupant	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

PUT {url}/v1.0/hotel/pms/checkin/guest

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14137",
            "cust_name":"xxx",
            "gender":1,
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ",
            "new_phone_no":"xxxxxxxxxxx",
            "old_phone_no":"xxxxxxxxxxx"
        },
        {
            "checkin_id":"14138",
            "cust_name":"xxx",
            "gender":0,
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ",
            "new_phone_no":"xxxxxxxxxxx",
            "old_phone_no":"xxxxxxxxxxx"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Delete room occupant

API Description

When the PMS system deletes the occupant, the information of the deleted occupant will be synchronized to the SaaS platform.

API Address

DELETE /v1.0/hotel/pms/checkin/guest

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
data	Object	Yes	Detailed information of the occupant	BODY

data description

Parameter	Type	Mandatory	Description	Position
checkin_id	String	Yes	Customer check-in unique ID	BODY
id_card_no	String	Yes	Check-in person’s ID number	BODY
id_card_type	String	Yes	Type of license `SFZ`：ID card `WAIGUOREN`：International residence permit `HKMOJUMIN`：Hong Kong, Macao and Taiwan residence permit	BODY
phone_no	String	Yes	Mobile phone number of room occupant	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

DELETE {url}/v1.0/hotel/pms/checkin/guest

{
    "hotel_code":"800884",
    "data":[
        {
            "checkin_id":"14138",
            "id_card_no":"xxxxxxxxxxx",
            "id_card_type":"SFZ",
            "phone_no":"xxxxxxxxxxx"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Add rooms

API Description

When there are new rooms created in the PMS system, the newly added room information will be synchronized to the SaaS platform.

API Address

POST /v1.0/hotel/pms/rooms

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
rooms	Object	Yes	List of room details	BODY

rooms description

Parameter	Type	Mandatory	Description	Position
room_no	String	Yes	Room number, maximum length is 10 characters	BODY
floor	String	Yes	Floor	BODY
building	String	No	Building	BODY
room_name	String	Yes	Room name	BODY
room_type	String	Yes	Room type	BODY
tel	String	Yes	Room telephone	BODY
description	String	No	Room description	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

POST {url}/v1.0/hotel/pms/rooms

{
    "hotel_code":"800884",
    "rooms":[
        {
            "room_no":"101",
            "room_name":"London",
            "room_type":"Boutique Duplex Suite",
            "tel":"020-8734124",
            "floor":"5",
            "description":"Boutique duplex suites to meet the needs of family travel"
        },
        {
            "room_no":"102",
            "room_name":"Los Angeles",
            "room_type":"Boutique Presidential Suite",
            "tel":"020-8734125",
            "floor":"6",
            "description":"The boutique presidential suite meets high-end business trips"
        },
        {
            "room_no":"103",
            "room_name":"Malaysia",
            "room_type":"Boutique Suite",
            "tel":"020-8734126",
            "floor":"3",
            "description":""
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "success":true,
    "t":1566053034624,
}

Delete rooms

API Description

When the PMS system deletes a room, the deleted room information will be synchronized to the SaaS platform.

API Address

DELETE /v2.0/hotel/pms/rooms

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
rooms	Arrays	Yes	Room list	BODY

rooms description

Parameter	Type	Mandatory	Description	Position
room_no	String	Yes	Room number, maximum length is 10 characters	BODY
floor	String	No	Floor	BODY
building	String	No	Building	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

DELETE {url}/v2.0/hotel/pms/rooms

{
    "hotel_code":"800884",
    "rooms": [{"room_no":"101","floor":"1","building":"1"}]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Synchronization of all room information

API Description

Synchronization of PMS room information, including operations such as adding, editing, and deleting rooms. If the PMS already has room data, it will compare the previous room data. If the room number exists, modify it, if the room number does not exist, add it, if the old room number exists and the synchronized data does not exist, delete it. If there is no room data before, add room data.

API Address

POST /v1.0/hotel/pms/rooms/sync

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	BODY
rooms	Object	Yes	List of room details	BODY

rooms description

Parameter	Type	Mandatory	Description	Position
room_no	String	Yes	Room number, maximum length is 10 characters	BODY
old_room_no	String	No	Old room number	BODY
room_name	String	Yes	Room name	BODY
room_type	String	Yes	Room type	BODY
tel	String	Yes	Room telephone	BODY
floor	String	Yes	Floor	BODY
description	String	No	Room description	BODY

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result object

Request Example

POST /v1.0/hotel/pms/rooms/sync

{
    "hotel_code":"800884",
    "rooms":[
        {
            "room_no":"101",
            "room_name":"London",
            "room_type":"Boutique Duplex Suite",
            "tel":"020-8734181",
            "floor":"8",
            "description":"Boutique duplex suites to meet the needs of family travel"
        },
        {
            "room_no":"8803",
            "old_room_no":"8802",
            "room_name":"London",
            "room_type":"Boutique Duplex Suite",
            "tel":"020-8734182",
            "floor":"8",
            "description":"Boutique duplex suites to meet the needs of family travel"
        },
        {
            "room_no":"1011",
            "room_name":"London",
            "room_type":"Boutique Duplex Suite",
            "tel":"020-8734121",
            "floor":"10",
            "description":"Boutique duplex suites to meet the needs of family travel"
        },
        {
            "room_no":"1012",
            "room_name":"London",
            "room_type":"Boutique Duplex Suite",
            "tel":"020-8734122",
            "floor":"10",
            "description":"Boutique duplex suites to meet the needs of family travel"
        }
    ]
}

Success Response Example

{
  "success": true,
  "result": true,
  "t": 1566053034624
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Get face photo score

API Description

Get the face photo score according to the face photo path.

API Address

GET /v1.0/hotel/pms/face/picture/score

Request Parameters

Parameter	Type	Mandatory	Description	Position
hotel_code	String	Yes	The unique code of the hotel/property in PMS system	URL
face_picture_url	String	No	Face photo URL path	URL
face_picture_id	String	No	Face photo ID	URL

faca_picture_url and face_picture_id must upload one.
face_picture_url and face_picture_id are optional. face_picture_url is the face photo URL provided by the manufacturer, and face_picture_id is the file ID returned by the Tuya file system.

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result set

result description

Parameter	Type	Description
score	Integer	Photo score
pass	Boolean	whether to pass

Request Example

GET {url}/v1.0/pms/face/picture/score?hotel_code=800884&face_picture_url=http://www.xxx.com/picture.jpeg

Success Response Example

{
    "success":true,
    "result": {
        "score":80,
        "pass":true
    }
    "t":1566053034624,
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Upload face picture at check-in machine

API Description

The check-in machine transmits the face photo path.

API Address

POST /v1.0/hotel/pms/face/picture

Request Parameters

Parameter	Type	Mandatory	Description	Position
sn	String	Yes	Check-in machine unique code	BODY
brand_code	String	No	Tuya provides brand coding	BODY
checkin_id	String	No	Check-in ID	BODY
face_picture_url	String	Yes	Face photo URL path	BODY
phone_no	String	No	Phone number	BODY
room_no	String	No	Room number	BODY

face_picture_url is the face photo URL provided by the manufacturer

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result set

Request Example

POST {url}/v1.0/hotel/pms/face/picture

{
    "sn": "6F192029B4106EE7",
    "brand_code": "fdddstewqt",
    "checkin_id": "11125533",
    "face_picture_url": "http://test.jpg",
    "phone_no": "86-13544029100",
    "room_no": "101"
}

Success Response Example

{
    "success":true,
    "result":true,
    "t":1566053034624,
}

Failure Response Example

{
    "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Personnel information push

API Description

The PMS system synchronizes personnel information to the SaaS platform.

API Address

PUT /v1.0/iot-02/pms/customers

Request Parameters

Parameter	Type	Position	Description	Mandatory
hotel_code	String	BODY	Tuya provides the unique identification of the hotel/property	Yes
data	Object[]	BODY	Synchronized people list	Yes

data description

Parameter	Type	Position	Description	Mandatory
usename	String	BODY	Username, unique within the merchant, as the basis for updating data	Yes
cust_name	String	BODY	Name of room occupant	Yes
gender	Integer	BODY	Gender of room occupant `0`：Female `1`：Male	No
id_card_type	String	BODY	Type of license`SFZ`：ID card	No
id_card_no	String	BODY	ID number	No
phone_no	String	BODY	Phone number	No
country_code	String	BODY	Country code, such as 86 for China	No
address	String	BODY	Address	No
emergency_contact_name	String	BODY	Emergency contact	No
emergency_contact_phone_no	String	BODY	Emergency phone number	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Exception information, empty if success
result	Boolean	Result set

result description

Parameter	Type	Description
username	String	Username
customer_id	String	User ID assigned by Tuya

Request Example

POST  {url}/v1.0/iot-02/pms/customers

{
    "hotel_code":"xxxxx",
    "data":[
        {
            "usename":"xxxxxxx",
            "cust_name":"xxxxxxx",
            "gender":1,
            "id_card_type":"SFZ",
            "id_card_no":"xxxxxxx",
            "phone_no":"xxxxxxx",
            "country_code":"86",
            "address":"xxxxxxx",
            "emergency_contact_name":"xxxxxxx",
            "emergency_contact_phone_no":"xxxxxxx"
        }
    ]
}

Success Response Example

{
 "success":true,
    "result":[
        {
            "username":"xxx",
            "customer_id":"121212121212"
        }
    ],
    "t":1566053034624
}

Failure Response Example

{
 "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

After reporting the personnel to Tuya, Tuya will assign a unique identifier customer_id to the user, and the interface caller can store the customer_id for subsequent association when receiving messages from Tuya. If the returned customer_id is empty, it means the save failed.
The username field can be a mobile phone number, email address, student number, etc., as long as it can be used as the unique identifier of the user in the merchant system. The string is composed of numbers, letters, dashes, @ and other characters, and the character length is 5-32 characters.

Get personnel information by page

API Description

The PMS system obtains the synchronized personnel information from the SaaS platform page.

API Address

GET /v1.0/iot-02/pms/customers

Request Parameters

Parameter	Type	Position	Description	Mandatory
hotel_code	String	URL	Tuya provides the unique identification of the hotel/property	Yes
page_no	Integer	URL	Page number, the value must be greater than `0`, and the default is `1`	No
page_size	Integer	URL	Number of pages. Value range: 0 < `page_size` < 100, default 20	No

Response Parameters

Parameter	Type	Description
code	Integer	Response code, empty if success
success	Boolean	whether succeed `true`：success `false`：fail
msg	String	Request failed information, empty if success
t	Long	Returns a 13-digit timestamp
result	Object	Return result

result description

Parameter	Type	Description
total	Integer	Total number
page_no	Integer	Page number
page_size	Integer	Number of pages
customers	Array	People Gathering

customers description

Parameter	Type	Description
usename	String	Username, unique within the merchant, as the basis for updating data
cust_name	String	Name of room occupant
gender	Integer	Gender of room occupant `0`：Female `1`：Male
id_card_type	String	Type of license`SFZ`：ID card
id_card_no	String	ID number
phone_no	String	Phone number
country_code	String	BODY
address	String	BODY
emergency_contact_name	String	BODY
emergency_contact_phone_no	String	BODY

Request Example

GET  {url}/v1.0/iot-02/pms/customers?hotel_code=XXX&page_no=1&page_size=20

Success Response Example

{
    "success":true,
    "result":{
        "total":1,
        "page_no":1,
        "page_size":20,
        "customers":[
            {
                "customer_id":"xxxxxxx",
                "usename":"xxxxxxx",
                "cust_name":"xxxxxxx",
                "gender":"xxxxxxx",
                "id_card_type":"SFZ",
                "id_card_no":"xxxxxxx",
                "phone_no":"xxxxxxx",
                "country_code":"86",
                "address":"xxxxxxx",
                "emergency_contact_name":"xxxxxxx",
                "emergency_contact_phone_no":"xxxxxxx"
            }
        ]
    },
    "t":1566053034624
}

Failure Response Example

{
 "code":500,
    "msg":"System error, please contact the admin",
    "success":false,
    "t":1561378856383
}

Appendix

Joint debugging environment

Prev DocPMS Access

Next DocPreparation