Tencent Palm Server-Side API Reference

This document applies to both the Max and Standard versions; the interface content is identical.

Version History

Version	Release Date	Changes
v2.5.0	2026-09-22	New APIs • Added the DescribeDeviceEmergencyStatus (Query Device Emergency Status) API, which returns the emergency status of the current tenant and of each device • Added the SendEmergencyCommand (Send Emergency Control Command) API, which supports issuing block (block all) / open (open all) / reset_block (restore block all) / reset_open (restore open all) commands to all devices or to a specified SN list API parameter changes • The LoginPalmMaSmsCode API response adds the CheckError (verification error) and UserIdList (list of user IDs, returned only when GrantType is client_credential_user) fields New enums and data structures • Added the EmergencyStatus enum (emergency status, int32 serialization) • Added the EmergencyCommandScope enum (emergency command scope, int32 serialization) • Added the SendEmergencyCommandRequestEmergencyCommandType enum (embedded in SendEmergencyCommandRequest, emergency command type: block all/open all/restore block all/restore open all, int32 serialization) • Added the LoginPalmMaSmsCodeResponseCheckError enum (login verification error) • Added the DescribeDeviceEmergencyStatusResponseDeviceEmergencyStatus and SendEmergencyCommandResponseFailedDevice data structures
v2.4.0	2026-08-12	New APIs • Added the RegisterPalm (Register Palm Print) API, which uploads a palm image to create a palm print and bind it to a specified user, with two-factor authentication API parameter changes • The IrImage parameter description of the CreatePalm API changed from "infrared image data" to "IR image data" • The IrImage parameter description of the SearchMobilePalm API changed from "infrared image data" to "IR image data" • In the CreateUser and ModifyUser APIs, the CustomFieldValue parameter is deprecated and replaced by the new CustomFieldValueList parameter (Array of CustomFieldValueItem), supporting multiple custom additional verification field configurations • In the DescribeUser API response, the CustomFieldValue field is deprecated and replaced by the new CustomFieldValues field (Array of CustomFieldValueItem) • The DescribeUserList API adds the SkipTotalCount (skip total count) and SceneId (scene ID filter) input parameters, and the response adds the HasMore field • The DescribeVerificationRecordList API adds the Source (verification record source filter) and SkipTotalCount (skip total count) input parameters, the response adds the HasMore field, and the VerificationRecord structure adds the Source, AccessDenied (verification result), and Reason (verification description) fields • The CreateVerificationRecord API adds the Source (verification record source), AccessDenied (verification result), and Reason (verification description) input parameters • The DescribeVerificationRecord push content adds the AccessDenied (verification result) and Reason (verification description) fields New enums and data structures • Added the HighSimilarityResolutionStrategy enum (policy for handling high-similarity users detected during palm registration: reject_with_error/reject_with_similar_users) • Added the RegisterPalmResponseCheckError enum (registration check error code: high_similarity_detected) • Added the VerificationRecordSource enum (verification record source: device/mobile/server/h5/wechat); the enum value web is renamed to h5 and weixin is renamed to wechat, with descriptions streamlined • Added the CustomFieldValueItem common data structure (custom additional verification field value item)
v2.3.0	2026-07-13	New APIs • Added the DescribeUserAccessScope (Query User Access Scope) and DescribeUserAccessScopeSummary (Query User Access Scope Summary) APIs • Added the DescribeUserTagTree (Query User Tag Tree Structure) API API availability • The SendPalmMaSmsCode (Send SMS Verification Code) and LoginPalmMaSmsCode (SMS Verification Code Login) APIs changed from internal to publicly available, and a new "PalmMa Login APIs" category was added • The CreateQrCodeScanSession (Create QR Code Palm Registration Session) and DescribeQrCodeScanSession (Query QR Code Palm Registration Session Status) APIs changed from internal to publicly available API parameter changes • The LoginPalmMaSmsCode API adds the PhoneNo (phone number verification) and GrantType (Grant Type) parameters; SmsCode and SessionId are now optional • The DescribeQrCodeScanSession API response adds the PhoneNo (phone number) field • The DescribeQrCodeScanUser API response adds the PhoneNo (phone number) field • The DescribeUserTag API response adds the ParentTagId (parent tag ID), Level (hierarchy depth), ChildrenCount (number of direct child tags), UserCount (number of users associated with the tag), and PathNodes (hierarchy path) fields • In the DescribeUserTagList API response, UserTagItem adds the ParentTagId, Level, ChildrenCount, and PathNodes fields New enums and data structures • Added the GrantType enum (Grant Type: client_credential_user/client_credential) • Added the UserTagNode common data structure (tag hierarchy path node) • Added the UserTag common data structure (user tag information, including the PathNodes hierarchy path) • Added the UserTagTreeNode common data structure (tag tree node) • Added the AccessScopeItem, AccessScopeSummary, and VerifyRuleInfo common data structures • Added the error code FailedOperation.PhoneNoAlreadyExists (1113, phone number already exists) • The serialization of the DeviceStatus enum changed from string to integer (int32)
v2.2.0	2026-06-17	Version number upgrade; no API changes
v2.1.0	2026-05-07	New APIs • Added 6 list query APIs: DescribeUserList (Query User Information List), DescribeUserTagList (Query User Tag List), DescribeDeviceList (Query Device List), DescribeSceneList (Query Scene List), DescribeSceneGroupList (Query Scene Group List), and DescribeVerifyRuleList (Query Verification Rule List) API parameter changes • The CreateUser and ModifyUser APIs add the CustomFieldValue parameter (custom additional verification field value) • The DescribeUser API response adds the CustomFieldValue field • The DescribeUserList API adds the PhoneNo, PhysicalCardNo, and UserTagId filter parameters, and the response adds the CreatedTime and UpdatedTime fields • The DescribeDeviceList API is publicly available, adds the Status, SceneId, and DeviceType filter parameters, and the response adds the Status, SceneId, SceneName, CreatedTime, and UpdatedTime fields • The DescribeVerificationRecordList API adds the SceneGroupIds, SceneGroupName, and OrderBy parameters, and the response adds the SceneGroupId and SceneGroupName fields • The NotifyQrCodeScanEvent API adds the EventType parameter (QR code scan event type) • In the Verify API, the type of the VerifyResult parameter changed from Integer to the VerifyResult enum (values: 1: success, 2: failure), clarifying the valid Value Range (semantics unchanged; existing callers passing 1/2 remain fully compatible) New enums and data structures • Added the DeviceStatus enum (device status: online/offline) • Added the AdditionalVerifyMethod enum (additional verification method: phone_no/custom_field/qr_code) • Added the VerificationRecordOrderField enum (verification record sorting field) • Added the SortOrder enum (sort order: asc/desc) • Added the QrCodeScanEventType enum (QR code scan event type, used as the value of NotifyQrCodeScanEvent.EventType) • Added the VerifyResult enum (additional verification result, used as the value of the Verify API's VerifyResult parameter) • Added the OrderBy common data structure (sorting condition)
v2.0.0	2026-04-03	• Added palm print management APIs (8 APIs: CreatePalm, BindPalm, SearchMobilePalm, Verify, DeletePalm, DescribePalm, SynchronizePalmFeature, DescribeVersionList) • Added the authentication management API DescribePalmLicense (Query Authorization Information) • The DescribeUser API output parameters add the UserState (user state) field • The DescribeUserPalm API output parameters add the UserName (user name), UserState (user state), PalmDirection (primary palm direction), LeftPalm (left palm registration information), and RightPalm (right palm registration information) fields • The DescribeQrCodeScanUser API output parameters add the UserName (user name), UserState (user state), PalmDirection (primary palm direction), LeftPalm (left palm registration information), and RightPalm (right palm registration information) fields • The PalmState enum adds the abnormal (abnormal) enum value • Added the UserState enum type • Added the Image, Pointf, Feature, VerifyInfo, PalmFeatureDetail, and ProductVersionInfo common business data structures • Added the ImageType, PalmPaasPalmDirection, FeatureType, PalmStatus, PalmPaasOperation, HasMoreType, AlgorithmStrategy, and VerifyType enum types
v1.8.1	2026-03-05	• The DescribeUser API output parameters add the PalmDirection (palm direction), LeftPalm (left palm registration information), RightPalm (right palm registration information), and CreateTime (user creation time) fields • Added the PalmInfo common business data structure (single palm registration information)
v1.8.0	2026-02-02	• Scene management adds the DescribeScene (Query Scene Details) API • Device management adds the DescribeDevice (Query Device Details) API • The CreateScene API adds the SceneId (optional) and ScenarioStrategy (required) parameters • The ModifyScene API adds the ScenarioStrategy (required) parameter • Added the ScenarioStrategy, RegisterType, and PalmDirection enum types • Added 5 Business error codes (InvalidUserId, RegisterTypeNotAllowed, and Member-related error codes)
v1.7.1	2026-01-20	• The EnableWebhookRule parameter of the CreateVerifyRule API changed to optional; it defaults to true when not provided
v1.7.0	2026-01-05	• Added user tag management (4 APIs: CreateUserTag, ModifyUserTag, DeleteUserTag, DescribeUserTag) • User management APIs support tag binding and partial failure (CreateUser and ModifyUser support the UserTagIdList and PartialFailure parameters) • Added complete documentation for the partial failure mechanism • Unified API naming conventions (API tables use Action names) • Added 14 Business error codes (user tag, pagination, session, and tenant related) • Optimized the format of 4 error codes and removed 39 deprecated error codes

Introduction

Overview

Tencent Palm (PalmAI) leverages Tencent's years of in-depth accumulation in computer vision and biometric identification technology, opening its three core capabilities of palm registration, palm print recognition, and palm print verification to enterprises and developers through Tencent Cloud services. It is committed to helping customers quickly build secure, convenient, and efficient palm print recognition solutions.

The Tencent Palm APIs described in this document are all Tencent Cloud API 3.0 APIs. You can call these APIs to perform operations on the Tencent Palm service, such as user management, palm registration and verification, device management, and scene configuration. For all APIs supported by Tencent Palm, see API Overview.

Glossary

Common terms used in Tencent Palm APIs are listed in the table below:

Term	Description
AppId	Unique application identifier used by the Tencent Cloud backend to distinguish between different Palm applications. It is generated automatically when a tenant is created in the Palm console. Data is not shared between different AppIds
RGB	Color image.
IR	Infrared image.
Three points	Data output after image detection and alignment.
Feature value	Data output after an image is input to the recognition model.
Palm Print Search Hot Library	A high-performance data structure loaded in GPU memory or RAM to improve search matching efficiency. Data in the system is divided into hot-library search data stored in GPU memory or RAM, and general stored data (including ordinary databases, object storage, file storage, etc.).
Device type	Model identifier of the palm verification device. Current Value Range: M3, M3B, M4, O1, O2.
Module type	Model identifier of the recognition module used by the palm verification device. Current Value Range: A3, A3B.

API Overview

The Palm API follows the Tencent Cloud API 3.0 specification and provides management capabilities such as authentication, palm print management, users, user palms, devices, scenes, verification records, verification rules, and QR code palm registration.

Function Classification

• Authentication Management APIs
• User Management APIs
• User Tag Management APIs
• User Palm Management APIs
• Device Management APIs
• Scene Management APIs
• Verification Record APIs
• Verification Rule APIs
• QR Code Palm Registration APIs
• PalmMa Login APIs
• Palm Print Management APIs (Palm Algorithm Platform)

Authentication Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateAccessToken	Obtain Access Credentials	20
DescribePalmLicense	Query Authorization Information	20

User Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateUser	Create User	20
ModifyUser	Modify User	20
DeleteUser	Delete User	20
DescribeUser	Query User	20
DescribeUserList	Query User Information List	20
DescribeUserAccessScope	Query User Access Scope	20
DescribeUserAccessScopeSummary	Query User Access Scope Summary	20

User Tag Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateUserTag	Create User Tag	20
ModifyUserTag	Modify User Tag	20
DeleteUserTag	Delete User Tag	20
DescribeUserTag	Query User Tag	20
DescribeUserTagList	Query User Tag List	20
DescribeUserTagTree	Query User Tag Tree Structure	20

User Palm Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
DeleteUserPalm	Delete User Palm Information	20
DescribeUserPalm	Query User Palm Information	20

Device Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateDevice	Create Device	20
ModifyDevice	Modify Device	20
DeleteDevice	Delete Device	20
DescribeDevice	Query Device Details	20
DescribeDeviceList	Query Device List	20
DescribeDeviceEmergencyStatus	Query Device Emergency Status	20
SendEmergencyCommand	Send Emergency Control Command	20

Scene Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateScene	Create Scene	20
ModifyScene	Modify Scene	20
DeleteScene	Delete Scene	20
DescribeScene	Query Scene Details	20
DescribeSceneList	Query Scene List	20
CreateSceneGroup	Create Scene Group	20
ModifySceneGroup	Modify Scene Group	20
DeleteSceneGroup	Delete Scene Group	20
DescribeSceneGroupList	Query Scene Group List	20

Verification Record APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateVerificationRecord	Create Verification Record	20
DescribeVerificationRecordList	Query Verification Record List	20
DescribeVerificationRecord	Query Verification Record (Push Only)	20

Verification Rule APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateVerifyRule	Create Verification Rule	20
ModifyVerifyRule	Modify Verification Rule	20
DeleteVerifyRule	Delete Verification Rule	20
DescribeVerifyRule	Query Verification Rule	20
DescribeVerifyRuleList	Query Verification Rule List	20
CheckAccessPermission	Check Access Permission (callback only)	20

QR Code Palm Registration APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateQrCodeScanSession	Create QR Code Palm Registration Session	20
NotifyQrCodeScanEvent	QR Code Scan Event Notification	20
BindQrCodeScanPalm	QR Code Palm Print Binding	20
DescribeQrCodeScanSession	Query QR Code Palm Registration Session Status	20
DescribeQrCodeScanUser	Query QR Code Palm Registration User Information	20

PalmMa Login APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
SendPalmMaSmsCode	Send SMS Verification Code	20
LoginPalmMaSmsCode	SMS Verification Code Login	20

Palm Print Management APIs (Palm Algorithm Platform)

Interface name	Interface function	Frequency limit (times/second/AppId)
CreatePalm	Create Palm Print	20
BindPalm	Bind Palm Print	20
RegisterPalm	Register Palm Print	20
SearchMobilePalm	Mobile Palm Registration Search	20
Verify	User Additional Verification	20
DeletePalm	Delete Palm Print	20
DescribePalm	Query Palm Print	20
SynchronizePalmFeature	Synchronize Palm Print Features	20
DescribeVersionList	Query Product Version List	20

---

How to Call

Basic Calling Flow

The following flowchart illustrates the basic steps for calling the Palm API:

Description of the two authentication methods:

Authentication method	Applicable scenarios	Request headers
Signature + Token	Most management APIs (users, devices, scenes, palm prints, etc.)	Authorization + X-Palm-Openapi-Token
Token only	QR Code Palm Registration APIs (NotifyQrCodeScanEvent, BindQrCodeScanPalm, DescribeQrCodeScanSession, DescribeQrCodeScanUser)	X-Palm-Openapi-Token only; no Authorization required

Note:

1. Before calling any API, you must first obtain an AccessToken through CreateAccessToken (this API itself uses signature authentication).
2. Signature-authenticated APIs carry both Authorization (signature) and X-Palm-Openapi-Token (Token) in the request headers.
3. Token-only APIs only need to carry X-Palm-Openapi-Token; no signature calculation is required.

Request Structure

The request structure of the Palm API is as follows:

1. Service Endpoint

The API supports access from the nearest region. The following domain is recommended:

• Default access domain (recommended): open.intl.palm.tencent.com (example only; the actual access domain is subject to allocation, and private deployment scenarios are supported)
• Access from a specific region (extensible if multiple regions are deployed): e.g., open.intl.palm.tencent.com (example only; the actual access domain is subject to allocation)

Note: The domain is the access point of the API and does not represent the region where the product or API actually provides services. If multiple regions are deployed in the future, this will be added to the documentation.

2. Communication Protocol

All Palm API interfaces communicate over HTTPS, providing a highly secure communication channel.

3. Request Method

• The POST method is recommended.
• Supported Content-Type:
  • application/json (recommended; signature method v3/TC3-HMAC-SHA256 must be used)
• When signature method v3 is used with the POST method, the request package can be up to 10 MB.

4. Character Encoding

All requests and responses use UTF-8 encoding.

Common Parameters

Common parameters are used to identify the user identity, API signature, and request context. When signature method v3 (TC3-HMAC-SHA256) is used, all common parameters must be placed in the HTTP request headers.

Parameter Name	Type	Required	Description
X-TC-Action	String	Yes	Name of the API to call. Example: CreateUser.
X-TC-Timestamp	Integer	Yes	Current UNIX timestamp in seconds. Example: 1704067200. If it differs from the server time by more than 5 minutes, a signature expiration error will occur.
X-TC-Version	String	Yes	API version, currently fixed at: 2025-07-15.
Authorization	String	Yes	Signature information, format: TC3-HMAC-SHA256 Credential=AKIDxxx/Date/service/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx. For details, see the Signature Method section.
X-TC-Nonce	String	Yes	Random string, generally used to prevent replay attacks. It is recommended to generate a new unique random string for each request.
Content-Type	String	Yes	Request content type; application/json; charset=utf-8 is recommended.
Host	String	Yes	Service endpoint, fixed at open.intl.palm.tencent.com.
X-Palm-AppId	String	Yes	Application ID, obtained when applying for security credentials. The customer needs to apply to Tencent for AppId, SecretId, and SecretKey. Please keep the above information secure and pass it in API requests as needed
X-Palm-Openapi-Token	String	Yes	Temporary security credential Token. Before calling Tencent APIs, you must first obtain an access credential through the [Obtain Access Credentials] API (Action: CreateAccessToken). Note that the access credential is time-sensitive and must be re-obtained after expiration.

Request Header Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

Signature Method

The Palm API uses the Tencent Cloud API 3.0 signature method v3 (TC3-HMAC-SHA256) for identity authentication.

Why Signing Is Required

• To verify the identity of the requester and ensure that the request comes from a user holding a valid key.
• To protect data in transit and prevent requests from being tampered with.

Applying for Security Credentials

The security credentials used in this document are keys, which include a SecretId and a SecretKey.

• SecretId: Identifies the API caller's identity; it can be simply compared to a username.
• SecretKey: Verifies the API caller's identity; it can be simply compared to a password.

Users must keep security credentials strictly confidential and avoid disclosure, otherwise their property security will be at risk. If a credential has been disclosed, disable it immediately.

The steps for applying for security credentials are as follows:

1. Log in to the Tencent Cloud Palm service console.
2. Go to the console page under System Management | Tenant Management.
3. On the Tenant Management page, select the current tenant and click [Details] to view the key pair.

Signature Process (v3)

The API currently only supports POST requests. For the POST method, only Content-Type: application/json is currently supported, and the request body content is data transmitted in JSON format.

The following uses binding a user's palm print as an example to introduce the signature calculation process step by step.

Assume the user's SecretId and SecretKey are AKID******************************** and ******************************** respectively.

The request is as follows:

curl -X POST https://open.intl.palm.tencent.com \
-H "Authorization: TC3-HMAC-SHA256 Credential=AKID********************************/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp, Signature=f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db" \
-H "Content-Type: application/json" \
-H "Host: open.intl.palm.tencent.com" \
-H "X-TC-Action: BindPalm" \
-H "X-TC-Timestamp: 1752587686" \
-H "X-TC-Version: 2025-07-15" \
-H "X-Palm-AppId: 223" \
-H "X-TC-Nonce: c68bf577-60f1-45d8-a9ef-7a0a8c59690f" \
-H "X-Palm-Openapi-Token: **************************************" \
-d '{"PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47","UserId": "Alice","IsForce": true}'

The signature calculation process is explained in detail below.

1. Concatenate the canonical request string

Concatenate the canonical request string (CanonicalRequest) in the following pseudocode format:

CanonicalRequest =
    HTTPRequestMethod + '\n' +
    CanonicalURI + '\n' +
    CanonicalQueryString + '\n' +
    CanonicalHeaders + '\n' +
    SignedHeaders + '\n' +
    HashedRequestPayload

Field	Description
HTTPRequestMethod	HTTP request method (GET, POST). In this example, the value is POST.
CanonicalURI	URI parameter. For API 3.0, it is fixed as a forward slash (/).
CanonicalQueryString	The query string in the URL of the HTTP request. For POST requests, it is fixed as an empty string ""; for GET requests, it is the string after the question mark (?) in the URL, for example: Limit=10&Offset=0. Note: CanonicalQueryString needs to be URLEncoded according to RFC3986, with the UTF-8 character set. It is recommended to use the standard library of the programming language. All special characters must be encoded in uppercase form.
CanonicalHeaders	Header information participating in the signature, including at least the host and content-type headers. Custom headers can also be added to participate in the signature to improve the uniqueness and security of your request. Concatenation rules: 1) Convert both the header key and value to lowercase and trim leading and trailing spaces, then concatenate in the key:value\n format; 2) For multiple headers, concatenate them in ASCII ascending order of the header key (lowercase). The calculated result in this example is: content-type:application/json\nhost:open.intl.palm.tencent.com\nx-palm-appid:223\nx-tc-nonce:c68bf577-60f1-45d8-a9ef-7a0a8c59690f\nx-tc-timestamp:1752587686\n. Note: The content-type must match what is actually sent. Some programming language network libraries automatically add a charset value even if it is not specified. If the signature differs from what is sent, the server will return a signature verification failure.
SignedHeaders	Header information participating in the signature, indicating which headers of this request participated in the signature, corresponding one-to-one with the headers contained in CanonicalHeaders. content-type and host are required headers. Concatenation rules: 1) Convert header keys to lowercase; 2) Concatenate multiple header keys (lowercase) in ASCII ascending order, separated by semicolons (;). In this example: content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp
HashedRequestPayload	The hash value of the request body (Payload, i.e., Body). The pseudocode is Lowercase(HexEncode(Hash.SHA256(RequestPayload))), that is, perform SHA256 hashing on the HTTP request body, then hexadecimal encoding, and finally convert the encoded string to lowercase letters. Note: For GET requests, RequestPayload is fixed as an empty string; for POST requests, RequestPayload is the request body Payload.

