Manage Persons

This topic describes the API operations used to manage persons.

Request method	API	Description
GET	/v1.0/iot-02/building/personnel	Get a list of persons
POST	/v1.0/iot-02/building/personnel	Add a person
PUT	/v1.0/iot-02/building/personnel	Edit a person
GET	/v1.0/iot-02/building/personnel/{person_id}/actions/detail	Get the details of the specified person
PUT	/v1.0/iot-02/building/personnel/actions/disable	Disable a person or multiple persons
DELETE	/v1.0/iot-02/building/personnel/actions/delete	Delete one or more persons
GET	/v1.0/iot-02/building/personnel/recycle-list	Get a list of deleted persons
GET	/v1.0/iot-02/building/personnel/{person_id}/recycle-detail	Get the details of deleted persons
PUT	/v1.0/iot-02/building/personnel/actions/recover	Recover one or more persons

Get a list of persons

Functional description

Get a list of persons.

API endpoint

GET /v1.0/iot-02/building/personnel

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
structureId	String	body	The ID of the target organization.	false
searchType	int	body	The query type. Valid values: 1: Only query persons directly associated with the specified structureId. 2: Query persons associated with the specified structureId and all the subordinate organizations. Default value.	false
name	String	body	The name.	false
enabled	int	body	Indicates whether to enable a person. Valid values: 1: Enable the specified person. Default value: 1. 2: Disable the specified person.	false
sex	int	body	The gender.	false
mobile	String	body	The mobile phone number.	false
email	String	body	The email address.	false
certType	String	body	The certificate type.	false
certNo	String	body	The certificate number.	false
feature	String	body	The biometrics.	false
personCode	String	body	The work number of the specified person.	false
page	int	body	The current page number.	false
pageSize	int	body	The number of items to be returned per page.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

{
  "total": "int",
  "list": [
    {
      "personId": "String // The ID of the specified person",
      "name": "String // The name",
      "enabled": "int // Indicates whether to enable a person",
      "sex": "int // The code of the gender",
      "sexStr": "String // The value of the gender",
      "mobileCountry": "String // The country code",
      "mobile": "String // The mobile phone number",
      "certArea": "String // The area to which the certificate belongs",
      "certType": "String // The code of the certificate type",
      "certTypeStr": "String // The value of the certificate type",
      "certNo": "String // The certificate number",
      "feature": "String // The biometrics",
      "imageUrl": "String // The URL of the specified image",
      "imagePath": "String // The path of the specified image",
      "checked": "boolean // Indicates whether the image is detected",
      "imageRating": "float // The score of an image, which is required for a face image",
      "pass": "boolean // Indicates whether the face image is qualified",
      "personCode": "String // The work number",
      "structureIds": "String[] // The ID of the specified organization",
      "structureNames": "String[] // The organization name",
      "structureName": "String // The organization name (It is used to export the field mappings)",
      "structureSnapshots": "String[] // The snapshot"
    }
  ]
}

Sample request

{
    "projectId":"1424615984265764***"
}

Sample response

{
    "result": {
        "has_more": true,
        "list": [
            {
                "cert_area": "",
                "cert_no": "",
                "cert_type": "_",
                "cert_type_str": "",
                "enabled": 1,
                "image_path": "saas/building/building_faceImg/166254529797b6a44bfdc.jpg",
                "image_rating": 0,
                "mobile": "199****9879",
                "mobile_country": "+86",
                "name": "newpeople",
                "person_code": "456",
                "person_id": "1567428253323362***",
                "sex": 1,
                "sex_str": "Male",
                "structure_ids": [
                    "1466612511766855***"
                ],
                "structure_name": "Root Organization 66678\\ Access Permission Test",
                "structure_names": [
                    "Root Organization 66678\\ Access Permission Test",
                ],
                "structure_snapshots": [
                    ""
                ]
            }
        ],
        "total": 83
    },
    "success": true,
    "t": 1662709749871,
    "tid": "e36a959a301311edaf4dfa23c521f7ba"
}

Add a person

Functional description

Add a person.

API endpoint

POST /v1.0/iot-02/building/personnel

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
personId	String	body	The person ID.	false
structureId	String	body	The ID of the target organization.	false
name	String	body	The name.	false
enabled	int	body	Indicates whether a person is enabled.	false
sex	int	body	The gender. Valid values: 0: unknown 1: male 2: female	false
mobileCountry	String	body	The country code.	false
mobile	String	body	The mobile phone number.	false
email	String	body	The email address.	false
certArea	String	body	The area to which the certificate belongs.	false
certType	String	body	The certificate type.	false
certNo	String	body	The certificate number.	false
imagePath	String	body	The path of a face image.	false
imageRating	float	body	The score of an image.	false
personCode	String	body	The work number of the specified person.	false
uploadType	String	body	The upload type.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
    "projectId":"1424615984265764**",
    "name": "OpenAPI Test 3",
    "sex":1,
    "structureId":"1563057531880804***",
    "mobile":"18858286***",
    "mobileCountry":"+86",
    "certNo":"330483199608241***",
    "certType":"ID_CARD_CN",
    "certArea":"CN"
}

Sample response

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

Edit a person

Functional description

Edit a person.

API endpoint

PUT /v1.0/iot-02/building/personnel

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
personId	String	body	The person ID.	false
structureId	String	body	The ID of the target organization.	false
originStructureId	String	body	The ID of the original organization.	false
name	String	body	The name.	false
enabled	int	body	Indicates whether a person is enabled.	false
sex	int	body	The gender. Valid values: 0: unknown 1: male 2: female	false
mobileCountry	String	body	The country code.	false
mobile	String	body	The mobile phone number.	false
email	String	body	The email address.	false
certArea	String	body	The area to which the certificate belongs.	false
certType	String	body	The certificate type.	false
certNo	String	body	The certificate number.	false
imagePath	String	body	The path of a face image.	false
imageRating	float	body	The score of an image.	false
personCode	String	body	The work number of the specified person.	false
uploadType	String	body	The upload type.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
    "projectId":"1424615984265764***",
    "name":"Test 2",
    "sex":2,
    "structureId":"1439128403298041***",
    "mobile":"18858286***",
    "mobileCountry":"+86",
    "certNo":"330483199608240***",
    "certType":"ID_CARD_CN",
    "certArea":"CN"
}

Sample response

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

Get the details of the specified person

Functional description

Get the details of the specified person.

API endpoint

GET /v1.0/iot-02/building/personnel/{person_id}/actions/detail

Request parameters

Parameter	Type	Parameter type	Description	Required
personId	String	body	The person ID.	false
projectId	String	body	The project ID.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

The same as the API of getting a list of persons.

Sample request

{
    "projectId":"1424615984265764***",
    "personId":"1563051208690630***"
}

Sample response

The same as the API of getting a list of persons.

Disable a person or multiple persons

Functional description

Disable a person or multiple persons.

API endpoint

PUT /v1.0/iot-02/building/personnel/actions/disable

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
personIdList	String[]	body	The list of person IDs.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
    "projectId":"1424615984265764***",
    "personId":"1562778729048965***"
}

Sample response

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

Delete one or more persons

Functional description

Delete one or more persons.

API endpoint

DELETE /v1.0/iot-02/building/personnel/actions/delete

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
personId	String	body	The person ID.	false
personIdList	String[]	body	The list of person IDs.	false
targetStructureId	String	body	The ID of the target organization.	false
originStructureId	String	body	The ID of the original organization.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
  "personIdList": "The list of person IDs",
  "originStructureId": "The ID of the original organization",
  "personId": "The person ID",
  "projectId": "The project ID",
  "targetStructureId": "The ID of the target organization"
}

Sample response

boolean{}

Get the details of deleted persons

Functional description

Get the details of deleted persons.

API endpoint

GET /v1.0/iot-02/building/personnel/{person_id}/recycle-detail

Request parameters

Parameter	Type	Parameter type	Description	Required
personId	String	body	The person ID.	false
projectId	String	body	The project ID.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

The same as the API of getting a list of persons.

Sample request

{
  "personId": "The person ID",
}

Sample response

The same as the API of getting a list of persons.

Get a list of deleted persons

Functional description

Get a list of deleted persons.

API endpoint

GET /v1.0/iot-02/building/personnel/recycle-list

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
structureId	String	body	The ID of the target organization.	false
structureSnapshotName	String	body	The name of a snapshot of the specified organization.	false
searchType	int	body	The query type. Valid values: 1: Only query persons directly associated with the specified structureId. 2: Query persons associated with the specified structureId and all the subordinate organizations. Default value.	false
name	String	body	The name.	false
enabled	int	body	Indicates whether to enable it. Valid values: 1: Enable. Default value: 1. 2: Disable.	false
sex	int	body	The gender.	false
mobile	String	body	The mobile phone number.	false
email	String	body	The email address.	false
certType	String	body	The certificate type.	false
certNo	String	body	The certificate number.	false
feature	String	body	The biometrics.	false
personCode	String	body	The work number of the specified person.	false
page	int	body	The current page number.	false
pageSize	int	body	The number of items to be returned per page.	false
isExportQuery	boolean	body	Specifies whether to export the query results. Default value: false.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

The same as the API of getting a list of persons.

Sample request

The same as the API of getting a list of persons.

Sample response

{
  "total": "int",
  "list": [
    {
      "list": "Snapshot"
    }
  ],
  "hasMore": "boolean"
}

Recover one or more persons

Functional description

Recover one or more persons.

API endpoint

PUT /v1.0/iot-02/building/personnel/actions/recover

Request parameters

Parameter	Type	Parameter type	Description	Required
projectId	String	body	The project ID.	false
personId	String	body	The person ID.	false
personIdList	String[]	body	The list of person IDs.	false
targetStructureId	String	body	The ID of the target organization.	false
originStructureId	String	body	The ID of the original organization.	false

Return parameters

Parameter	Type	Description
code	Integer	The response code. For more information, see the error code section. It is empty if the request is successful.
success	Boolean	Indicates whether the operation is successful. Valid values: true: succeeded. false: failed.
msg	String	The message that is returned if the request failed. The response is empty if the request is successful.
t	Long	The returned 13-digit timestamp.
result	Object	The returned result.

Description of result

boolean{}

Sample request

{
  "personIdList": "The list of person IDs",
  "originStructureId": "The ID of the original organization",
  "personId": "The person ID",
  "projectId": "The project ID",
  "targetStructureId": "The ID of the target organization"
}

Sample response

boolean{}

Error code

The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

Error code	Description
500	A system error has occurred while processing your request.