According to the above rules, the canonical request string obtained in the example is as follows (for clarity, \n newlines are shown as actual line breaks):

POST
/

content-type:application/json
host:open.intl.palm.tencent.com
x-palm-appid:223
x-tc-nonce:c68bf577-60f1-45d8-a9ef-7a0a8c59690f
x-tc-timestamp:1752587686

content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp
b199b12c8af15dd7543ede5b6343d1abedd85f166b99b8b4b06599f10822b3a2

2. Concatenate the string to sign

Concatenate the string to sign in the following pseudocode format:

StringToSign =
    Algorithm + "\n" +
    RequestTimestamp + "\n" +
    CredentialScope + "\n" +
    HashedCanonicalRequest

Field	Description
Algorithm	Signature algorithm, currently fixed at TC3-HMAC-SHA256.
RequestTimestamp	Request timestamp, i.e., the value of the common parameter X-TC-Timestamp in the request header, which is the current UNIX timestamp accurate to the second. In this example, the value is 1752587686.
CredentialScope	Credential scope, in the format Date/service/tc3_request, containing the date, the requested service, and the termination string (tc3_request). Date is the date in UTC standard time, and its value must be consistent with the UTC standard time date converted from the common parameter X-TC-Timestamp; service is the product name, which must match the called product domain, here palm. The calculated result in this example is: 2025-07-15/palm/tc3_request.
HashedCanonicalRequest	The hash value of the canonical request string concatenated in the previous step. The pseudocode is Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))). The calculated result in this example is 3044b1650deaa09d3d1e93d63c15fd76c7c764254b3a1cba9c6b321eda191774.

⚠️ Note:

1. Date must be calculated from the timestamp X-TC-Timestamp, and the time zone must be UTC+0. If the system's local time zone information is added (for example, UTC+8), calls will succeed during the day and evening but will definitely fail in the early morning. Assume the timestamp is 1551113065; the time in UTC+8 is 2019-02-26 00:44:25, but the Date calculated using the UTC+0 date should be 2019-02-25, not 2019-02-26.
2. Timestamp must be the current system time, and you must ensure that the system time is synchronized with standard time; if they differ by more than five minutes, the call will definitely fail. If the time is not synchronized with standard time for a long period, requests may fail after running for a while, returning a signature expiration error.

According to the above rules, the string to sign obtained in the example is as follows:

TC3-HMAC-SHA256
1752587686
2025-07-15/palm/tc3_request
3044b1650deaa09d3d1e93d63c15fd76c7c764254b3a1cba9c6b321eda191774

3. Calculate the signature

1. Calculate the derived signing key. The pseudocode is as follows:

SecretKey = "********************************"
SecretDate = HMAC_SHA256("TC3" + SecretKey, Date)
SecretService = HMAC_SHA256(SecretDate, Service)
SecretSigning = HMAC_SHA256(SecretService, "tc3_request")

The derived keys SecretDate, SecretService, and SecretSigning are binary data and may contain non-printable characters. Their outputs printed as hexadecimal strings are respectively:
2fbd1f93d8d1aae5c0a4e2df255519752e1e4be521b9edae832930379544679c,
45589385000e5972fe3fb6ca9f07339289dee6e33e0b5bb9022308d69eb15fc9,
a116ccc06739ebac6c1c54514ace4229c98847c5f1ee5abc395eafab262b0246.
Please note that in different programming languages, the parameter order of HMAC library functions may vary; refer to the actual situation. In the pseudocode here, the key parameter comes first and the message parameter data comes second. Standard library functions usually return values in binary format, and may also provide print-friendly hexadecimal return values; the binary format is used here.

Field	Description
SecretKey	The original SecretKey, i.e., ********************************.
Date	The Date field information in Credential. In this example, the value is 2025-07-15.
Service	The Service field information in Credential. In this example, the value is palm.

2. Calculate the signature. The pseudocode is as follows:

Signature = HexEncode(HMAC_SHA256(SecretSigning, StringToSign))

The calculated result in this example is f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db.

4. Concatenate the Authorization

   Concatenate the Authorization in the following format:

   Authorization =
       Algorithm + ' ' +
       'Credential=' + SecretId + '/' + CredentialScope + ', ' +
       'SignedHeaders=' + SignedHeaders + ', ' +
       'Signature=' + Signature

   Field	Description
   Algorithm	Signature method, fixed at TC3-HMAC-SHA256
   SecretId	The SecretId in the key pair, i.e., AKID********************************
   CredentialScope	Credential scope, see above. In this example: 2025-07-15/palm/tc3_request
   SignedHeaders	Header information participating in the signature. In this example, the value is content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp
   Signature	Signature value. The calculated result in this example is f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db

   According to the above rules, the value obtained in the example is:

   Authorization: TC3-HMAC-SHA256 Credential=AKID********************************/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp, Signature=f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db

   The final complete call information is as follows:

   POST https://open.intl.palm.tencent.com/
   Authorization: TC3-HMAC-SHA256 Credential=AKID********************************/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp, Signature=f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db
   Content-Type: application/json
   Host: open.intl.palm.tencent.com
   X-Palm-AppId: 223
   X-TC-Action: BindPalm
   X-TC-Timestamp: 1752587686
   X-TC-Version: 2025-07-15
   X-TC-Nonce: c68bf577-60f1-45d8-a9ef-7a0a8c59690f
   X-Palm-Openapi-Token: **************************************
   {"PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47","UserId": "Alice","IsForce": true}

   ⚠️ Note: The HTTP headers and request body (Payload) sent with the request must be exactly consistent with the content used in the signature calculation process; otherwise, a signature mismatch error will be returned. You can compare and troubleshoot by printing the actual request content or capturing network packets.

Signature Demo (Python)

The following is a complete signature process demo implemented in Python:

def get_openapi_request_header(secret_id, secret_key, access_token, appid, action, nonce, data, svr_version = "standard"):
    version = "2025-07-15"
    timestamp = int(time.time())
    host = "open.intl.palm.tencent.com"
    service = "palm"
    algorithm = "TC3-HMAC-SHA256"
    date = datetime.utcfromtimestamp(timestamp).strftime("%Y-%m-%d")
 
    # ************* 步骤 1：拼接规范请求串 *************
    http_request_method = "POST"
    canonical_uri = "/"
    canonical_querystring = ""
    ct = "application/json"
    payload = json.dumps(data)  ##body
    canonical_headers = "content-type:%s\nhost:%s\nx-palm-appid:%s\nx-tc-nonce:%s\nx-tc-timestamp:%s\n" % (ct, host, str(appid), nonce, str(timestamp))
    signed_headers = "content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp"
    hashed_request_payload = hashlib.sha256(payload.encode("utf-8")).hexdigest()
    canonical_request = (http_request_method + "\n" +
                        canonical_uri + "\n" +
                        canonical_querystring + "\n" +
                        canonical_headers + "\n" +
                        signed_headers + "\n" +
                        hashed_request_payload)
    
    # ************* 步骤 2：拼接待签名字符串 *************
    credential_scope = date + "/" + service + "/" + "tc3_request"
    hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest()
    string_to_sign = (algorithm + "\n" +
                    str(timestamp) + "\n" +
                    credential_scope + "\n" +
                    hashed_canonical_request)
 
    # ************* 步骤 3：计算签名 *************
    # 计算签名摘要函数
    def sign(key, msg):
        return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
    secret_date = sign(("TC3" + secret_key).encode("utf-8"), date)
    secret_service = sign(secret_date, service)
    secret_signing = sign(secret_service, "tc3_request")
    signature = hmac.new(secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
 
    # ************* 步骤 4：拼接 Authorization *************
    authorization = (algorithm + " " +
                    "Credential=" + secret_id + "/" + credential_scope + ", " +
                    "SignedHeaders=" + signed_headers + ", " +
                    "Signature=" + signature)
    print("authorization: {}".format(authorization))
 
    # 公共参数添加到请求头部
    headers = {
        "Authorization": authorization,
        "Host": host,
        "Content-Type": "application/json",
        "X-Palm-AppId": str(appid),
        "X-TC-Action": action,
        "X-TC-Timestamp": str(timestamp),
        "X-TC-Version": version,
        "X-TC-Nonce": nonce,
        "X-Palm-Openapi-Token": access_token
    }
    return headers

Common Signature Failure Error Codes

Error Code	Error Description
AuthFailure.SignatureExpire	Signature expired. The difference between Timestamp and the time when the server receives the request must not exceed five minutes.
AuthFailure.SecretIdNotFound	The key does not exist. Please check in the console whether the key is disabled, or whether characters were missed or added when copying.
AuthFailure.SignatureFailure	Signature error. This may be caused by a signature calculation error, a mismatch between the signature and the actually sent content, or an incorrect SecretKey.
AuthFailure.TokenFailure	Temporary credential Token error.
AuthFailure.InvalidSecretId	Invalid key (not a Cloud API key type).

Return Result

Cloud API 3.0 interfaces return JSON data by default. Interfaces that return non-JSON formats will be noted in the documentation. When JSON data is returned, the maximum limit is 50 MB. If the returned data exceeds the maximum limit, the request will fail and an internal error will be returned. It is recommended to control the amount of returned data using the filtering or pagination features in the API documentation.

Note: As long as the request is processed normally by the server, the HTTP Status Code of the response is 200. For example, even for errors such as signature failure, the HTTP Status Code is still 200; the specific error information is reflected in the response body.

Successful Response

Taking the user query API as an example, a successful call returns the following:

{
  "Response": {
    "UserId": "user123456",
    "UserName": "张三",
    "PhoneNo": "(+86)13800138000",
    "PhysicalCardNo": "CARD001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

• Response and its internal RequestId are fixed fields and are returned regardless of whether the request succeeds.
• RequestId uniquely identifies an API request, facilitating troubleshooting.
• The remaining fields are business fields defined by the specific API.

Error Response

A failed call returns the following:

{
  "Response": {
    "Error": {
      "Code": "AuthFailure.SignatureFailure",
      "Message": "The provided credentials could not be validated. Please check your signature is correct."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

• The presence of the Error field indicates that the request failed. It contains Code (error code) and Message (error message).
• RequestId is still returned for troubleshooting.
• For error codes, refer to the "Common Error Codes" section of the API documentation.

Common Error Codes

If the Error field exists in the return result, the API call failed. The Error.Code field is the error code. Error codes that may occur in all businesses are common error codes. For the complete error code list, refer to the "Error Codes" page under the "API Documentation" directory of this product.

Parameter Types

Palm API 3.0 input parameters and output parameters support the following data types:

Type	Description	Example
String	String	"user123456"
Integer	Integer, up to an unsigned 64-bit integer. It is recommended to use the maximum integer definition for different languages.	123456
Boolean	Boolean, true/false	true
Float	Floating-point	3.14
Double	Double-precision floating-point	3.1415926535
Date	String, date format	"2022-01-01"
Timestamp	String, time format	"2022-01-01 00:00:00"
Timestamp RFC3339	String, time format, RFC3339 standard time format; it is recommended to use a standard library for parsing	"2022-01-01T00:00:20.021Z"
Binary	Binary content, which must be requested and parsed using a specific protocol	-

Partial Failure

Partial failure is a special processing mechanism that allows successful operations in a batch to still be executed even if some operations fail. This mechanism improves the fault tolerance and efficiency of batch operations.

What Is Partial Failure

In batch operations (such as batch binding user tags), if the partial failure mechanism is not used:

• If any single operation fails, the entire request fails
• All operations are rolled back, even if most of them are valid

After enabling the partial failure mechanism:

• Valid operations are executed successfully
• Failed operations return detailed error information in the response
• You can retry the failed operations based on the returned error information

How to Use Partial Failure

APIs that support partial failure provide the PartialFailure parameter:

Request parameters:

Parameter Name	Required	Type	Description
PartialFailure	No	Boolean	Whether to allow partial failure. Set to true to enable the partial failure mechanism; the default is false.

Response fields:

When partial failure is enabled and there are failed items, the response includes the PartialFailureError field, detailing the reasons for the failures:

Parameter Name	Type	Description
PartialFailureError	Object	Partial failure error information, containing details of the failed items.

Example Scenarios

Scenario 1: Create a user and batch bind tags

Sample Request:

{
  "UserId": "user001",
  "UserName": "张三",
  "UserTagIdList": ["tag001", "tag002", "tag003"],
  "PartialFailure": true
}

Successful Response (no failed items):

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Partial failure response (failed items exist):

{
  "Response": {
    "PartialFailureError": {
      "NotExistUserTagIdList": ["tag003"]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

In the above example:

• User user001 was created successfully
• tag001 and tag002 were bound successfully
• tag003 does not exist, so the binding failed

Retry note: If you need to retry, after fixing tag003 you must pass the complete tag list ["tag001", "tag002", "tag003"], not just ["tag003"], because user tag binding is an overwrite operation.

Best Practices

1. Enable partial failure for batch operations

   • In batch creation, modification, and other operations, it is recommended to set PartialFailure=true
   • This ensures that valid data is processed and invalid data is recorded

2. Check the PartialFailureError field in the response

   • Even when the result is returned successfully, check the PartialFailureError field
   • The presence of PartialFailureError indicates that some operations failed and need to be handled based on the returned information

3. Record and retry failed items

   • Record the failed item information returned in PartialFailureError
   • Fix the cause of the failure and resend the request
   • Note: For overwrite operations such as batch binding user tags, you must pass the complete tag list (including previously successful items) when retrying, rather than retrying only the failed items

4. Idempotency design

   • Ensure that operations are idempotent so that failed operations can be safely retried
   • Batch binding operations must be retried with complete data (overwrite update)

APIs Supporting Partial Failure

The following APIs support the partial failure mechanism:

• Create User: Supports partial failure when batch binding user tags
• Modify User: Supports partial failure when batch binding user tags

Note: Not all APIs support the partial failure mechanism. For specific support, refer to the parameter description of each API.

---

Authentication Management APIs

Obtain Access Credentials

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to obtain access credentials (AccessToken). The following calling method is only applicable to scenarios where a common server calls the Palm Application Platform open APIs.

Note: This API only requires a signature (Authorization); X-Palm-Openapi-Token does not need to be passed. Before integrating with the Palm Application Platform service, the customer needs to apply to Tencent for AppId, SecretId, and SecretKey. Please keep this information secure and pass it in API requests as needed.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateAccessToken.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
AppId	Yes	Integer	Product ID assigned by the system
SecretId	Yes	String	Customer's key ID
SecretKeyHash	Yes	String	Hash of the customer's key, calculated as: hex.EncodeToString(sha256.Sum256(secretKey))
GrantType	Yes	String	Grant Type. When calling the Palm Application Platform open APIs, you must use client_credential. Valid values: - client_credential_user: Applicable to scenarios where a third-party platform integrates the Mobile Palm Registration SDK, that is: a. The mobile end uses the SDK to initiate registration or obtain the liveness video upload URL; b. The third-party server needs to apply for an access credential for a specified user for use by the SDK; c. In this case, the UserId field must be passed at the same time. - client_credential: Applicable to scenarios where a common server calls the open APIs, that is: a. Under this type, no specific user is bound; only the application-level key is used to obtain the access credential; b. The UserId field does not need to be passed.
UserId	No	String	User identity ID. When grant_type is "client_credential_user", the UserId field must be passed

3. Output Parameters

Parameter Name	Type	Description
AccessToken	String	Access credential, which can be used to access other APIs
ExpiresIn	Integer	Validity period of the AccessToken in seconds. The token becomes invalid after expiration
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateAccessToken
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
   "AppId": 223,
   "SecretId": "this is secretId",
   "SecretKeyHash": "this is secretKey hash",
   "GrantType": "client_credential"
}

Output Example

{
  "Response": {
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ExpiresIn": 7200,
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Authorization Information

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Query Server-Side Authorization Information, including the palm database capacity limit, current usage, and License expiration time.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribePalmLicense.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
AppId	Yes	Integer	Product ID assigned by the system.

3. Output Parameters

Parameter Name	Type	Description
PalmCapacity	Integer	Palm database capacity limit, indicating the maximum number of palm prints allowed to be registered under the current license.
PalmUsage	Integer	Current palm database usage, indicating the number of registered palm prints.
ExpireTime	Integer	License expiration time, UTC timestamp in seconds. The service cannot be used after expiration.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribePalmLicense
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "AppId": 223
}

Output Example

{
  "Response": {
    "PalmCapacity": 100000,
    "PalmUsage": 5000,
    "ExpireTime": 1756108800,
    "RequestId": "e3b0c442-98fc-1c14-b39f-f75b262b1d0e"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

User Management APIs

Create User

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a new user and supports setting basic user information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateUser.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
UserName	Yes	String	User name.
PhoneNo	No	String	Phone number (with country code), e.g., "(+86)13800138000". If the country code is not provided, "(+86)" is used by default.
PhysicalCardNo	No	String	Physical card number, a combination of digits and letters.
UserTagIdList	No	Array of String	List of user tag IDs.
PartialFailure	No	Boolean	Whether to allow partial failure.
CustomFieldValue	No	String	Deprecated. Use CustomFieldValueList instead.
CustomFieldValueList	No	Array of CustomFieldValueItem	List of custom additional verification field values. If both CustomFieldValue and CustomFieldValueList are passed, CustomFieldValueList takes precedence.

3. Output Parameters

Parameter Name	Type	Description
PartialFailureError	CreateUserResponsePartialFailureError	Partial failure result. See the CreateUserResponsePartialFailureError structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user123456",
  "UserName": "张三",
  "PhoneNo": "(+86)13800138000",
  "PhysicalCardNo": "CARD001",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true,
  "CustomFieldValueList": [
    {"FieldName": "工号", "FieldValue": "123456"}
  ]
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Partial failure output example

{
  "Response": {
    "PartialFailureError": {
      "NotExistUserTagIdList": [
        "tag003"
      ]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserNameEmpty",
      "Message": "用户名称为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Modify User

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to modify user information and supports updating basic user information.

Note: This API performs a full update and requires all user field information to be passed. Optional fields that are not passed will be cleared. It is recommended to call DescribeUser to obtain the current user information before modifying.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: ModifyUser.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
UserName	Yes	String	User name.
PhoneNo	No	String	Phone number (with country code), e.g., "(+86)13800138000". If the country code is not provided, "(+86)" is used by default.
PhysicalCardNo	No	String	Physical card number, a combination of digits and letters.
UserTagIdList	No	Array of String	List of user tag IDs.
PartialFailure	No	Boolean	Whether to allow partial failure.
CustomFieldValue	No	String	Deprecated. Use CustomFieldValueList instead.
CustomFieldValueList	No	Array of CustomFieldValueItem	Full list of custom additional verification field values. If both CustomFieldValue and CustomFieldValueList are passed, CustomFieldValueList takes precedence.

3. Output Parameters

Parameter Name	Type	Description
PartialFailureError	ModifyUserResponsePartialFailureError	Partial failure result. See the ModifyUserResponsePartialFailureError structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "UserName": "张三",
  "PhoneNo": "(+86)13800138000",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true,
  "CustomFieldValueList": [
    {"FieldName": "工号", "FieldValue": "123456"}
  ]
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Partial failure output example

{
  "Response": {
    "PartialFailureError": {
      "NotExistUserTagIdList": [
        "tag003"
      ]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete User

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete a specified user. Deleted user data cannot be recovered.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteUser.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query detailed information about a specified user, including basic information and palm registration status.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUser.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
UserId	String	Unique user identifier.
UserName	String	User name.
PhoneNo	String	Phone number (with country code), e.g., "(+86)13800138000". If the country code is not provided, "(+86)" is used by default.
PhysicalCardNo	String	Physical card number, a combination of digits and letters.
UserTagList	Array of DescribeUserResponseUserTag	User tag list. See the DescribeUserResponseUserTag structure.
PalmDirection	PalmDirection	Palm direction. See the PalmDirection enum.
LeftPalm	PalmInfo	Left palm registration information. See the PalmInfo structure.
RightPalm	PalmInfo	Right palm registration information. See the PalmInfo structure.
CreateTime	Timestamp	User creation time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
UserState	UserState	User state. See the UserState enum.
CustomFieldValue	String	Deprecated. Use CustomFieldValues instead.
CustomFieldValues	Array of CustomFieldValueItem	Full list of custom additional verification field values.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "UserId": "user001",
    "UserName": "张三",
    "PhoneNo": "(+86)13800138000",
    "PhysicalCardNo": "CARD2024A001",
    "UserTagList": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发中心"
      },
      {
        "UserTagId": "tag002",
        "UserTagName": "产品中心"
      }
    ],
    "PalmDirection": "right",
    "RightPalm": {
      "PalmState": "registered",
      "RegisterType": "device",
      "PreRegisterTime": "2025-06-01T10:00:00.000Z",
      "RegisterTime": "2025-06-01T10:05:00.000Z",
      "ExpireTime": "2026-06-01T10:05:00.000Z"
    },
    "CreateTime": "2025-05-20T08:30:00.000Z",
    "UserState": "right_valid",
    "CustomFieldValues": [
      {"FieldName": "工号", "FieldValue": "123456"}
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "未找到该用户信息。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Information List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the user information list, supporting multi-condition filtering and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	No	String	Unique user identifier. Fuzzy query is supported.
UserName	No	String	User name. Fuzzy query is supported.
PhoneNo	No	String	Phone number. Exact match.
PhysicalCardNo	No	String	Physical card number. Exact match.
PalmState	No	PalmState	Primary palm registration status.
UserState	No	UserState	User state.
UserTagId	No	String	User tag ID, filters users that have the specified tag.
SceneId	No	String	Scene ID, filters users with access permission for that scene.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.
SkipTotalCount	No	Boolean	Whether to skip counting the total. When set to true, TotalCount is not returned (avoiding slow queries); use HasMore instead to determine whether there is a next page.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Number of users that meet the conditions. This field is not returned when the request has SkipTotalCount=true.
UserList	Array of DescribeUserListResponseUser	User list. See the DescribeUserListResponseUser structure.
HasMore	Boolean	Whether there is more data. When the request has SkipTotalCount=true, use this field to determine whether there is a next page.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserName": "张",
  "PalmState": "registered",
  "Offset": 0,
  "Limit": 10
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "UserList": [
      {
        "UserId": "user001",
        "UserName": "张三",
        "PhoneNo": "(+86)13800138000",
        "PhysicalCardNo": "CARD001",
        "UserTagList": [{"UserTagId": "tag001", "UserTagName": "研发中心"}],
        "RegisterType": "device",
        "PalmState": "registered",
        "PalmDirection": "right",
        "PalmRegisterTime": "2025-06-01T10:05:00.000Z",
        "PalmExpireTime": "2026-06-01T10:05:00.000Z",
        "UserState": "right_valid",
        "CreatedTime": "2025-05-20T08:30:00.000Z",
        "UpdatedTime": "2025-06-01T10:05:00.000Z"
      }
    ],
    "HasMore": false,
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Access Scope

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Queries detailed information about the scenes, devices, and access time periods that a user can access, based on the user ID.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserAccessScope.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Total number of scenes that meet the conditions.
AccessScopeList	Array of AccessScopeItem	Access scope list (aggregated by scene). See the AccessScopeItem structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserAccessScope
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "AccessScopeList": [
      {
        "SceneId": "scene001",
        "SceneName": "大门",
        "SceneGroupId": "group001",
        "SceneGroupName": "总部园区",
        "DeviceSn": "DEV001",
        "DeviceName": "前台设备",
        "VerifyRules": [
          {"VerifyRuleId": "rule001", "VerifyRuleName": "工作日规则"}
        ]
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Access Scope Summary

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Counts the number of scene groups, scenes, and devices that a user can access, based on the user ID.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserAccessScopeSummary.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
Summary	AccessScopeSummary	Access scope summary. See the AccessScopeSummary structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserAccessScopeSummary
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "Summary": {
      "SceneGroupCount": 3,
      "SceneCount": 8,
      "DeviceCount": 15
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

User Tag Management APIs

Create User Tag

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a new user tag.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateUserTag.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserTagName	Yes	String	User tag name.

3. Output Parameters

Parameter Name	Type	Description
UserTagId	String	Unique user tag identifier.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagName": "研发中心"
}

Output Example

{
  "Response": {
    "UserTagId": "tag001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserTagNameEmpty",
      "Message": "用户标签名称为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Modify User Tag

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to modify user tag information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: ModifyUserTag.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserTagId	Yes	String	Unique user tag identifier.
UserTagName	Yes	String	User tag name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagId": "tag001",
  "UserTagName": "产品中心"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "用户标签不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete User Tag

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete a specified user tag. Deleted user tag data cannot be recovered.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteUserTag.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserTagId	Yes	String	Unique user tag identifier.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagId": "tag001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "用户标签不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Tag

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query detailed information about a specified user tag.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserTag.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserTagId	Yes	String	Unique user tag identifier.

3. Output Parameters

Parameter Name	Type	Description
UserTagId	String	Unique user tag identifier.
UserTagName	String	User tag name.
ParentTagId	String	Parent tag ID. Empty indicates a top-level tag.
Level	Integer	Hierarchy depth: 0=L1 (top level), 1=L2 (level 2), 2=L3 (level 3).
ChildrenCount	Integer	Number of direct child tags.
UserCount	Integer	Number of users associated with the tag.
PathNodes	Array of UserTagNode	Complete hierarchy path from the root tag to the current tag, returned in parent-to-child order. See the UserTagNode structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserTag
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagId": "tag001"
}

Output Example

{
  "Response": {
    "UserTagId": "tag001",
    "UserTagName": "研发中心",
    "ParentTagId": "",
    "Level": 0,
    "ChildrenCount": 3,
    "UserCount": 50,
    "PathNodes": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发中心",
        "Level": 0
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "未找到该用户标签信息。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Tag List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the user tag list, supporting fuzzy search and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserTagList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserTagName	No	String	Tag name. Fuzzy search is supported.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Total number of tags that meet the conditions.
UserTagList	Array of DescribeUserTagListResponseUserTagItem	Tag information list. See the DescribeUserTagListResponseUserTagItem structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserTagList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserTagName": "研发",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "UserTagList": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发中心",
        "UserCount": 50,
        "ParentTagId": "",
        "Level": 0,
        "ChildrenCount": 3,
        "PathNodes": [
          {
            "UserTagId": "tag001",
            "UserTagName": "研发中心",
            "Level": 0
          }
        ],
        "CreatedTime": "2025-05-01T10:00:00.000Z",
        "UpdatedTime": "2025-06-01T10:00:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Tag Tree Structure

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Queries the user tag tree structure and returns the tag hierarchy.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserTagTree.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
RootTagId	No	String	Root tag ID. Empty indicates that the complete tree is returned.

3. Output Parameters

Parameter Name	Type	Description
Tree	Array of UserTagTreeNode	Tag tree node list. See the UserTagTreeNode structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserTagTree
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "RootTagId": ""
}

Output Example

{
  "Response": {
    "Tree": [
      {
        "UserTagId": "tag001",
        "UserTagName": "研发部",
        "UserCount": 50,
        "Level": 0,
        "ParentTagId": "",
        "Children": [
          {
            "UserTagId": "tag002",
            "UserTagName": "前端组",
            "UserCount": 20,
            "Level": 1,
            "ParentTagId": "tag001",
            "Children": []
          }
        ]
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

User Palm Management APIs

Delete User Palm Information

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete the palm information of a specified user. After deletion, palm registration must be performed again.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteUserPalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
PalmDirectionList	No	Array of PalmDirection	Palm direction list. If not passed, both palms are deleted.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteUserPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "PalmDirectionList": ["left", "right"]
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户手掌信息不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query User Palm Information

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the palm print information and palm registration status of a specified user.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeUserPalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
UserId	String	Unique user identifier.
PalmState	PalmState	Primary palm registration status.
UserName	String	User name.
UserState	UserState	User state. See the UserState enum.
PalmDirection	PalmDirection	Primary palm direction. See the PalmDirection enum.
LeftPalm	PalmInfo	Left palm registration information. See the PalmInfo structure.
RightPalm	PalmInfo	Right palm registration information. See the PalmInfo structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeUserPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "UserId": "user001",
    "PalmState": "registered",
    "UserName": "张三",
    "UserState": "right_valid",
    "PalmDirection": "right",
    "RightPalm": {
      "PalmState": "registered",
      "RegisterType": "device",
      "PreRegisterTime": "2025-06-01T10:00:00.000Z",
      "RegisterTime": "2025-06-01T10:05:00.000Z",
      "ExpireTime": "2026-06-01T10:05:00.000Z"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "未找到该用户手掌信息。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Device Management APIs

Create Device

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a new device and supports setting basic device information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateDevice.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
DeviceSn	Yes	String	Device serial number.
DeviceName	Yes	String	Device name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001",
  "DeviceName": "深圳南山门禁1号"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.DeviceSnEmpty",
      "Message": "设备SN为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Modify Device

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to modify device information and supports updating basic device information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: ModifyDevice.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
DeviceSn	Yes	String	Device serial number.
DeviceName	Yes	String	Device name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001",
  "DeviceName": "深圳南山门禁1号（已更新）"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "设备不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete Device

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete a specified device. Deleted device data cannot be recovered.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteDevice.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
DeviceSn	Yes	String	Device serial number.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "设备不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Device Details

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query detailed information about a specified device.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeDevice.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
DeviceSn	Yes	String	Device serial number.

3. Output Parameters

Parameter Name	Type	Description
DeviceSn	String	Device SN.
DeviceName	String	Associated device name.
DeviceType	String	Device type.
ModuleType	String	Module type.
ModuleExpireTime	Timestamp	Module validity period in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
AppVersion	String	Application version.
ModuleVersion	String	Module version.
SystemVersion	String	System version.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeDevice
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSn": "device001"
}

Output Example

{
  "Response": {
    "DeviceSn": "device001",
    "DeviceName": "深圳南山门禁设备",
    "DeviceType": "M4",
    "ModuleType": "A3",
    "ModuleExpireTime": "2027-07-03T09:30:15.500Z",
    "AppVersion": "1.0.0",
    "ModuleVersion": "2.0.0",
    "SystemVersion": "3.0.0",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "设备不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Device List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the device list, supporting multi-condition filtering and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeDeviceList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
DeviceSn	No	String	Device serial number. Exact match.
DeviceName	No	String	Device name. Fuzzy search is supported.
Status	No	DeviceStatus	Device status filter.
SceneId	No	String	Scene ID, filters devices bound to the specified scene.
DeviceType	No	String	Device type. For valid values, see the Glossary.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Total number of devices that meet the conditions.
DeviceList	Array of DescribeDeviceListResponseDevice	Device list. See the DescribeDeviceListResponseDevice structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeDeviceList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceName": "门禁",
  "Status": "online",
  "Offset": 0,
  "Limit": 10
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "DeviceList": [
      {
        "DeviceSn": "SN001",
        "DeviceType": "M4",
        "DeviceName": "深圳南山门禁设备",
        "HeartbeatTime": "2025-07-15T09:30:00.000Z",
        "SystemVersion": "1.0.0",
        "AppVersion": "2.0.0",
        "ModuleType": "A3",
        "ModuleVersion": "3.0.0",
        "ModuleExpireTime": "2026-07-15T09:30:00.000Z",
        "Status": "online",
        "SceneId": "scene001",
        "SceneName": "深圳南山门禁1号",
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Device Emergency Status

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the emergency status of devices. The input is a list of device SNs (all SNs must belong to the same tenant AppId). It returns the emergency status of the current tenant and each device. When the SN list is empty, only devices in the emergency state are returned.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeDeviceEmergencyStatus.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
DeviceSnList	No	Array of String	Device SN list. If not empty, the emergency status of the corresponding devices is queried by exact SN match; all SNs must belong to the same tenant AppId, with a maximum of 100. If empty, all devices in the emergency state under the current tenant are returned with pagination.
Offset	No	Integer	Offset. Default: 0. Takes effect only when DeviceSnList is empty.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100. Takes effect only when DeviceSnList is empty.

3. Output Parameters

Parameter Name	Type	Description
TenantEmergencyStatus	EmergencyStatus	Emergency status of the current tenant. See the EmergencyStatus enum.
DeviceEmergencyStatusList	Array of DescribeDeviceEmergencyStatusResponseDeviceEmergencyStatus	Emergency status list of each device. See the DescribeDeviceEmergencyStatusResponseDeviceEmergencyStatus structure.
TotalCount	Integer	Total number of devices that meet the conditions.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeDeviceEmergencyStatus
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "DeviceSnList": [
    "SN001",
    "SN002"
  ]
}

Output Example

{
  "Response": {
    "TenantEmergencyStatus": 0,
    "DeviceEmergencyStatusList": [
      {
        "DeviceSn": "SN001",
        "EmergencyStatus": 1
      },
      {
        "DeviceSn": "SN002",
        "EmergencyStatus": 2
      }
    ],
    "TotalCount": 2,
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Send Emergency Control Command

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to issue emergency control commands. Supports issuing block (block all) / open (open all) / reset_block (restore block all) / reset_open (restore open all) commands to all devices or to a specified SN list.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: SendEmergencyCommand.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
CommandType	Yes	SendEmergencyCommandRequestEmergencyCommandType	Command type. See the SendEmergencyCommandRequestEmergencyCommandType enum.
Scope	Yes	EmergencyCommandScope	Effective scope. See the EmergencyCommandScope enum.
DeviceSnList	No	Array of String	Device SN list. Required only when Scope is 2 (specified SN list). All SNs must belong to the same tenant AppId.
Reason	Yes	String	Operation reason.

3. Output Parameters

Parameter Name	Type	Description
FailedDeviceList	Array of SendEmergencyCommandResponseFailedDevice	List of devices for which the command failed to be issued. See the SendEmergencyCommandResponseFailedDevice structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SendEmergencyCommand
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "CommandType": 1,
  "Scope": 2,
  "DeviceSnList": [
    "SN001",
    "SN002"
  ],
  "Reason": "应急演练"
}

Output Example

{
  "Response": {
    "FailedDeviceList": [
      {
        "DeviceSn": "SN002",
        "ErrorMessage": "设备离线"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Scene Management APIs

Create Scene

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a new scene, supporting setting basic scene information, binding devices, and verification rules.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateScene.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneName	Yes	String	Scene name.
SceneGroupId	Yes	String	Scene group ID.
DeviceSn	No	String	Device serial number.
VerifyRuleIdList	No	Array of String	List of verification rule IDs.
SceneId	No	String	Scene ID (optional; automatically generated if not passed).
ScenarioStrategy	Yes	ScenarioStrategy	Scene strategy. See the ScenarioStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
SceneId	String	Unique scene identifier.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneName": "深圳南山门禁1号",
  "SceneGroupId": "scenegroup001",
  "DeviceSn": "device001",
  "VerifyRuleIdList": ["verifyrule001", "verifyrule002"],
  "ScenarioStrategy": "AccessOnDeviceRecognition50k"
}

Output Example

{
  "Response": {
    "SceneId": "scene001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.SceneNameEmpty",
      "Message": "场景名称不能为空。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Modify Scene

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to modify scene information, supporting updating basic scene information, bound devices, and verification rules.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: ModifyScene.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneId	Yes	String	Scene ID.
SceneName	Yes	String	Scene name.
DeviceSn	No	String	Device serial number.
VerifyRuleIdList	No	Array of String	List of verification rule IDs.
ScenarioStrategy	Yes	ScenarioStrategy	Scene strategy. See the ScenarioStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneId": "scene001",
  "SceneName": "深圳南山门禁1号（已更新）",
  "DeviceSn": "device002",
  "VerifyRuleIdList": ["verifyrule001"],
  "ScenarioStrategy": "AccessOnDeviceRecognition50k"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "场景不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete Scene

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete a specified scene. Deleted scene data cannot be recovered.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteScene.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneId	Yes	String	Scene ID.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneId": "scene001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "场景不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Scene Details

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query detailed information about a specified scene.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeScene.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneId	Yes	String	Scene ID.

3. Output Parameters

Parameter Name	Type	Description
SceneId	String	Scene ID.
SceneName	String	Scene name.
SceneGroupId	String	Scene group ID.
SceneGroupName	String	Scene group name.
DeviceSn	String	Associated device SN.
DeviceName	String	Associated device name.
ScenarioStrategy	ScenarioStrategy	Scene strategy. See the ScenarioStrategy enum.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeScene
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneId": "scene001"
}

Output Example

{
  "Response": {
    "SceneId": "scene001",
    "SceneName": "深圳南山门禁1号",
    "SceneGroupId": "scenegroup001",
    "SceneGroupName": "深圳南山区域",
    "DeviceSn": "device001",
    "DeviceName": "深圳南山门禁设备",
    "ScenarioStrategy": "AccessOnDeviceRecognition50k",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "场景不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Create Scene Group

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a new scene group, supporting setting basic scene group information and the parent scene group.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateSceneGroup.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneGroupName	Yes	String	Scene group name.
ParentSceneGroupId	Yes	String	Parent scene group ID.

3. Output Parameters

Parameter Name	Type	Description
SceneGroupId	String	Unique scene group identifier.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateSceneGroup
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneGroupName": "深圳南山区域",
  "ParentSceneGroupId": "scene_group_root"
}

Output Example

{
  "Response": {
    "SceneGroupId": "scenegroup001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.SceneGroupNameEmpty",
      "Message": "场景组名称不能为空。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Modify Scene Group

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to modify scene group information and supports updating basic scene group information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: ModifySceneGroup.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneGroupId	Yes	String	Scene group ID.
SceneGroupName	Yes	String	Scene group name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifySceneGroup
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneGroupId": "scenegroup001",
  "SceneGroupName": "深圳南山区域（已更新）"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneGroupNotExist",
      "Message": "场景组不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete Scene Group

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete a specified scene group. Deleted scene group data cannot be recovered.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteSceneGroup.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneGroupId	Yes	String	Scene group ID.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteSceneGroup
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneGroupId": "scenegroup001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneGroupNotExist",
      "Message": "场景组不存在或已被删除。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Scene List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the scene list, supporting multi-condition filtering and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeSceneList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneIdList	No	Array of String	Scene ID list. Exact match; batch query is supported.
SceneName	No	String	Scene name. Fuzzy search is supported.
SceneGroupId	No	String	Scene group ID, filters scenes belonging to the specified scene group.
DeviceSn	No	String	Device serial number. Exact match.
VerifyRuleId	No	String	Verification rule ID, filters scenes bound to the specified rule.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Total number of scenes that meet the conditions.
SceneList	Array of DescribeSceneListResponseSceneItem	Scene information list. See the DescribeSceneListResponseSceneItem structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeSceneList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "SceneName": "门禁",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "SceneList": [
      {
        "SceneId": "scene001",
        "SceneName": "深圳南山门禁1号",
        "SceneGroupId": "sg001",
        "SceneGroupName": "深圳南山区域",
        "DeviceSn": "SN001",
        "DeviceName": "深圳南山门禁设备",
        "ScenarioStrategy": "AccessOnDeviceRecognition50k",
        "VerifyRuleIdList": ["vr_001"],
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Scene Group List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the scene group list, supporting multi-condition filtering and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeSceneGroupList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SceneGroupIdList	No	Array of String	Scene group ID list. Exact match; batch query is supported.
SceneGroupName	No	String	Scene group name. Fuzzy search is supported.
ParentSceneGroupId	No	String	Parent scene group ID. When passed, only the direct child scene groups under that parent are returned; when not passed, all scene groups are returned.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Total number of scene groups that meet the conditions.
SceneGroupList	Array of DescribeSceneGroupListResponseSceneGroupItem	Scene group information list. See the DescribeSceneGroupListResponseSceneGroupItem structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeSceneGroupList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ParentSceneGroupId": "sg_root",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "SceneGroupList": [
      {
        "SceneGroupId": "sg001",
        "SceneGroupName": "深圳南山区域",
        "ParentSceneGroupId": "sg_root",
        "ParentSceneGroupName": "全部场景组",
        "SceneCount": 3,
        "ChildGroupCount": 1,
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Verification Record APIs

Create Verification Record

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a verification record.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateVerificationRecord.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	User ID.
VerificationTime	Yes	Timestamp	Verification time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
VerificationMedium	Yes	VerificationMedium	Verification medium.
DeviceSn	Yes	String	Device SN.
VerifierId	No	String	Verifier ID.
VerifierName	No	String	Verifier name.
Source	No	VerificationRecordSource	Verification record source. If not passed, it defaults to device-side reporting.
AccessDenied	No	Boolean	Whether the verification result is rejected. Returned (with the value true) only when verification fails.
Reason	No	String	Verification description.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerificationRecord
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "VerifierId": "verifier001",
  "VerifierName": "李四",
  "Source": "device"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserIdEmpty",
      "Message": "用户ID不能为空。"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Verification Record List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the verification record list, supporting multi-condition filtering and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeVerificationRecordList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	No	String	User ID.
UserName	No	String	User name.
VerificationMedium	No	VerificationMedium	Verification medium.
DeviceSn	No	String	Device SN.
SceneId	No	String	Scene ID.
StartTime	No	Timestamp	Verification start time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
EndTime	No	Timestamp	Verification end time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
SceneGroupIds	No	Array of String	Scene group ID list. Exact match (including expansion of child scene groups).
SceneGroupName	No	String	Scene group name. Fuzzy search.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.
OrderBy	No	OrderBy	Sorting condition. See the OrderBy structure.
Source	No	VerificationRecordSource	Verification record source filter (optional).
SkipTotalCount	No	Boolean	Whether to skip counting the total. When set to true, TotalCount is not returned (avoiding slow queries); use HasMore instead to determine whether there is a next page.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Number of verification records that meet the conditions. This field is not returned when the request has SkipTotalCount=true.
VerificationRecordList	Array of DescribeVerificationRecordListResponseVerificationRecord	Verification record list. See the DescribeVerificationRecordListResponseVerificationRecord structure.
HasMore	Boolean	Whether there is more data. When the request has SkipTotalCount=true, use this field to determine whether there is a next page.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVerificationRecordList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "UserName": "张三",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "StartTime": "2024-06-01T00:00:00+08:00",
  "EndTime": "2024-06-30T23:59:59+08:00",
  "Offset": 0,
  "Limit": 10
}

Output Example

{
  "Response": {
    "TotalCount": 2,
    "VerificationRecordList": [
      {
        "UserId": "user001",
        "UserName": "张三",
        "VerificationTime": "2024-06-10T09:15:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device001",
        "SceneId": "scene001",
        "SceneName": "深圳南山门禁1号",
        "VerifierId": "verifier001",
        "VerifierName": "李四",
        "Source": "device",
        "Reason": ""
      },
      {
        "UserId": "user001",
        "UserName": "张三",
        "VerificationTime": "2024-06-11T18:30:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device002",
        "SceneId": "scene002",
        "SceneName": "深圳南山门禁2号",
        "VerifierId": "verifier002",
        "VerifierName": "王五",
        "Source": "device",
        "AccessDenied": true,
        "Reason": "不在通行时间段内"
      }
    ],
    "HasMore": false,
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.FiltersLimitExceed",
      "Message": "过滤器个数超过限制"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Verification Record (Push Only)

1. API Description

Interface push domain: Provided by the customer to the platform; the platform pushes actively

Interface description: Used to receive verification record information pushed by the open platform. This API only supports push and does not support active pulling.

The push content is the verification record details (see the table below). After receiving a push, the customer only needs to return HTTP 200 OK.

2. Push Content (Parameter Structure)

Parameter Name	Type	Description
UserId	String	User ID
UserName	String	User name
VerificationTime	Timestamp	Verification time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
VerificationMedium	VerificationMedium	Verification medium
DeviceSn	String	Device SN
SceneId	String	Scene ID
SceneName	String	Scene name
VerifierId	String	Verifier ID
VerifierName	String	Verifier name
AccessDenied	Boolean	Whether the verification result is rejected. false indicates successful verification; true indicates failed verification
Reason	String	Verification description
RequestId	String	Unique request ID

3. Push Example

POST / HTTP/1.1
Host: <客户推送地址域名>
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerificationRecord

{
  "UserId": "user001",
  "UserName": "张三",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "深圳南山门禁1号",
  "VerifierId": "verifier001",
  "VerifierName": "李四",
  "AccessDenied": false,
  "Reason": "",
  "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
}

After receiving a push, the customer only needs to return HTTP 200 OK; no business data needs to be returned.

---

Verification Rule APIs

Create Verification Rule

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to create a verification rule, supporting the configuration of time rules and user rules, and can be bound to multiple scenes.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateVerifyRule.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
VerifyRuleName	Yes	String	Verification rule name.
EnableTimeRule	Yes	Boolean	Whether to enable the time rule. false means disabled; true means enabled.
TimeRule	No	TimeRule	Time rule. Required when the time rule is enabled. See the TimeRule structure.
EnableUserRule	Yes	Boolean	Whether to enable the user rule. false means all users; true means specified users.
UserRule	No	UserRule	User rule. Required when the user rule is enabled. See the UserRule structure.
EnableWebhookRule	No	Boolean	Whether to enable the webhook rule. Optional; defaults to true when not passed.
BindSceneIdList	No	Array of String	List of bound scene IDs. Multiple scenes can be bound.

3. Output Parameters

Parameter Name	Type	Description
VerifyRuleId	String	Verification rule ID.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleName": "工作日早晚高峰",
  "EnableTimeRule": true,
  "TimeRule": {
    "AllowDateRange": {
      "StartDate": {"Year": 2025, "Month": 1, "Day": 1},
      "EndDate": {"Year": 2025, "Month": 12, "Day": 31}
    },
    "AllowDayOfWeekList": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
    "AllowTimePeriodList": [
      {
        "StartTime": {"Hours": 7, "Minutes": 30, "Seconds": 0},
        "EndTime": {"Hours": 9, "Minutes": 30, "Seconds": 0},
        "MaxVerificationCount": 0
      },
      {
        "StartTime": {"Hours": 17, "Minutes": 30, "Seconds": 0},
        "EndTime": {"Hours": 20, "Minutes": 0, "Seconds": 0},
        "MaxVerificationCount": 0
      }
    ]
  },
  "EnableUserRule": true,
  "UserRule": {
    "UserTags": [
      {"UserTagId": "tag001", "UserTagName": "研发中心"}
    ],
    "UserInfos": [
      {"UserId": "user001", "UserName": "张三"}
    ]
  },
  "EnableWebhookRule": false,
  "BindSceneIdList": ["scene001", "scene002"]
}

Output Example

{
  "Response": {
    "VerifyRuleId": "vr_20250715001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Modify Verification Rule

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to modify existing verification rule information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: ModifyVerifyRule.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
VerifyRuleId	Yes	String	Globally unique verification rule ID.
VerifyRuleName	Yes	String	Verification rule name.
EnableTimeRule	Yes	Boolean	Whether to enable the time rule.
TimeRule	No	TimeRule	Time rule. See the TimeRule structure.
EnableUserRule	Yes	Boolean	Whether to enable the user rule.
UserRule	No	UserRule	User rule. See the UserRule structure.
EnableWebhookRule	Yes	Boolean	Whether to enable the webhook rule.
BindSceneIdList	No	Array of String	List of bound scene IDs.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: ModifyVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleId": "vr_20250715001",
  "VerifyRuleName": "工作日高峰与中午",
  "EnableTimeRule": true,
  "TimeRule": {
    "AllowDayOfWeekList": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
    "AllowTimePeriodList": [
      {"StartTime": {"Hours": 7, "Minutes": 30, "Seconds": 0}, "EndTime": {"Hours": 9, "Minutes": 30, "Seconds": 0}},
      {"StartTime": {"Hours": 12, "Minutes": 0, "Seconds": 0}, "EndTime": {"Hours": 13, "Minutes": 30, "Seconds": 0}},
      {"StartTime": {"Hours": 17, "Minutes": 30, "Seconds": 0}, "EndTime": {"Hours": 20, "Minutes": 0, "Seconds": 0}}
    ]
  },
  "EnableUserRule": false,
  "EnableWebhookRule": true,
  "BindSceneIdList": ["scene001"]
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete Verification Rule

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to delete a specified verification rule.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeleteVerifyRule.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
VerifyRuleId	Yes	String	Verification rule ID.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeleteVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleId": "vr_20250715001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Verification Rule

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the detailed configuration of a specified verification rule.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeVerifyRule.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
VerifyRuleId	Yes	String	Verification rule ID.

3. Output Parameters

Parameter Name	Type	Description
VerifyRuleId	String	Verification rule ID.
VerifyRuleName	String	Verification rule name.
EnableTimeRule	Boolean	Whether to enable the time rule.
TimeRule	TimeRule	Time rule. See the TimeRule structure.
EnableUserRule	Boolean	Whether to enable the user rule.
UserRule	UserRule	User rule. See the UserRule structure.
EnableWebhookRule	Boolean	Whether to enable the webhook rule.
BindSceneIdList	Array of String	List of bound scene IDs.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVerifyRule
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleId": "vr_20250715001"
}

Output Example

{
  "Response": {
    "VerifyRuleId": "vr_20250715001",
    "VerifyRuleName": "工作日早晚高峰",
    "EnableTimeRule": true,
    "TimeRule": {
      "AllowDateRange": {
        "StartDate": {
          "Year": 2025,
          "Month": 1,
          "Day": 1
        },
        "EndDate": {
          "Year": 2025,
          "Month": 12,
          "Day": 31
        }
      },
      "DisallowDateList": [
        {
          "Year": 2025,
          "Month": 5,
          "Day": 1
        }
      ],
      "AllowDayOfWeekList": [
        "MONDAY",
        "TUESDAY",
        "WEDNESDAY",
        "THURSDAY",
        "FRIDAY"
      ],
      "AllowTimePeriodList": [
        {
          "StartTime": {
            "Hours": 7,
            "Minutes": 30,
            "Seconds": 0
          },
          "EndTime": {
            "Hours": 9,
            "Minutes": 30,
            "Seconds": 0
          },
          "MaxVerificationCount": 0
        },
        {
          "StartTime": {
            "Hours": 17,
            "Minutes": 30,
            "Seconds": 0
          },
          "EndTime": {
            "Hours": 20,
            "Minutes": 0,
            "Seconds": 0
          },
          "MaxVerificationCount": 0
        }
      ]
    },
    "EnableUserRule": true,
    "UserRule": {
      "UserTags": [
        {
          "UserTagId": "tag001",
          "UserTagName": "研发中心"
        }
      ],
      "UserInfos": [
        {
          "UserId": "user001",
          "UserName": "张三"
        }
      ]
    },
    "EnableWebhookRule": false,
    "BindSceneIdList": [
      "scene001",
      "scene002"
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Verification Rule List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the verification rule list, supporting multi-condition filtering and pagination.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeVerifyRuleList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
VerifyRuleIdList	No	Array of String	Verification rule ID list. Exact match; batch query is supported.
VerifyRuleName	No	String	Verification rule name. Fuzzy search is supported.
Offset	No	Integer	Offset. Default: 0.
Limit	No	Integer	Number of results to return. Default: 20; maximum: 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	Total number of verification rules that meet the conditions.
VerifyRuleList	Array of DescribeVerifyRuleListResponseVerifyRuleItem	Verification rule list. See the DescribeVerifyRuleListResponseVerifyRuleItem structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVerifyRuleList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyRuleName": "工作日",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "VerifyRuleList": [
      {
        "VerifyRuleId": "vr_20250715001",
        "VerifyRuleName": "工作日早晚高峰",
        "EnableTimeRule": true,
        "TimeRule": {
          "AllowDayOfWeekList": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"],
          "AllowTimePeriodList": [
            {"StartTime": {"Hours": 7, "Minutes": 30, "Seconds": 0}, "EndTime": {"Hours": 9, "Minutes": 30, "Seconds": 0}, "MaxVerificationCount": 0}
          ]
        },
        "EnableUserRule": false,
        "EnableWebhookRule": true,
        "BindSceneIdList": ["scene001"],
        "CreatedTime": "2025-01-01T00:00:00.000Z",
        "UpdatedTime": "2025-07-15T09:30:00.000Z"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Check Access Permission (callback only)

1. API Description

Interface callback domain: Provided by the customer to the platform; the platform calls it actively

Interface description: Used to check a user's access permission. This API only supports callbacks and does not support active pulling. The callback address must be provided to the platform in advance, and the platform calls it actively. The platform sends an access permission check request, and the customer returns whether access is allowed along with the reason based on its own rules.

2. Input Parameters

Parameter Name	Type	Description
UserId	String	User ID
UserName	String	User name
VerificationTime	Timestamp	Verification time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z"
VerificationMedium	VerificationMedium	Verification medium
DeviceSn	String	Device SN
SceneId	String	Scene ID
SceneName	String	Scene name

3. Output Parameters

Parameter Name	Type	Description
Allowed	Boolean	Whether access is allowed
Reason	String	Access reason description, e.g., "Hit verification rule: visitor appointment access"
RequestId	String	Unique request ID. RequestId is returned for every request.

4. Request and Response Examples

Request Example

POST / HTTP/1.1
Host: <客户回调地址域名>
Content-Type: application/json; charset=utf-8
X-TC-Action: CheckAccessPermission

{
  "UserId": "user001",
  "UserName": "张三",
  "VerificationTime": "2025-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "深圳南山门禁1号"
}

Response Example (access allowed)

{
  "Response": {
    "Allowed": true,
    "Reason": "命中核验规则：访客预约通行",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Response Example (access denied)

{
  "Response": {
    "Allowed": false,
    "Reason": "用户未在允许时间范围内",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

QR Code Palm Registration APIs

The QR Code Palm Registration service is suitable for open user registration scenarios.

The QR code is generated by the palm verification device. After the user registers their palm, the palm verification device displays the QR code, which carries the user information. After the user scans the code, the application server is notified, and the application server registers the user based on the user information. Example of a URL obtained by scanning the QR code: https://app.intl.palm.tencent.com/local_h5/brushAuth?ocode=***&session_id=***&session_key=***&app_id=***&access_token=***

QR Code Scan Event Notification

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to notify the server of user QR code scan events. This API only verifies the Token and does not verify the signature; the Authorization field is not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid and X-Palm-Openapi-Token fields in the HTTP request header, which come from the app_id/access_token parameters in the scanned URL and can be reused until the token expires.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: NotifyQrCodeScanEvent.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SessionId	Yes	String	Session ID
EventType	No	NotifyQrCodeScanEventRequestQrCodeScanEventType	Event type. See the NotifyQrCodeScanEventRequestQrCodeScanEventType enum. When not passed, it is equivalent to scanned.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID. RequestId is returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: NotifyQrCodeScanEvent
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001"
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

QR Code Palm Print Binding

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to bind a palm print by scanning the QR code. This API only verifies the Token and does not verify the signature; the Authorization field is not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid and X-Palm-Openapi-Token fields in the HTTP request header, which come from the app_id/access_token parameters in the scanned URL and can be reused until the token expires.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: BindQrCodeScanPalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SessionId	Yes	String	Session ID
UserId	Yes	String	Unique user identifier
UserName	Yes	String	User name
ReplacePalm	No	Boolean	Whether to replace the palm

3. Output Parameters

Parameter Name	Type	Description
UserSessionId	String	User session ID
RequestId	String	Unique request ID. RequestId is returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: BindQrCodeScanPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001",
  "UserId": "user001",
  "UserName": "张三",
  "ReplacePalm": false
}

Output Example

{
  "Response": {
    "UserSessionId": "user_session_001",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query QR Code Palm Registration User Information

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query QR Code Palm Registration user information. This API only verifies the Token and does not verify the signature; the Authorization field is not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid and X-Palm-Openapi-Token fields in the HTTP request header, which come from the app_id/access_token parameters in the scanned URL and can be reused until the token expires.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeQrCodeScanUser.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SessionId	Yes	String	Session ID
UserId	Yes	String	Unique user identifier

3. Output Parameters

Parameter Name	Type	Description
UserId	String	Unique user identifier
PalmState	PalmState	Primary palm registration status
UserName	String	User name
UserState	UserState	User state. See the UserState enum.
PalmDirection	PalmDirection	Primary palm direction. See the PalmDirection enum.
LeftPalm	PalmInfo	Left palm registration information. See the PalmInfo structure.
RightPalm	PalmInfo	Right palm registration information. See the PalmInfo structure.
PhoneNo	String	Phone number (with country code).
RequestId	String	Unique request ID. RequestId is returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeQrCodeScanUser
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001",
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "UserId": "user001",
    "PalmState": "registered",
    "UserName": "张三",
    "UserState": "right_valid",
    "PalmDirection": "right",
    "RightPalm": {
      "PalmState": "registered",
      "RegisterType": "device",
      "PreRegisterTime": "2025-06-01T10:00:00.000Z",
      "RegisterTime": "2025-06-01T10:05:00.000Z",
      "ExpireTime": "2026-06-01T10:05:00.000Z"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Create QR Code Palm Registration Session

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Creates a QR Code Palm Registration session, used to generate a QR code or URL for user palm registration by scanning. Three session purposes are supported: QR Code Palm Registration (scan_register), tap-code palm registration (tap_register), and tap-code additional verification (tap_verify). This API only verifies the Token and does not verify the signature; the Authorization field is not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid and X-Palm-Openapi-Token fields in the HTTP request header, which come from the app_id/access_token parameters in the scanned URL and can be reused until the token expires.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreateQrCodeScanSession.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
Ttl	No	String	Expected session lifetime. Takes effect in scan_register/tap_register scenarios; in tap_verify scenarios it is determined by tenant configuration (this field does not take effect). When not specified, the default is 1 hour for scan_register and 15 minutes for tap_register. Maximum: 24 hours. String format, e.g., "3600s".
ResponseFormat	No	ResponseFormat	Response data format. Options: metadata (default, returns metadata), url (returns the QR code URL), image (returns the QR code image).
PalmDirection	No	PalmDirection	Palm direction, specifying the palm direction for this palm registration.
QrCodeSessionType	No	QrCodeSessionType	Session purpose. When not passed or set to scan_register, it is QR Code Palm Registration (default behavior); tap_register is tap-code palm registration; tap_verify is tap-code additional verification.
UserId	No	String	User ID. Required in tap_register/tap_verify scenarios.
UserName	No	String	User name. Required in the tap_register scenario; optional in the tap_verify scenario.
PhoneNo	No	String	Phone number. Optional in the tap-code palm registration scenario; when passed, it is checked against the user phone number in the backend.

3. Output Parameters

Parameter Name	Type	Description
SessionId	String	Session ID.
ExpireTime	Timestamp	Session expiration time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
AppId	String	Application ID, which must be carried in the HTTP request header "X-Palm-Appid" for subsequent QR Code Palm Registration requests of this session.
AccessToken	String	Access token, which must be carried in the HTTP request header "X-Palm-Openapi-Token" for subsequent QR Code Palm Registration requests of this session.
AccessTokenExpireTime	Timestamp	Token expiration time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
SessionUrl	String	Session URL. A complete H5 link in the scan_register scenario; a session identifier in tap_register/tap_verify scenarios. Returned only when ResponseFormat=url.
SessionImage	String	Session QR code image (base64-encoded binary data), returned only when ResponseFormat=image.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateQrCodeScanSession
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************

{
  "Ttl": "3600s",
  "ResponseFormat": "metadata",
  "PalmDirection": "right",
  "QrCodeSessionType": "scan_register"
}

Output Example

{
  "Response": {
    "SessionId": "session_001",
    "ExpireTime": "2025-07-03T10:30:15.500Z",
    "AppId": "app_001",
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "AccessTokenExpireTime": "2025-07-03T10:30:15.500Z",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query QR Code Palm Registration Session Status

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to query the QR Code Palm Registration session status. This API only verifies the Token and does not verify the signature; the Authorization field is not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid and X-Palm-Openapi-Token fields in the HTTP request header, which come from the app_id/access_token parameters in the scanned URL and can be reused until the token expires.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeQrCodeScanSession.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SessionId	Yes	String	Session ID.

3. Output Parameters

Parameter Name	Type	Description
QrCodeScanState	QrCodeScanState	QR code scan state.
UserId	String	Unique user identifier.
UserName	String	User name.
ReplacePalm	Boolean	Whether to replace the palm.
PalmDirection	PalmDirection	Palm direction.
QrCodeSessionType	QrCodeSessionType	Session purpose, used by the device side to distinguish between QR Code Palm Registration, tap-code palm registration, and tap-code additional verification scenarios.
PhoneNo	String	Phone number (with country code).
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeQrCodeScanSession
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: app_001
X-Palm-Openapi-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "SessionId": "session_001"
}

Output Example

{
  "Response": {
    "QrCodeScanState": "scanned",
    "UserId": "user001",
    "UserName": "张三",
    "ReplacePalm": false,
    "PalmDirection": "right",
    "QrCodeSessionType": "scan_register",
    "PhoneNo": "+8613800138000",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

PalmMa Login APIs

Send SMS Verification Code

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used to send an SMS verification code to a specified phone number. This API is an open API; it does not verify the Token or the signature, and the Authorization and X-Palm-Openapi-Token fields are not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid field in the HTTP request header.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: SendPalmMaSmsCode.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
PhoneNo	Yes	String	Phone number (with country code).

3. Output Parameters

Parameter Name	Type	Description
SessionId	String	Session ID, used for subsequent verification code validation.
ExpireTime	Timestamp	Session expiration time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
ResendInterval	String	Resend interval of the session verification code, e.g., "60s".
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SendPalmMaSmsCode
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223

{
  "PhoneNo": "+8613800138000"
}

Output Example

{
  "Response": {
    "SessionId": "sess_1234567890abcdef",
    "ExpireTime": "2025-07-03T09:40:15.500Z",
    "ResendInterval": "60s",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

SMS Verification Code Login

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Used for user login via SMS verification code. After a successful login, an access token and a refresh token are returned. This API is an open API; it does not verify the Token or the signature, and the Authorization and X-Palm-Openapi-Token fields are not required in the HTTP header.

Default API request frequency limit: 20 times/second/AppId.

Note: This API requires the X-Palm-Appid field in the HTTP request header. The verification code can be used only once, and SessionId expires immediately after successful validation.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: LoginPalmMaSmsCode.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
SmsCode	No	String	SMS verification code (verification is required every time, and the code can be used only once). If SMS capability is not configured during deployment, this field does not need to be passed.
SessionId	No	String	The SessionId returned when the verification code was sent (for one-time use; it expires immediately after successful validation). If SMS capability is not configured during deployment, this field does not need to be passed.
UserId	Yes	String	User ID.
PhoneNo	No	String	Phone number (with country code), used to verify against the phone number bound to the user in the backend. If not passed, verification is skipped.
GrantType	No	GrantType	Grant Type. When calling the Palm Application Platform open APIs, you must use client_credential. Valid values: - client_credential_user: Applicable to scenarios where a third-party platform integrates the Mobile Palm Registration SDK, that is: a. The mobile end uses the SDK to initiate registration or obtain the liveness video upload URL; b. The third-party server needs to apply for an access credential for a specified user for use by the SDK; c. In this case, the UserId field must be passed at the same time. - client_credential: Applicable to scenarios where a common server calls the open APIs, that is: a. Under this type, no specific user is bound; only the application-level key is used to obtain the access credential; b. The UserId field does not need to be passed. The default type when not passed is client_credential_user. See the GrantType enum.

3. Output Parameters

Parameter Name	Type	Description
AccessToken	String	Access token (short-term validity, e.g., 2 hours). Subsequent requests of the current session need to carry this token in the HTTP request header "X-Palm-Openapi-Token".
AccessTokenExpireTime	Timestamp	Access token expiration time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
RefreshToken	String	Refresh token (long-term validity, e.g., 30 days), used to refresh the access token.
RefreshTokenExpireTime	Timestamp	Refresh token expiration time in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
CheckError	LoginPalmMaSmsCodeResponseCheckError	Verification error. See the LoginPalmMaSmsCodeResponseCheckError enum. The default value check_error_unspecified indicates success.
UserIdList	Array of String	User ID list (desensitized), returned only when GrantType is client_credential_user.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: LoginPalmMaSmsCode
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223

{
  "SmsCode": "123456",
  "SessionId": "sess_1234567890abcdef",
  "UserId": "user001",
  "GrantType": "client_credential"
}

Output Example

{
  "Response": {
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "AccessTokenExpireTime": "2025-07-03T11:30:15.500Z",
    "RefreshToken": "refresh_token_xxx",
    "RefreshTokenExpireTime": "2025-08-02T09:30:15.500Z",
    "CheckError": "check_error_unspecified",
    "UserIdList": [
      "user001"
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Palm Print Management APIs (Palm Algorithm Platform)

Create Palm Print

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Uploads palm images to create a palm print and returns the PalmId. Two-factor authentication.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: CreatePalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
RgbImage	Yes	Image	RGB image data. See the Image structure.
IrImage	Yes	Image	IR image data. See the Image structure.
PalmDirection	Yes	PalmPaasPalmDirection	Palm direction. See the PalmPaasPalmDirection enum. 1: left hand; 2: right hand.

3. Output Parameters

Parameter Name	Type	Description
PalmId	String	Palm print ID.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: CreatePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "RgbImage": {
    "Data": "... 特征数据，需要base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 1
  },
  "IrImage": {
    "Data": "... 特征数据，需要base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 2
  },
  "PalmDirection": 1
}

Output Example

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.PalmIdEmpty",
      "Message": "掌纹ID为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Bind Palm Print

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Binds a created PalmId to a specified user. Two-factor authentication.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: BindPalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
PalmId	Yes	String	Palm print ID.
IsForce	No	Boolean	Whether to force rebinding.
AlgorithmStrategy	No	AlgorithmStrategy	Algorithm strategy type. See the AlgorithmStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
PalmId	String	The user's palm print ID. If the user has already bound palm print information, the system automatically updates the existing palm print data (the original PalmId remains unchanged) and returns the user's registered PalmId.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: BindPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
  "IsForce": true,
  "AlgorithmStrategy": 2
}

Output Example

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Register Palm Print

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Uploads palm images to create a palm print and binds it to a specified user. Two-factor authentication.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: RegisterPalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
RgbImage	Yes	Image	RGB image data. See the Image structure.
IrImage	Yes	Image	IR image data. See the Image structure.
PalmDirection	Yes	PalmPaasPalmDirection	Palm direction. See the PalmPaasPalmDirection enum.
IsForce	No	Boolean	Whether to force rebinding.
AlgorithmStrategy	No	AlgorithmStrategy	Algorithm strategy type. See the AlgorithmStrategy enum.
HighSimilarityResolutionStrategy	No	HighSimilarityResolutionStrategy	Policy for handling high-similarity users detected during palm registration. See the HighSimilarityResolutionStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
PalmId	String	The user's palm print ID. If the user has already bound palm print information, the system automatically updates the existing palm print data (the original PalmId remains unchanged) and returns the user's registered PalmId.
CheckErrors	Array of Integer	Registration check error list. See the RegisterPalmResponseCheckError enum. Empty indicates successful registration; non-empty indicates registration was rejected. Only when HighSimilarityResolutionStrategy = 2 (REJECT_WITH_SIMILAR_USERS), the rejection reason is returned through this field instead of an error.
HighSimilarityUserIdList	Array of String	List of high-similarity user IDs. Has a value when CheckErrors contains 1 (HIGH_SIMILARITY_DETECTED).
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: RegisterPalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "RgbImage": {
    "Data": "... 特征数据，需要base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 1
  },
  "IrImage": {
    "Data": "... 特征数据，需要base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 2
  },
  "PalmDirection": 1,
  "IsForce": false,
  "AlgorithmStrategy": 2,
  "HighSimilarityResolutionStrategy": 2
}

Output Example

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "CheckErrors": [],
    "HighSimilarityUserIdList": [],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Output example (registration rejected, high-similarity users returned)

{
  "Response": {
    "PalmId": "",
    "CheckErrors": [1],
    "HighSimilarityUserIdList": ["user002", "user003"],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Mobile Palm Registration Search

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Uploads RGB+IR palm images, performs a 1:N search for users, and returns additional verification information.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: SearchMobilePalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
ProductVersion	No	String	Algorithm version of the palm scan product, provided by the integrating product, e.g., v20250715.
RgbImage	Yes	Image	RGB image data. See the Image structure.
IrImage	No	Image	IR image data, used to supplement the palm database after subsequent additional verification passes. See the Image structure.
PalmDirection	Yes	PalmPaasPalmDirection	Palm direction. See the PalmPaasPalmDirection enum. 1: left hand; 2: right hand.

3. Output Parameters

Parameter Name	Type	Description
VerifyInfo	VerifyInfo	Additional verification information. See the VerifyInfo structure.
PalmId	String	Palm print ID.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SearchMobilePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ProductVersion": "v20250715",
  "RgbImage": {
    "Data": "base64encodedRgbImageData...",
    "ImageType": 1,
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ]
  },
  "IrImage": {
    "Data": "base64encodedIrImageData...",
    "ImageType": 2,
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ]
  },
  "PalmDirection": 1
}

Output Example

{
  "Response": {
    "VerifyInfo": {
      "NeedVerify": true,
      "UserId": "user001",
      "VerifyId": "a1b2c3d4-5678-9abc-def0-1234567890ab",
      "VerifyType": 3,
      "HighSimilarityUserIdList": []
    },
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InternalError",
      "Message": "内部错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

User Additional Verification

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Completes user identity additional verification and binds the palm print.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: Verify.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
VerifyId	Yes	String	Additional verification ID. Source: VerifyInfo.VerifyId returned by SearchMobilePalm.
UserId	Yes	String	Unique identifier of the user undergoing additional verification.
VerifyResult	Yes	VerifyResult	Additional verification result. See the VerifyResult enum.
AlgorithmStrategy	No	AlgorithmStrategy	Algorithm strategy type. See the AlgorithmStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
VerifyInfo	VerifyInfo	Additional verification information, returned when further additional verification is needed. See the VerifyInfo structure.
PalmId	String	The palm print ID of the user, returned when additional verification succeeds.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: Verify
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "VerifyId": "a1b2c3d4-5678-9abc-def0-1234567890ab",
  "UserId": "user001",
  "VerifyResult": 1,
  "AlgorithmStrategy": 2
}

Output Example

{
  "Response": {
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Output example (further additional verification needed)

{
  "Response": {
    "VerifyInfo": {
      "NeedVerify": true,
      "UserId": "user002",
      "VerifyId": "b2c3d4e5-6789-abcd-ef01-234567890abc",
      "VerifyType": 1,
      "HighSimilarityUserIdList": ["user003", "user004"]
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserIdEmpty",
      "Message": "用户ID为空"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Delete Palm Print

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Deletes the palm print information of a specified user.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DeletePalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
PalmDirectionList	Yes	Array of PalmPaasPalmDirection	List of palm print directions. Both left and right hands can be passed at the same time, or a single left or right hand.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DeletePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001",
  "PalmDirectionList": [1, 2]
}

Output Example

{
  "Response": {
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Palm Print

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Queries the palm print information of a specified user.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribePalm.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
UserId	Yes	String	Unique user identifier.
UserToken	No	String	User token. The client SDK queries through the token.

3. Output Parameters

Parameter Name	Type	Description
LeftPalm	PalmPaasPalmInfo	Left-hand palm print information. See the PalmPaasPalmInfo structure.
RightPalm	PalmPaasPalmInfo	Right-hand palm print information. See the PalmPaasPalmInfo structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribePalm
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "LeftPalm": {
      "PalmState": 3,
      "PalmDirection": 1,
      "RegisterTime": 1700000000,
      "RegisterType": 1
    },
    "RightPalm": {
      "PalmState": 3,
      "PalmDirection": 2,
      "RegisterTime": 1700000100,
      "RegisterType": 1
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "用户不存在"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Synchronize Palm Print Features

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Synchronizes palm print features.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: SynchronizePalmFeature.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
ProductVersion	Yes	String	Product version to synchronize, e.g., v20250715. This version number must match the version number on the device.
QueryPosition	Yes	String	Current synchronization position. Pass an empty string for the first time; for subsequent requests, use the QueryPosition data in the response.
DeviceId	Yes	String	Device ID. Currently used only for troubleshooting.
DisableFeature	No	Boolean	Disables returning the feature value. Default is false (returned); when true, it is not returned.
Operations	No	Array of PalmPaasOperation	Filters by operation type. When empty, no filtering is applied and all statuses are returned; for example, passing [1] returns only new-feature events. See the PalmPaasOperation enum.

3. Output Parameters

Parameter Name	Type	Description
PalmFeatureDetailList	Array of PalmFeatureDetail	Palm print feature detail list. See the PalmFeatureDetail structure.
HasMore	HasMoreType	Whether there is more data. See the HasMoreType enum. 1: no more data; 2: more data available and synchronization can continue. Other states may be added in the future; if so, the documentation will be updated accordingly.
QueryPosition	String	Current synchronization position.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: SynchronizePalmFeature
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ProductVersion": "v1.0",
  "QueryPosition": "",
  "DeviceId": "X8AZ112D4646978SKAP3ZX3",
  "DisableFeature": false
}

Output Example

{
  "Response": {
    "PalmFeatureDetailList": [
      {
        "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
        "Status": 1,
        "ImageType": 1,
        "Feature": {
          "FeatureValue": "... 特征数据，需要base64",
          "FeatureType": 1,
          "FeatureDigest": "md5hash",
          "FeatureDimension": 128
        },
        "PalmDirection": 1,
        "PalmDataVersion": 100,
        "UserId": "user001",
        "Operation": 1
      }
    ],
    "HasMore": 2,
    "QueryPosition": "position_abc",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

Query Product Version List

1. API Description

Request endpoint: open.intl.palm.tencent.com

Interface description: Queries the product version list.

Default API request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. Value for this API: DescribeVersionList.
Version	Yes	String	Common parameter. Value for this API: 2025-07-15.
ProductName	Yes	String	Product name. For the Standard edition, it is fixed as: standard.

3. Output Parameters

Parameter Name	Type	Description
VersionList	Array of ProductVersionInfo	Version information list. See the ProductVersionInfo structure.
RequestId	String	Unique request ID, returned for every request.

4. Example

Input Example

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
X-TC-Action: DescribeVersionList
X-TC-Timestamp: 1704067200
X-TC-Version: 2025-07-15
X-TC-Nonce: b6a5c4e3a2b1c0d9e8f7a6b5c4d3e2f1
X-Palm-AppId: 223
X-Palm-Openapi-Token: **************************************
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxx/2025-07-15/palm/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx

{
  "ProductName": "standard"
}

Output Example

{
  "Response": {
    "VersionList": [
      {
        "ProductVersion": "v20250715",
        "ProductVersionCreateTime": 1700000000,
        "Status": 1,
        "OldProductName": ""
      },
      {
        "ProductVersion": "v20250801",
        "ProductVersionCreateTime": 1700100000,
        "Status": 2,
        "OldProductName": "standard_v1"
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error output example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "参数取值错误"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

---

---

Data Structures

Common Business Structures

PalmInfo

Single palm registration information.

Name	Type	Description
PalmState	PalmState	Palm state.
RegisterType	RegisterType	Registration method.
PreRegisterTime	Timestamp	Mobile Palm Registration Time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
RegisterTime	Timestamp	Palm registration completion time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
ExpireTime	Timestamp	Palm print expiration time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

TimeRule

Name	Type	Description
AllowDateRange	DateRange	Allowed verification date range. Empty means no restriction.
DisallowDateList	Date[]	List of dates on which verification is not allowed
AllowDayOfWeekList	DayOfWeek[]	Valid days of each week
AllowTimePeriodList	TimePeriod[]	Allowed access time periods each day

DateRange

Name	Type	Description
StartDate	Date	Start date
EndDate	Date	End date

Date

Name	Type	Description
Year	Integer	Year
Month	Integer	Month
Day	Integer	Day

TimeOfDay

Name	Type	Description
Hours	Integer	Hour
Minutes	Integer	Minute
Seconds	Integer	Second

TimePeriod

Name	Type	Description
StartTime	TimeOfDay	Start time
EndTime	TimeOfDay	End time
MaxVerificationCount	Integer	Allowed number of verifications. 0 means no restriction.

UserRule

Name	Type	Description
UserTags	UserTagInfo[]	User tag list
UserInfos	UserInfo[]	User information list

UserTagInfo

Name	Type	Description
UserTagId	String	Unique user tag identifier
UserTagName	String	User tag name

UserInfo

Name	Type	Description
UserId	String	Unique user identifier
UserName	String	User name

OrderBy

Sorting condition.

Name	Type	Description
Field	VerificationRecordOrderField	Sorting field
Order	SortOrder	Sort order

Image

Image.

Name	Type	Description
Data	String	Image data, requires base64.
ThreePointList	Array of Pointf	Three-point data.
ImageType	ImageType	Image type. See the ImageType enum.
DataDigest	String	Md5 computed on the image data.

Pointf

Point.

Name	Type	Description
PointX	Float	X-axis coordinate.
PointY	Float	Y-axis coordinate.

Feature

Feature.

Name	Type	Description
FeatureValue	String	Feature value.
FeatureType	FeatureType	Feature type. See the FeatureType enum.
FeatureDigest	String	Feature digest.
FeatureDimension	Integer	Dimension of the feature value.

VerifyInfo

Additional verification information.

Name	Type	Description
NeedVerify	Boolean	Whether additional verification is required. The VerifyInfo information is meaningful only when true is returned here.
UserId	String	ID of the user undergoing additional verification.
VerifyId	String	Additional verification ID.
VerifyType	VerifyType	Additional verification type. See the VerifyType enum.
HighSimilarityUserIdList	Array of String	Returned when the additional verification type is high-similarity verification; indicates the list of high-similarity user IDs requiring additional verification.

PalmFeatureDetail

Palm print feature details.

Name	Type	Description
PalmId	String	Palm print ID.
Status	PalmStatus	Palm print status. See the PalmStatus enum.
ImageType	ImageType	Image type. See the ImageType enum.
Feature	Feature	Feature. See the Feature structure.
PalmDirection	PalmPaasPalmDirection	Palm print direction. See the PalmPaasPalmDirection enum.
PalmDataVersion	Integer	Data version. Each data record contains a version number field, identified by a monotonically increasing integer version. When the data content changes, its version number automatically increments. During data synchronization, the system uses a version comparison mechanism: local data is overwritten only when the locally stored version number is strictly greater than the version number obtained by synchronization.
UserId	String	User ID.
Operation	PalmPaasOperation	Operation type. See the PalmPaasOperation enum.

ProductVersionInfo

Product version information.

Name	Type	Description
ProductVersion	String	Algorithm version of the palm scan product, provided by the integrating product, e.g., v20250715.
ProductVersionCreateTime	Integer	Product version creation time.
Status	Integer	Algorithm version type of the palm scan product. 1: currently used version; 2: version to be upgraded.
OldProductName	String	Original product name.

CustomFieldValueItem

Custom additional verification field value item at the user level.

Name	Type	Description
FieldName	String	Field name, aligned with the FieldName in the tenant's additional verification configuration
FieldValue	String	The actual value the user filled in for this field (digits only)

API-Specific Structures

Palm Print Management APIs

PalmPaasPalmInfo

Single palm registration information returned by the Query Palm Print API (DescribePalm).

Note: This structure is used only for palm print management APIs. It has a different field set from PalmInfo used by user management APIs (no PreRegisterTime; additionally includes PalmDirection / MobileRegisterTime).

Name	Type	Description
PalmState	PalmPaasPalmState	Palm state. See the PalmPaasPalmState enum.
PalmDirection	PalmPaasPalmDirection	Palm direction. See the PalmPaasPalmDirection enum.
RegisterTime	Integer	Registration time, a Unix timestamp in seconds.
ExpireTime	Integer	Palm print expiration time, a Unix timestamp in seconds. Returned only when the user's palm print is in the Mobile Palm Registration Pending Stage (PalmState=2, to be activated); not returned in other states.
MobileRegisterTime	Integer	Mobile Palm Registration Time.
RegisterType	PalmPaasRegisterType	Registration type. See the PalmPaasRegisterType enum.

User Management APIs

CreateUserResponsePartialFailureError

Partial failure error information of the Create User API.

Name	Type	Description
NotExistUserTagIdList	Array of String	List of user tag IDs that do not exist

ModifyUserResponsePartialFailureError

Partial failure error information of the Modify User API.

Name	Type	Description
NotExistUserTagIdList	Array of String	List of user tag IDs that do not exist

DescribeUserResponseUserTag

Element structure of the output parameter UserTagList of the Query User (DescribeUser) API.

Field Name	Type	Description
UserTagId	String	User tag ID
UserTagName	String	User tag name

DescribeUserListResponseUser

Element structure of the output parameter UserList of the Query User Information List (DescribeUserList) API.

Field Name	Type	Description
UserId	String	Unique user identifier
UserName	String	User name
PhoneNo	String	Phone number (with country code)
PhysicalCardNo	String	Physical card number
UserTagList	Array of DescribeUserListResponseUserTag	User tag list. See the DescribeUserListResponseUserTag structure
RegisterType	RegisterType	Primary palm registration type
PalmState	PalmState	Primary palm registration status
PalmDirection	PalmDirection	Primary palm direction
PalmPreRegisterTime	Timestamp	Primary palm pre-registration time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
PalmRegisterTime	Timestamp	Primary palm registration time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
PalmExpireTime	Timestamp	Primary palm feature expiration time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UserState	UserState	User state
AccessScopeSummary	AccessScopeSummary	Access scope summary
CreatedTime	Timestamp	User creation time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	User last update time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

DescribeUserListResponseUserTag

Element structure of the output parameter UserList[i].UserTagList of the Query User Information List (DescribeUserList) API.

Field Name	Type	Description
UserTagId	String	User tag ID
UserTagName	String	User tag name

User Tag Management APIs

DescribeUserTagListResponseUserTagItem

Element structure of the output parameter UserTagList of the Query User Tag List (DescribeUserTagList) API.

Field Name	Type	Description
UserTagId	String	Tag ID
UserTagName	String	Tag name
UserCount	Integer	Number of users associated with the tag
ParentTagId	String	Parent tag ID. Empty indicates a top-level tag
Level	Integer	Hierarchy depth: 0=L1 (top level), 1=L2 (level 2), 2=L3 (level 3)
ChildrenCount	Integer	Number of direct child tags
PathNodes	Array of UserTagNode	Complete hierarchy path from the root tag to the current tag, returned in parent-to-child order. See the UserTagNode structure.
CreatedTime	Timestamp	Creation time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	Last update time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

UserTagNode

User tag hierarchy path node structure, used to represent the complete hierarchy path from the root tag to the current tag.

Field Name	Type	Description
UserTagId	String	User tag ID
UserTagName	String	User tag name
Level	Integer	Tag level: 0=L1 (top level), 1=L2 (level 2), 2=L3 (level 3)

UserTag

User tag information structure.

Field Name	Type	Description
UserTagId	String	User tag ID
UserTagName	String	User tag name
PathNodes	Array of UserTagNode	Complete hierarchy path from the root tag to the current tag, returned in parent-to-child order.

UserTagTreeNode

Tag tree node structure, used for the output of the Query User Tag Tree Structure (DescribeUserTagTree) API.

Field Name	Type	Description
UserTagId	String	Tag ID
UserTagName	String	Tag name
UserCount	Integer	Number of users associated with the tag
Level	Integer	Hierarchy depth: 0=L1, 1=L2, 2=L3
ParentTagId	String	Parent tag ID. Empty for top-level tags
Children	Array of UserTagTreeNode	Child tag nodes

User Access Scope

AccessScopeItem

Element structure of the output parameter AccessScopeList of the Query User Access Scope (DescribeUserAccessScope) API.

Field Name	Type	Description
SceneId	String	Scene ID
SceneName	String	Scene name
SceneGroupId	String	Scene group ID
SceneGroupName	String	Scene group name
DeviceSn	String	Device SN (empty when no device is bound)
DeviceName	String	Device name (empty when no device is bound)
VerifyRules	Array of VerifyRuleInfo	Bound verification rule list (empty array when no rule is bound)

VerifyRuleInfo

Verification rule information structure.

Field Name	Type	Description
VerifyRuleId	String	Verification rule ID
VerifyRuleName	String	Verification rule name

AccessScopeSummary

Structure of the output parameter Summary of the Query User Access Scope Summary (DescribeUserAccessScopeSummary) API.

Field Name	Type	Description
SceneGroupCount	Integer	Number of accessible scene groups
SceneCount	Integer	Number of accessible scenes
DeviceCount	Integer	Number of accessible devices

Device Management APIs

DescribeDeviceListResponseDevice

Element structure of the output parameter DeviceList of the Query Device List (DescribeDeviceList) API.

Field Name	Type	Description
DeviceSn	String	Device serial number
DeviceType	String	Device type
DeviceName	String	Device name
HeartbeatTime	Timestamp	Device heartbeat time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
ModuleHeartbeatTime	Timestamp	Module heartbeat time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
SystemVersion	String	System version
AppVersion	String	Application version
ModuleType	String	Module type
ModuleVersion	String	Module version
ModuleExpireTime	Timestamp	Module expiration time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
Status	DeviceStatus	Real-time device status
SceneId	String	Bound scene ID
SceneName	String	Bound scene name
CreatedTime	Timestamp	Device creation time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	Last update time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

DescribeDeviceEmergencyStatusResponseDeviceEmergencyStatus

Element structure of the output parameter DeviceEmergencyStatusList of the Query Device Emergency Status (DescribeDeviceEmergencyStatus) API.

Field Name	Type	Description
DeviceSn	String	Device serial number
EmergencyStatus	EmergencyStatus	Device emergency status. See the EmergencyStatus enum

SendEmergencyCommandResponseFailedDevice

Element structure of the output parameter FailedDeviceList of the Send Emergency Control Command (SendEmergencyCommand) API.

Field Name	Type	Description
DeviceSn	String	Device serial number
ErrorMessage	String	Failure reason

Scene Management APIs

DescribeSceneListResponseSceneItem

Element structure of the output parameter SceneList of the Query Scene List (DescribeSceneList) API.

Field Name	Type	Description
SceneId	String	Scene ID
SceneName	String	Scene name
SceneGroupId	String	ID of the scene group it belongs to
SceneGroupName	String	Name of the scene group it belongs to
DeviceSn	String	Bound device serial number
DeviceName	String	Bound device name
ScenarioStrategy	ScenarioStrategy	Scene strategy
VerifyRuleIdList	Array of String	List of associated verification rule IDs
CreatedTime	Timestamp	Creation time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	Last update time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

DescribeSceneGroupListResponseSceneGroupItem

Element structure of the output parameter SceneGroupList of the Query Scene Group List (DescribeSceneGroupList) API.

Field Name	Type	Description
SceneGroupId	String	Scene group ID
SceneGroupName	String	Scene group name
ParentSceneGroupId	String	Parent scene group ID. This value is "0" for top-level scene groups
ParentSceneGroupName	String	Parent scene group name. This value is empty for top-level scene groups
SceneCount	Integer	Number of direct child scenes
ChildGroupCount	Integer	Number of direct child scene groups
CreatedTime	Timestamp	Creation time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	Last update time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

Verification Record APIs

DescribeVerificationRecordListResponseVerificationRecord

Element structure of the output parameter VerificationRecordList of the Query Verification Record List (DescribeVerificationRecordList) API.

Field Name	Type	Description
UserId	String	User ID
UserName	String	User name
VerificationTime	Timestamp	Verification time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
VerificationMedium	VerificationMedium	Verification medium
DeviceSn	String	Device SN
SceneId	String	Scene ID
SceneName	String	Scene name
VerifierId	String	Verifier ID
VerifierName	String	Verifier name
SceneGroupId	String	Scene group ID
SceneGroupName	String	Scene group name
Source	VerificationRecordSource	Verification record source
AccessDenied	Boolean	Whether the verification result is rejected. Returned (with the value true) only when verification fails
Reason	String	Verification description

Verification Rule APIs

DescribeVerifyRuleListResponseVerifyRuleItem

Element structure of the output parameter VerifyRuleList of the Query Verification Rule List (DescribeVerifyRuleList) API.

Field Name	Type	Description
VerifyRuleId	String	Globally unique verification rule ID
VerifyRuleName	String	Verification rule name
EnableTimeRule	Boolean	Whether to enable the time rule
TimeRule	TimeRule	Time rule. See the TimeRule structure
EnableUserRule	Boolean	Whether to enable the user rule
UserRule	UserRule	User rule. See the UserRule structure
EnableWebhookRule	Boolean	Whether to enable the webhook rule
BindSceneIdList	Array of String	List of bound scene IDs
CreatedTime	Timestamp	Creation time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	Last update time in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

Enum Types

PalmState

Palm state.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
unregistered	Not registered
pre_registered	Pre-registered
registered	Registered
abnormal	Abnormal

UserState

Return type: string; the value is one of the enum value names in the table below.
The user state represents the status of the user's two palms, without distinguishing pre-registration.

Enum Value	Description
user_state_unspecified	Unspecified
both_unregistered	Unregistered: neither palm has been registered
not_activated	Not Activated: after Mobile Palm Registration, no activated palm
user_state_abnormal	Abnormal: the user state is abnormal (at least one palm is abnormal and there is no activated palm)
left_valid	Left Valid: the left palm is activated while the right palm is not activated
right_valid	Right Valid: the right palm is activated while the left palm is not activated
both_valid	Both Valid: both palms are activated

VerificationMedium

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
verification_medium_unspecified	Medium unspecified
palm	Palm scan
card	Card
code	Code

NotifyQrCodeScanEventRequestQrCodeScanEventType

QR code scan event type. The value of the input parameter EventType of the QR Code Scan Event Notification (NotifyQrCodeScanEvent) API.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
qrcode_scan_event_type_unspecified	Event type unspecified, equivalent to scanned
scanned	The user has scanned the code

DayOfWeek

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
NONE	Unspecified
MONDAY	Monday
TUESDAY	Tuesday
WEDNESDAY	Wednesday
THURSDAY	Thursday
FRIDAY	Friday
SATURDAY	Saturday
SUNDAY	Sunday

ScenarioStrategy

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
Default	Default
DemoOnDeviceRecognition100	100 User Demo On-device Recognition
AccessOnDeviceRecognition50k	50k User Access Control On-device Recognition
EKYCCloudRecognition1M	1M User eKYC Cloud Recognition
EKYCHybridRecognition1M	1M User eKYC Hybrid Recognition

RegisterType

Registration type.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
register_type_unspecified	Registration type unspecified
device	Device registration
mobile	Mobile registration

PalmDirection

Palm print direction.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
palm_direction_unspecified	Palm print direction unspecified
left	Left hand
right	Right hand

AdditionalVerifyMethod

Additional verification method.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
additional_verify_method_unspecified	Unspecified; falls back to the last four digits of the phone number
phone_no	Last four digits of the phone number
custom_field	Custom field numeric verification
qr_code	QR code tap-code verification

VerificationRecordSource

Verification record source.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
verification_record_source_unspecified	Source unspecified
device	Reported by the device side
mobile	Reported by the mobile side
server	Reported by the server side
h5	Reported by H5
wechat	Reported by WeChat Mini Program

DeviceStatus

Device status.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Device status unspecified
1	Online
2	Offline

EmergencyStatus

Emergency status, a top-level standalone enum. The value of the output parameters TenantEmergencyStatus and DeviceEmergencyStatusList[i].EmergencyStatus of the Query Device Emergency Status (DescribeDeviceEmergencyStatus) API.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Emergency status unspecified (normal state)
1	Emergency lockdown
2	Emergency opening

EmergencyCommandScope

Emergency command scope, a top-level standalone enum. The value of the input parameter Scope of the Send Emergency Control Command (SendEmergencyCommand) API.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Scope unspecified
1	All devices
2	Specified SN list

SendEmergencyCommandRequestEmergencyCommandType

Emergency command type, an enum embedded in SendEmergencyCommandRequest. The value of the input parameter CommandType of the Send Emergency Control Command (SendEmergencyCommand) API.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Emergency command operation type unspecified
1	Block all (block)
2	Open all (open)
3	Restore block all (reset_block)
4	Restore open all (reset_open)

VerificationRecordOrderField

Verification record sorting field.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
verification_record_order_field_unspecified	Unspecified
verification_time	Verification time

SortOrder

Sort order.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
sort_order_unspecified	Unspecified
asc	Ascending
desc	Descending

ImageType

Image type.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	Rgb
2	Ir

PalmPaasPalmDirection

Palm direction.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	Left hand
2	Right hand

FeatureType

Feature type.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	float32
2	int8
3	int7

PalmStatus

Palm print data status.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	Normal
2	Deleted

PalmPaasOperation

Operation type.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	Create
2	Update
3	Delete

PalmPaasPalmState

Palm state.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	Pending capture: the user exists but has not registered a palm
2	Pending activation: the user has activated Mobile Palm Registration but has not yet bound a palm
3	Activated: the user has bound a palm through an offline device
100	First registration, waiting for additional verification
101	High similarity state
102	The user was incorrectly bound
103	The user has enabled Mobile Palm Registration, but another user found this user in the Mobile Palm Registration search when binding a palm

PalmPaasRegisterType

Registration type.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Unspecified
1	Device registration
2	Mobile registration

HasMoreType

Whether there is more data.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
1	No more data
2	More data available

AlgorithmStrategy

Algorithm strategy type. The Standard edition supports strategies A and B; the Max edition supports strategies A, B, C, and D.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Unspecified, default value
1	Strategy A: 100-user demo on-device recognition
2	Strategy B: 10k-user access control and attendance on-device recognition
3	Strategy C: 1M-user eKYC cloud recognition
4	Strategy D: 1M-user eKYC hybrid recognition

HighSimilarityResolutionStrategy

Policy for handling high-similarity users detected during palm registration.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Unspecified. Default behavior: registration is rejected directly with an error returned
1	Reject registration and return an error
2	Reject registration without returning an error; the list of high-similarity user IDs is returned in the response for the caller to decide

RegisterPalmResponseCheckError

Registration check error code, an enum embedded in RegisterPalmResponse. The value of the output parameter CheckErrors of the Register Palm Print (RegisterPalm) API.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Unspecified
1	High-similarity user detected

VerifyType

Additional verification type.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Unspecified, default value
1	High-similarity additional verification
2	The first-level threshold is not met, but the second-level threshold is met, and the auxiliary background image comparison threshold is not passed
3	Mobile Palm Registration Additional Verification
4	New registration type additional verification

VerifyResult

Additional verification result. The value of the input parameter VerifyResult of the User Additional Verification (Verify) API.

Return type: integer; the value is one of the enum values in the table below.

Enum Value	Description
0	Unspecified, default value
1	Success
2	Failure

GrantType

Grant Type.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
grant_type_unspecified	Unspecified, equivalent to client_credential_user by default
client_credential_user	Applicable to scenarios where a third-party platform integrates the Mobile Palm Registration SDK; in this case, the UserId field must be passed at the same time
client_credential	Applicable to scenarios where a common server calls the open APIs; the UserId field does not need to be passed. This type must be used when calling the Palm Application Platform open APIs

LoginPalmMaSmsCodeResponseCheckError

Login verification error. The value of the output parameter CheckError of the SMS Verification Code Login (LoginPalmMaSmsCode) API.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
check_error_unspecified	Unspecified; passes by default
phone_already_bind	The phone number is already bound to a user

QrCodeScanState

QR code scan state.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
pending	Waiting for the code to be scanned
scanned	Code scanned, waiting for information to be filled in
success	QR Code Palm Registration succeeded
failed	QR Code Palm Registration failed
expired	The QR Code Palm Registration session has expired

ResponseFormat

Response data format.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
metadata	Returns metadata (default, recommended); returns fields other than SessionUrl and SessionImage
url	Returns the QR code URL; returns SessionId, ExpireTime, and SessionUrl
image	Returns the QR code image (PNG); returns SessionId, ExpireTime, and SessionImage

QrCodeSessionType

QR code session purpose.

Return type: string; the value is one of the enum value names in the table below.

Enum Value	Description
scan_register	QR Code Palm Registration: the device generates a QR code → the user scans the code → palm registration and binding
tap_register	Tap-code palm registration: the app generates a QR code (carrying user information) → the device scans the code → palm registration and binding
tap_verify	Tap-code additional verification: the app generates a QR code (carrying user information) → the device scans the code → identity verification

General Structures

Error

Name	Type	Description
Code	String	Error code
Message	String	Error message

---

Error Codes

Function Description

If the Error field exists in the return result, the API call failed. For example:

{
  "Response": {
    "Error": {
      "Code": "AuthFailure.SignatureFailure",
      "Message": "The provided credentials could not be validated. Please check your signature is correct."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

The Code in Error indicates the error code, and Message indicates the specific information about the error.

Common Error Codes

Error Code	Description
InvalidParameter	Parameter error (including parameter format, type, and other errors)
InvalidParameterValue	Invalid parameter value
MissingParameter	Missing parameter error; a required parameter was not provided
UnknownParameter	Unknown parameter error, caused by passing extra undefined parameters
AuthFailure	CAM signature/authentication error
InternalError	Internal error. Businesses must uniformly use InternalError or the InternalError.xxx form to represent internal errors
InvalidAction	The API does not exist
UnauthorizedOperation	Unauthorized operation
RequestLimitExceeded	The number of requests exceeds the frequency limit
NoSuchVersion	The API version does not exist
UnsupportedRegion	The API does not support the specified region
UnsupportedOperation	Operation not supported
ResourceNotFound	Resource does not exist
LimitExceeded	Quota limit exceeded
ResourceUnavailable	Resource unavailable
ResourceInsufficient	Insufficient resources
ResourceExhausted	Insufficient resource quota or rate limit reached
FailedOperation	Operation failed
ResourceInUse	Resource in use
DryRunOperation	DryRun operation, which means the request would have succeeded, except that an extra DryRun parameter was passed
ResourcesSoldOut	Resource sold out
OperationDenied	Operation denied

Business error codes

Error Code	Description
InvalidParameterValue.FiltersLimitExceed	The number of filters exceeds the limit
InvalidParameterValue.PageLimitExceed	Pagination parameter exceeds the limit
InvalidParameterValue.PageTokenExpired	Pagination token expired
InvalidParameterValue.PageTokenSignatureFailure	Pagination token signature verification failed
InvalidParameterValue.PageTokenQueryMismatch	Pagination token query condition mismatch
ResourceNotFound.TenantNotFound	The specified tenant does not exist, or you do not have permission to access this tenant
InvalidParameterValue.UserIdEmpty	User ID is empty
InvalidParameterValue.UserIdLengthNotAllowed	User ID length does not meet the limit
InvalidParameterValue.UserIdShouldOnlyContainLettersAndDigits	User ID can only contain letters and digits
InvalidParameterValue.UserIdShouldOnlyContainGraphicsAscii	User ID can only contain ASCII graphic characters (ASCII range: 33-126)
InvalidParameterValue.UserNameEmpty	User name is empty
InvalidParameterValue.UserNameLengthNotAllowed	User name length does not meet the limit
InvalidParameterValue.UserNameOrPasswordEmpty	User name or password is empty
InvalidParameterValue.PhoneNoEmpty	Phone number is empty
InvalidParameterValue.PhoneNoLengthNotAllowed	Phone number length does not meet the limit
InvalidParameterValue.InvalidPhoneNo	Phone number format is incorrect
InvalidParameterValue.PhysicalCardNoLengthNotAllowed	Physical card number length does not meet the limit
InvalidParameterValue.PhysicalCardNoShouldOnlyContainLettersAndDigits	Physical card number can only contain letters and digits
InvalidParameterValue.PalmIdEmpty	Palm ID is empty
InvalidParameterValue.SessionIdEmpty	Session ID is empty
InvalidParameterValue.SessionIdLengthNotAllowed	Session ID length does not meet the limit
InvalidParameterValue.SessionNotExist	Session does not exist
InvalidParameterValue.InvalidUserId	User ID format is incorrect; it can only contain digits, letters, and hyphens
InvalidParameterValue.RegisterTypeNotAllowed	Registration type does not meet the limit
InvalidParameterValue.UserTagIdEmpty	User tag ID is empty
InvalidParameterValue.UserTagIdLengthNotAllowed	User tag ID length does not meet the limit
InvalidParameterValue.InvalidUserTagId	User tag ID format is incorrect
InvalidParameterValue.UserTagNameEmpty	User tag name is empty
InvalidParameterValue.UserTagNameLengthNotAllowed	User tag name length does not meet the limit
InvalidParameterValue.DeviceSnEmpty	Device SN is empty
InvalidParameterValue.DeviceSnLengthNotAllowed	Device SN length does not meet the limit
InvalidParameterValue.DeviceSnShouldOnlyContainLettersAndDigits	Device SN can only contain letters and digits
InvalidParameterValue.InvalidDeviceSn	Device SN format is incorrect
InvalidParameterValue.DeviceNameEmpty	Device name is empty
InvalidParameterValue.DeviceNameLengthNotAllowed	Device name length does not meet the limit
InvalidParameterValue.ErrDeviceNameInvalid	Device name format is incorrect
InvalidParameterValue.SceneIdEmpty	Scene ID is empty
InvalidParameterValue.SceneIdLengthNotAllowed	Scene ID length does not meet the limit
InvalidParameterValue.SceneIdShouldOnlyContainLettersAndDigits	Scene ID can only contain letters and digits
InvalidParameterValue.InvalidSceneId	Scene ID format is incorrect
InvalidParameterValue.SceneNameEmpty	Scene name is empty
InvalidParameterValue.SceneNameLengthNotAllowed	Scene name length does not meet the limit
InvalidParameterValue.SceneGroupIdEmpty	Scene group ID is empty
InvalidParameterValue.SceneGroupIdLengthNotAllowed	Scene group ID length does not meet the limit
InvalidParameterValue.SceneGroupIdShouldOnlyContainLettersAndDigits	Scene group ID can only contain letters and digits
InvalidParameterValue.InvalidSceneGroupId	Scene group ID format is incorrect
InvalidParameterValue.SceneGroupNameEmpty	Scene group name is empty
InvalidParameterValue.SceneGroupNameLengthNotAllowed	Scene group name length does not meet the limit
InvalidParameterValue.VerifierIdEmpty	Verifier ID is empty
InvalidParameterValue.VerifierIdLengthNotAllowed	Verifier ID length does not meet the limit
InvalidParameterValue.VerifierIdShouldOnlyContainLettersAndDigits	Verifier ID can only contain letters and digits
InvalidParameterValue.InvalidVerifierId	Verifier ID format is incorrect
InvalidParameterValue.VerifierNameEmpty	Verifier name is empty
InvalidParameterValue.VerifierNameLengthNotAllowed	Verifier name length does not meet the limit
InvalidParameterValue.QrCodeScanSessionIdEmpty	QR Code Palm Registration session ID is empty
InvalidParameterValue.QrCodeScanSessionTtlNotAllowed	QR Code Palm Registration session expected lifetime does not meet the limit
FailedOperation.UserNotExist	The user does not exist
FailedOperation.UserAlreadyExists	The user already exists
FailedOperation.UserIdAlreadyExists	The user ID already exists
FailedOperation.PhoneNoAlreadyExists	The phone number already exists
FailedOperation.UserPalmAlreadyBound	The user's palm is already bound
FailedOperation.SceneNotExist	The scene does not exist
FailedOperation.SceneAlreadyExists	The scene already exists
FailedOperation.SceneGroupNotExist	The scene group does not exist
FailedOperation.SceneGroupAlreadyExists	The scene group already exists
FailedOperation.DuplicateSceneNameInSceneGroup	Duplicate scene name in the scene group
FailedOperation.DuplicateSceneGroupNameInSceneGroup	Duplicate scene group name in the scene group
FailedOperation.DeviceSceneBindingLimitExceeded	Device-scene binding limit exceeded
FailedOperation.QrCodeExpired	The palm registration QR code has expired
FailedOperation.QrCodeFinished	The palm registration QR code has been used
FailedOperation.QrCodeStatusInvalid	The palm registration QR code status is invalid
FailedOperation.BindPalmUserIdAndUserNameNotMatch	The user ID and user name of the palm print being bound do not match
FailedOperation.VerifyRuleAlreadyExist	The verification rule already exists
FailedOperation.VerifyRuleNotExist	The verification rule does not exist
FailedOperation.DeviceNotExist	The device does not exist
FailedOperation.DeviceAlreadyExists	The device already exists
FailedOperation.DeviceCannotBeDeletedWhenBindWithScene	The device cannot be deleted while bound to a scene
FailedOperation.DeviceNotBoundWithScene	The device is not bound to a scene
FailedOperation.UserTagNotExist	The user tag does not exist
FailedOperation.UserTagAlreadyExists	The user tag already exists
FailedOperation.UserTagNameAlreadyExists	The user tag name already exists
InternalError.GetPaaSChannelFailed	Failed to get the PaaS channel
InternalError.UpdateUserPalmFailed	Failed to update the user's palm
InternalError.CreateUserTokenFailed	Failed to create the user token
InternalError.BindUserPalmByPaaSChannelFailed	Failed to bind the user's palm through the PaaS channel
InternalError.DeleteUserPalmByPaaSChannelFailed	Failed to delete the user's palm through the PaaS channel
InternalError.DescribeUserPalmByPaaSChannelFailed	Failed to query the user's palm through the PaaS channel
InternalError.CreateAccessTokenFailed	Failed to create the open API access token
InternalError.CreateDeviceAccessTokenFailed	Failed to create the open API device access token
InternalError.DescribeSecretKeyFailed	Failed to query the open API access key
FailedOperation.MemberNotExist	The member does not exist
FailedOperation.MemberAlreadyExists	The member already exists
FailedOperation.MemberLoginExpired	The member login has expired
FailedOperation.NoAvailableVersion	No available version
FailedOperation.UnknownImageType	Unknown image type
FailedOperation.PicInconsistent	Image MD5 inconsistent
FailedOperation.LivenessCheckNoPass	Liveness detection failed
FailedOperation.QualityCheckNoPass	Quality detection failed
FailedOperation.LivenessWithVideoCheckNoPass	Liveness video detection failed
FailedOperation.PalmIdNoExistInCache	The palm ID does not exist
FailedOperation.AlreadyBind	Already bound
FailedOperation.ThirdAuthFail	Authentication failed
FailedOperation.NoFoundDataInDb	No data found in the database
FailedOperation.NoSearchUser	No matching user found in the Palm Print Search Hot Library
FailedOperation.UnknownVerifyType	Unknown verification type
FailedOperation.TableCapacityFull	Insufficient system capacity
FailedOperation.VerifyUserIdNoMatch	Verification user ID does not match
FailedOperation.VerifyIdExpire	Verification ID expired
FailedOperation.PalmIdAlreadyExist	The palm ID already exists
FailedOperation.HighSimilarity	A high-similarity palm exists
FailedOperation.PalmCapacityFull	The capacity of the user's Palm Print Search Hot Library has reached the limit
FailedOperation.LiveImageAlreadyExist	The image already exists
FailedOperation.QrCodeUserIdNotMatchSession	The QR Code Palm Registration user ID does not match the session
LimitExceeded.VerifyRuleUserTagsExceedLimit	The number of tags associated with the verification rule exceeds the limit
LimitExceeded.VerifyRuleUsersExceedLimit	The number of users associated with the verification rule exceeds the limit
FailedOperation.MemberDisabled	The member has been disabled
OperationDenied.TenantDisabled	The tenant has been disabled and cannot log in
InvalidParameterValue.SmsCodeEmpty	SMS verification code is empty
InvalidParameterValue.RefreshTokenEmpty	Refresh token is empty
InvalidParameterValue.SmsCodeNotMatch	Incorrect SMS verification code
InvalidParameterValue.PhoneNoNotMatch	The phone number does not match the verification code session
ResourceNotFound.SmsSessionNotExist	The verification code session does not exist or has expired
ResourceNotFound.RefreshTokenNotExist	The refresh token does not exist or has expired
ResourceExhausted.SmsResendTooFrequent	SMS verification codes are being sent too frequently
ResourceExhausted.SmsMaxVerifyAttempts	Too many verification code attempts
FailedOperation.SmsSendFailed	Failed to send the SMS