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

Tencent PalmAI Server-Side API Reference

Version History

Version	Release Date	Update Description
v2.4.0	2026-08-12	New Interfaces • Added the RegisterPalm (register palm print) interface, which uploads a palm image to create a palm print and bind it to a specified user. Two-factor authentication Interface Parameter Changes • The description of the IrImage parameter of the CreatePalm interface is corrected from "infrared image data" to "IR image data" • The description of the IrImage parameter of the SearchMobilePalm interface is corrected from "infrared image data" to "IR image data" • The CustomFieldValue parameter of the CreateUser and ModifyUser interfaces is deprecated. A new CustomFieldValueList parameter (Array of CustomFieldValueItem) is added, supporting configuration of multiple custom additional verification field values • The CustomFieldValue field in the DescribeUser interface response is deprecated. A new CustomFieldValues field (Array of CustomFieldValueItem) is added • The DescribeUserList interface adds the SkipTotalCount (skip total count) and SceneId (filter by scene ID) input parameters, and the response adds a HasMore field • The DescribeVerificationRecordList interface adds the Source (filter by verification record source) and SkipTotalCount (skip total count) input parameters; the response adds a HasMore field, and the VerificationRecord structure adds the Source, AccessDenied (verification result), and Reason (verification description) fields • The CreateVerificationRecord interface 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 (resolution strategy when a high-similarity user is detected during palm registration: reject_with_error/reject_with_similar_users) • Added the CheckError enum (registration check error code: high_similarity_detected) • Added the VerificationRecordSource enum (verification record source: device/mobile/server/h5/wechat); enum value web renamed to h5 and weixin 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 Interfaces • Added the DescribeUserAccessScope (query user access scope) and DescribeUserAccessScopeSummary (query user access scope summary) interfaces • Added the DescribeUserTagTree (query user tag tree structure) interface Interface Opening • The SendPalmMaSmsCode (send SMS verification code) and LoginPalmMaSmsCode (SMS verification code login) interfaces are opened to external use from internal use, and a new "PalmMa Login Interfaces" category is added • The CreateQrCodeScanSession (create QR Code Palm Registration session) and DescribeQrCodeScanSession (query QR Code Palm Registration session status) interfaces are opened to external use from internal use Interface Parameter Changes • The LoginPalmMaSmsCode interface adds the PhoneNo (phone number validation) and GrantType (grant type) parameters; SmsCode and SessionId are changed to optional • The DescribeQrCodeScanSession interface response adds a PhoneNo (phone number) field • The DescribeQrCodeScanUser interface response adds a PhoneNo (phone number) field • The DescribeUserTag interface response adds the ParentTagId (parent tag ID), Level (level depth), ChildrenCount (number of direct child tags), UserCount (number of users associated with the tag), and PathNodes (level path) fields • The UserTagItem in the DescribeUserTagList interface response 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 level path node) • Added the UserTag common data structure (user tag information, including the PathNodes level 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 DeviceStatus enum serialization was changed from string to integer (int32)
v2.2.0	2026-06-17	Version number upgraded; no interface changes
v2.1.0	2026-05-07	New Interfaces • Added 6 list query interfaces: 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) Interface Parameter Changes • The CreateUser and ModifyUser interfaces add the CustomFieldValue parameter (custom additional verification field value) • The DescribeUser interface response adds a CustomFieldValue field • The DescribeUserList interface adds the PhoneNo, PhysicalCardNo, and UserTagId filter parameters; the response adds the CreatedTime and UpdatedTime fields • The DescribeDeviceList interface is opened to external use, adding the Status, SceneId, and DeviceType filter parameters; the response adds the Status, SceneId, SceneName, CreatedTime, and UpdatedTime fields • The DescribeVerificationRecordList interface adds the SceneGroupIds, SceneGroupName, and OrderBy parameters; the response adds the SceneGroupId and SceneGroupName fields • The NotifyQrCodeScanEvent interface adds the EventType parameter (QR code scan event type) • The VerifyResult parameter of the Verify interface is changed from Integer to the VerifyResult enum (values: 1: success, 2: failure), clarifying the valid value range (semantics unchanged; legacy 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 sort field) • Added the SortOrder enum (sort direction: asc/desc) • Added the QrCodeScanEventType enum (QR code scan event type, used as the NotifyQrCodeScanEvent.EventType value) • Added the VerifyResult enum (additional verification result, used as the VerifyResult parameter value of the Verify interface) • Added the OrderBy common data structure (sorting condition)
v2.0.0	2026-04-03	• Added Palm Print management interfaces (8 interfaces: CreatePalm, BindPalm, SearchMobilePalm, Verify, DeletePalm, DescribePalm, SynchronizePalmFeature, DescribeVersionList) • Added the authentication management interface DescribePalmLicense (query authorization information) • The DescribeUser interface output adds a UserState (user status) field • The DescribeUserPalm interface output adds the UserName (user name), UserState (user status), PalmDirection (main palm direction), LeftPalm (left palm registration information), and RightPalm (right palm registration information) fields • The DescribeQrCodeScanUser interface output adds the UserName (user name), UserState (user status), PalmDirection (main palm direction), LeftPalm (left palm registration information), and RightPalm (right palm registration information) fields • The PalmState enum adds the 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 interface output adds 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) interface • Device management adds the DescribeDevice (query device details) interface • The CreateScene interface adds the SceneId (optional) and ScenarioStrategy (required) parameters • The ModifyScene interface 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 interface is changed to optional; if not passed, it defaults to true
v1.7.0	2026-01-05	• Added user tag management (4 interfaces: CreateUserTag, ModifyUserTag, DeleteUserTag, DescribeUserTag) • User management interfaces support tag binding and the partial failure mechanism (CreateUser and ModifyUser support the UserTagIdList and PartialFailure parameters) • Added complete documentation for the partial failure mechanism • Unified interface naming conventions (interface 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 PalmAI leverages Tencent's years of in-depth accumulation in computer vision and biometric identification technology, and uses its three core capabilities of palm registration, palm print recognition, and palm print verification. It is open to enterprises and developers through Tencent Cloud services and is committed to helping customers quickly build safe, convenient, and efficient palm print recognition solutions.

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

Glossary

For common terms of the Tencent PalmAI API, see the table below:

Term	Description
AppId	The unique application identifier. It is used by the Tencent Cloud backend to distinguish different Palm applications, and is automatically generated when a tenant is created in the Palm console. Data is not shared between different AppIds.
RGB	Color image.
IR	Infrared image.
Three points	The data output after image detection and alignment.
Feature value	The data output after an image is fed into 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 search hot library data stored in GPU memory or RAM, and general storage data (including ordinary databases, object storage, file storage, etc.).
Device type	The model identifier of the Palm Verification Device. Currently valid values: M3, M3B, M4, O1, O2.
Module type	The model identifier of the recognition module used by the Palm Verification Device. Currently valid values: 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 Interfaces
User Management Interfaces
User Tag Management Interfaces
User Palm Management Interfaces
Device Management Interfaces
Scene Management Interfaces
Verification Record Interfaces
Verification Rule Interfaces
QR Code Palm Registration Interfaces
PalmMa Login Interfaces
Palm Print Management Interfaces (Palm Algorithm Platform)

Authentication Management Interfaces

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateAccessToken	Obtain access credentials	20
DescribePalmLicense	Query authorization information	20

User Management Interfaces

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 Interfaces

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 Interfaces

Interface name	Interface function	Frequency limit (times/second/AppId)
DeleteUserPalm	Delete user palm information	20
DescribeUserPalm	Query user palm information	20

Device Management Interfaces

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

Scene Management Interfaces

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 Interfaces

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 Interfaces

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 Interfaces

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateQrCodeScanSession	Create QR Code Palm Registration session	20
NotifyQrCodeScanEvent	User QR code scan event notification	20
BindQrCodeScanPalm	QR Code Palm Binding	20
DescribeQrCodeScanSession	Query QR Code Palm Registration session status	20
DescribeQrCodeScanUser	Query QR Code Palm Registration user information	20

Interface name	Interface function	Frequency limit (times/second/AppId)
SendPalmMaSmsCode	Send SMS verification code	20
LoginPalmMaSmsCode	SMS verification code login	20

Palm Print Management Interfaces (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 feature	20
DescribeVersionList	Query product version list	20

How to Call

Basic Call Flow

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

Description of the two authentication methods:

Authentication method	Applicable scenario	Request headers
Signature + Token	Most management interfaces (user, device, scene, palm print, etc.)	`Authorization` + `X-Palm-Openapi-Token`
Token only	QR Code Palm Registration interfaces (NotifyQrCodeScanEvent, BindQrCodeScanPalm, DescribeQrCodeScanSession, DescribeQrCodeScanUser)	Only `X-Palm-Openapi-Token`, no `Authorization` required

Note:

Before calling any interface, you must first obtain an AccessToken through CreateAccessToken (this interface itself uses signature authentication).

Signature-authenticated interfaces carry both Authorization (signature) and X-Palm-Openapi-Token (Token) in the request headers.

Token-only authenticated interfaces only need to carry X-Palm-Openapi-Token, without computing a signature.

Request Structure

The request structure of the Palm API is as follows:

1. Service Endpoint

The API supports nearby regional access. The following domain is recommended:

Default access domain (recommended): open.intl.palm.tencent.com (for illustration only; the actual access domain is subject to assignment, and private deployment scenarios are supported)
Specified regional access (extensible if multiple regions are deployed): e.g., open.intl.palm.tencent.com (for illustration only; the actual access domain is subject to assignment)

Note: The domain is the access point of the API and does not represent the region where the product or interface actually provides services. If multiple regions are deployed later, this will be supplemented in 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 values:
- application/json (recommended; the signature method v3/TC3-HMAC-SHA256 must be used)
When the POST method uses signature method v3, a request packet of up to 10MB is supported.

4. Character Encoding

All requests and responses use UTF-8 encoding.

Common Parameters

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

Parameter Name	Type	Required	Description
X-TC-Action	String	Yes	The name of the interface being called. For example: CreateUser.
X-TC-Timestamp	Integer	Yes	The current UNIX timestamp in seconds. For example: 1704067200. A difference of more than 5 minutes from the server time will cause a signature expiration error.
X-TC-Version	String	Yes	The API version number, currently fixed at: 2025-07-15.
Authorization	String	Yes	The signature information, in the format: TC3-HMAC-SHA256 Credential=AKIDxxx/Date/service/tc3_request, SignedHeaders=content-type;host;x-tc-action, Signature=xxx. See the Signature Method section for details.
X-TC-Nonce	String	Yes	A 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	The request content type; application/json; charset=utf-8 is recommended.
Host	String	Yes	The service endpoint, fixed at open.intl.palm.tencent.com.
X-Palm-AppId	String	Yes	The application ID, obtained when applying for security credentials. Customers need to apply to Tencent for an AppId, SecretId, and SecretKey. Keep the above information secure and pass it in interface requests as required by your business.
X-Palm-Openapi-Token	String	Yes	The temporary security credential Token. Before calling a Tencent interface, you must first obtain the access credential through the [Obtain Access Credentials] interface (Action: CreateAccessToken). Note that access credentials are time-limited and must be reapplied for 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 credential used in this document is the key, which includes a SecretId and a SecretKey.

SecretId: Used to identify the API caller's identity, which can be simply analogized to a username.
SecretKey: Used to verify the API caller's identity, which can be simply analogized to a password.

Users must strictly safeguard their security credentials to avoid leakage; otherwise, property security will be endangered. If a credential has been leaked, disable it immediately.

The specific steps to apply for security credentials are as follows:

Log in to the Tencent Cloud Palm Service Console.
Go to the System Management | Tenant Management console page.
On the Tenant Management page, select the current tenant and click [Details] to query 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 passed in JSON format.

The following uses the example of binding a user's palm print to describe the signature calculation process step by step.

Assume that 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 following explains the signature calculation process in detail.

Concatenate the canonical request string

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

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

Field	Description
HTTPRequestMethod	The HTTP request method (GET, POST). In this example, the value is `POST`.
CanonicalURI	The URI parameter, fixed as a forward slash (`/`) in API 3.0.
CanonicalQueryString	The query string in the HTTP request URL. For POST requests, it is fixed as an empty string `""`; for GET requests, it is the string content after the question mark (?) in the URL, e.g., `Limit=10&Offset=0`. Note: CanonicalQueryString must be URL-encoded per RFC3986, with the UTF-8 character set. It is recommended to use the standard library of your programming language. All special characters must be encoded in uppercase form.
CanonicalHeaders	The header information involved in the signature, which must contain at least the host and content-type headers. Custom headers may also be added to the signature to increase the uniqueness and security of your request. Concatenation rules: 1) Convert both header keys and values to lowercase and trim leading and trailing spaces, then concatenate in the format `key:value\n`; 2) For multiple headers, concatenate them in ASCII ascending order by header key (lowercase). In this example, the result 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: content-type must match what is actually sent. Some programming language network libraries automatically add a charset value even if not specified; if the signature and the sent request are inconsistent, the server will return a signature validation failure.
SignedHeaders	The header information involved in the signature, indicating which headers of this request participated in the signature. It corresponds one-to-one with the headers contained in CanonicalHeaders. content-type and host are required headers. Concatenation rules: 1) Convert all header keys to lowercase; 2) Concatenate multiple header keys (lowercase) in ASCII ascending order, separated by a semicolon (;). 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 calculation pseudocode is `Lowercase(HexEncode(Hash.SHA256(RequestPayload)))`, i.e., perform SHA256 hashing on the HTTP request body, then hex-encode it, and finally convert the encoded string to lowercase. Note: For GET requests, RequestPayload is fixed as an empty string; for POST requests, RequestPayload is the request body Payload.

Based on the above rules, the canonical request string obtained in the example is as follows (for clarity, the \n line breaks 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

Concatenate the string to sign

Concatenate the string to sign according to the following pseudocode format:

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

Field	Description
Algorithm	The signature algorithm, currently fixed as `TC3-HMAC-SHA256`.
RequestTimestamp	The request timestamp, i.e., the value of the common parameter X-TC-Timestamp in the request headers, taking the current UNIX timestamp accurate to the second. In this example, the value is `1752587686`.
CredentialScope	The 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 match the UTC standard time date converted from the common parameter X-TC-Timestamp; service is the product name and must be consistent with the product domain being called, which is `palm` here. In this example, the result is: `2025-07-15/palm/tc3_request`.
HashedCanonicalRequest	The hash value of the canonical request string concatenated in the previous step. The calculation pseudocode is `Lowercase(HexEncode(Hash.SHA256(CanonicalRequest)))`. In this example, the result is 3044b1650deaa09d3d1e93d63c15fd76c7c764254b3a1cba9c6b321eda191774.

⚠️ Note:

Date must be calculated from the timestamp X-TC-Timestamp, and the time zone must be UTC+0. If local system time zone information (e.g., UTC+8) is included, calls will succeed during the day and evening but will always fail in the early morning. Suppose the timestamp is 1551113065; the time in UTC+8 is 2019-02-26 00:44:25, but the Date calculated in UTC+0 should be 2019-02-25, not 2019-02-26.

Timestamp must be the current system time, and you must ensure that the system time is synchronized with standard time. If the difference exceeds five minutes, the call will always fail. If the system is not synchronized with standard time for a long time, the request may fail after running for a while and return a signature expiration error.

Based on 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

Calculate the signature

Calculate the derived signing key, with the following pseudocode:

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 that may contain non-printable characters. Their hexadecimal string representations are:
2fbd1f93d8d1aae5c0a4e2df255519752e1e4be521b9edae832930379544679c,
45589385000e5972fe3fb6ca9f07339289dee6e33e0b5bb9022308d69eb15fc9,
a116ccc06739ebac6c1c54514ace4229c98847c5f1ee5abc395eafab262b0246.
Note that in different programming languages, the order of parameters in the HMAC library function may differ; please follow the actual situation. In the pseudocode here, the key parameter comes first and the message parameter data comes last. Standard library functions usually provide a return value in binary format, and may also provide a print-friendly hexadecimal format; the binary format is used here.

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

Calculate the signature, with the following pseudocode:

Signature = HexEncode(HMAC_SHA256(SecretSigning, StringToSign))

In this example, the result is f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db.

Concatenate Authorization

Concatenate Authorization according to the following format:

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

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

Based on 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 in the request must be exactly the same as the content used in the signature calculation process; otherwise, a signature mismatch error will be returned. You can troubleshoot by printing the actual request content or capturing network packets for comparison.

Signature Demo (Python)

The following is complete demo code implementing the signature process 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")
 
    # ************* Step 1: Concatenate the canonical request string *************
    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)
    
    # ************* Step 2: Concatenate the string to sign *************
    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)
 
    # ************* Step 3: Calculate the signature *************
    # Function to calculate the signature digest
    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()
 
    # ************* Step 4: Concatenate Authorization *************
    authorization = (algorithm + " " +
                    "Credential=" + secret_id + "/" + credential_scope + ", " +
                    "SignedHeaders=" + signed_headers + ", " +
                    "Signature=" + signature)
    print("authorization: {}".format(authorization))
 
    # Add common parameters to the request headers
    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 the server receives the request must not exceed five minutes.
AuthFailure.SecretIdNotFound	Key does not exist. Check in the console whether the key is disabled, or whether characters were missed or added during copying.
AuthFailure.SignatureFailure	Signature error. This may be caused by an error in the signature calculation, a mismatch between the signature and the content actually sent, 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 a non-JSON format will state so in the documentation. When returning JSON data, the maximum limit is 50 MB. If the returned data exceeds the maximum limit, the request will fail and return an internal error. It is recommended to control the returned data size using the filtering or pagination features in the interface documentation.

Note: As long as the request is processed normally by the server, the HTTP status code of the response is 200. For example, for errors such as signature failure, the HTTP status code is also 200, and the specific error information is reflected in the response body.

Successful Response

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

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

Response and its internal RequestId are fixed fields that 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 interface.

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 "Error Codes" section of the interface documentation.

Common Error Codes

If the Error field is present in the return result, it indicates that the API interface call failed. The Error.Code field is the error code, and error codes that may appear for 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 and output parameters support the following data types:

Type	Description	Example
String	String	"user123456"
Integer	Integer, with an upper limit of an unsigned 64-bit integer. It is recommended to define it with the largest integer type in 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 parse with a standard library	"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 handling mechanism that allows successful operations to still be executed even if some operations fail in a batch operation. This mechanism can improve the fault tolerance and efficiency of batch operations.

What Is Partial Failure

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

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

After the partial failure mechanism is enabled:

Valid operations are executed successfully
Failed operations return detailed error information in the response
Failed operations can be retried based on the returned error information

How to Use Partial Failure

Interfaces that support partial failure provide the PartialFailure parameter:

Request parameter:

Parameter Name	Required	Type	Description
PartialFailure	No	Boolean	Whether to allow partial failure. When set to `true`, the partial failure mechanism is enabled; the default is `false`.

Response field:

When partial failure is enabled and failed items exist, the response includes the PartialFailureError field, which describes the reason for failure in detail:

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

Example Scenarios

Scenario 1: Create a user and batch bind tags

Request example:

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

Successful response (no failed items):

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

Partial failure response (with failed items):

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

In the above example:

User user001 is created successfully
tag001 and tag002 are bound successfully
tag003 does not exist, so binding fails

Retry note: To retry, after correcting tag003, you must pass in the complete tag list ["tag001", "tag002", "tag003"] rather than only ["tag003"], because user tag binding is an overwrite operation.

Best Practices

Enable partial failure for batch operations
- In batch operations such as creation and modification, it is recommended to set PartialFailure=true
- This ensures that valid data is processed and invalid data is recorded
Check the PartialFailureError field in the response
- Even for a successful response, check the PartialFailureError field
- The presence of PartialFailureError indicates that some operations failed and need to be handled based on the returned information
Record and retry failed items
- Record the failed item information returned in PartialFailureError
- Reinitiate the request after correcting the cause of failure
- Note: For overwrite operations such as batch binding of user tags, you must pass the complete tag list when retrying (including previously successful items) rather than retrying only the failed items
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)

Interfaces That Support Partial Failure

The following interfaces 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 interfaces support the partial failure mechanism. For specific support, refer to the parameter description of each interface.

Authentication Management Interfaces

Obtain Access Credentials

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to obtain an access credential (AccessToken). The following call method is limited to scenarios where an ordinary server calls the open interfaces of the Palm Application Platform.

Note: This interface only requires a signature (Authorization) and does not require passing X-Palm-Openapi-Token. Before accessing the Palm Application Platform service, customers need to apply to Tencent for an AppId, SecretId, and SecretKey. Keep the above information secure and pass it in interface requests as required by your business.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateAccessToken.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
AppId	Yes	Integer	The product ID assigned by the system
SecretId	Yes	String	The customer's key ID
SecretKeyHash	Yes	String	The customer's key hash. The calculation rule is: hex.EncodeToString(sha256.Sum256(secretKey))
GrantType	Yes	String	The grant type. When calling the open interfaces of the Palm Application Platform, you must use `client_credential`. Value enum: - client_credential_user: Applicable to scenarios where a third-party platform integrates the Mobile Palm Registration SDK, i.e.: a. The mobile client uses the SDK to initiate registration or obtain a liveness video upload address; 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 also be passed in. - client_credential: Applicable to scenarios where an ordinary server calls the open interfaces, i.e.: a. This type does not bind a specific user and only uses the application-level key to obtain an access credential; b. The `UserId` field does not need to be passed in.
UserId	No	String	The user's identity ID. When grant_type is "client_credential_user", the UserId field must be passed.

3. Output Parameters

Parameter Name	Type	Description
AccessToken	String	The access credential, which can be used to access other interfaces subsequently
ExpiresIn	Integer	The validity period of the AccessToken in seconds; the token becomes invalid after expiration
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Authorization Information

1. Interface Description

Interface request domain: 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 interface request frequency limit: 20 times/second/AppId.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribePalmLicense.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
AppId	Yes	Integer	The product ID assigned by the system.

3. Output Parameters

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

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

User Management Interfaces

Create User

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to create a new user, supporting the setting of basic user information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateUser.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
UserName	Yes	String	The user name.
PhoneNo	No	String	The phone number (with area code), e.g., "(+86)13800138000". If no area code is provided, it defaults to "(+86)".
PhysicalCardNo	No	String	The physical card number, a combination of digits and letters.
UserTagIdList	No	Array of String	The list of user tag IDs.
PartialFailure	No	Boolean	Whether to allow partial failure.
CustomFieldValue	No	String	Deprecated; please use CustomFieldValueList.
CustomFieldValueList	No	Array of CustomFieldValueItem	The 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	The partial failure result. See the CreateUserResponsePartialFailureError structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang San",
  "PhoneNo": "(+86)13800138000",
  "PhysicalCardNo": "CARD001",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true,
  "CustomFieldValueList": [
    {"FieldName": "Employee ID", "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": "The user name is empty"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Modify User

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to modify user information, supporting updates to the user's basic information.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: ModifyUser.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
UserName	Yes	String	The user name.
PhoneNo	No	String	The phone number (with area code), e.g., "(+86)13800138000". If no area code is provided, it defaults to "(+86)".
PhysicalCardNo	No	String	The physical card number, a combination of digits and letters.
UserTagIdList	No	Array of String	The list of user tag IDs.
PartialFailure	No	Boolean	Whether to allow partial failure.
CustomFieldValue	No	String	Deprecated; please use CustomFieldValueList.
CustomFieldValueList	No	Array of CustomFieldValueItem	The 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	The partial failure result. See the ModifyUserResponsePartialFailureError structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang San",
  "PhoneNo": "(+86)13800138000",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true,
  "CustomFieldValueList": [
    {"FieldName": "Employee ID", "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": "The user does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete User

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to delete a specified user. After deletion, the user data cannot be recovered.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeleteUser.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The user does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUser.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
UserId	String	The unique user identifier.
UserName	String	The user name.
PhoneNo	String	The phone number (with area code), e.g., "(+86)13800138000". If no area code is provided, it defaults to "(+86)".
PhysicalCardNo	String	The physical card number, a combination of digits and letters.
UserTagList	Array of DescribeUserResponseUserTag	The user tag list. See the DescribeUserResponseUserTag structure.
PalmDirection	PalmDirection	The palm direction. See the PalmDirection enum.
LeftPalm	PalmInfo	The left palm registration information. See the PalmInfo structure.
RightPalm	PalmInfo	The right palm registration information. See the PalmInfo structure.
CreateTime	Timestamp	The user creation time, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
UserState	UserState	The user status. See the UserState enum.
CustomFieldValue	String	Deprecated; please use CustomFieldValues.
CustomFieldValues	Array of CustomFieldValueItem	The full list of custom additional verification field values.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang San",
    "PhoneNo": "(+86)13800138000",
    "PhysicalCardNo": "CARD2024A001",
    "UserTagList": [
      {
        "UserTagId": "tag001",
        "UserTagName": "R&D Center"
      },
      {
        "UserTagId": "tag002",
        "UserTagName": "Product Center"
      }
    ],
    "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": "Employee ID", "FieldValue": "123456"}
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserNotExist",
      "Message": "The user information was not found."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User Information List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUserList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	No	String	The unique user identifier. Fuzzy query is supported.
UserName	No	String	The user name. Fuzzy query is supported.
PhoneNo	No	String	The phone number. Exact match.
PhysicalCardNo	No	String	The physical card number. Exact match.
PalmState	No	PalmState	The main palm registration status.
UserState	No	UserState	The user status.
UserTagId	No	String	The user tag ID, used to filter users that have the specified tag.
SceneId	No	String	The scene ID, used to filter users who have access permission for that scene.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.
SkipTotalCount	No	Boolean	Whether to skip the total count. When set to true, TotalCount is not returned (to avoid slow queries), and HasMore is used instead to determine whether there is a next page.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The number of users that meet the conditions. When SkipTotalCount=true is requested, this field is not returned.
UserList	Array of DescribeUserListResponseUser	The user list. See the DescribeUserListResponseUser structure.
HasMore	Boolean	Whether there is more data. When SkipTotalCount=true is requested, this field is used to determine whether there is a next page.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang",
  "PalmState": "registered",
  "Offset": 0,
  "Limit": 10
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "UserList": [
      {
        "UserId": "user001",
        "UserName": "Zhang San",
        "PhoneNo": "(+86)13800138000",
        "PhysicalCardNo": "CARD001",
        "UserTagList": [{"UserTagId": "tag001", "UserTagName": "R&D Center"}],
        "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User Access Scope

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Query the detailed information of the scenes, devices, and access time periods the user can access, based on the user ID.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUserAccessScope.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The total number of scenes that meet the conditions.
AccessScopeList	Array of AccessScopeItem	The access scope list (aggregated by scene). See the AccessScopeItem structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Main Gate",
        "SceneGroupId": "group001",
        "SceneGroupName": "Headquarters Campus",
        "DeviceSn": "DEV001",
        "DeviceName": "Front Desk Device",
        "VerifyRules": [
          {"VerifyRuleId": "rule001", "VerifyRuleName": "Weekday Rule"}
        ]
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User Access Scope Summary

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUserAccessScopeSummary.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
Summary	AccessScopeSummary	The access scope summary. See the AccessScopeSummary structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

User Tag Management Interfaces

Create User Tag

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to create a new user tag.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateUserTag.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserTagName	Yes	String	The user tag name.

3. Output Parameters

Parameter Name	Type	Description
UserTagId	String	The unique user tag identifier.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "R&D Center"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserTagNameEmpty",
      "Message": "The user tag name is empty"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Modify User Tag

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to modify user tag information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: ModifyUserTag.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserTagId	Yes	String	The unique user tag identifier.
UserTagName	Yes	String	The user tag name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Product Center"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "The user tag does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete User Tag

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to delete a specified user tag. After deletion, the user tag data cannot be recovered.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeleteUserTag.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserTagId	Yes	String	The unique user tag identifier.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The user tag does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User Tag

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUserTag.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserTagId	Yes	String	The unique user tag identifier.

3. Output Parameters

Parameter Name	Type	Description
UserTagId	String	The unique user tag identifier.
UserTagName	String	The user tag name.
ParentTagId	String	The parent tag ID. Empty indicates a top-level tag.
Level	Integer	The level depth: 0=L1 (top level), 1=L2 (second level), 2=L3 (third level).
ChildrenCount	Integer	The number of direct child tags.
UserCount	Integer	The number of users associated with the tag.
PathNodes	Array of UserTagNode	The complete level path from the root tag to the current tag, returned in parent-to-child order. See the UserTagNode structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "R&D Center",
    "ParentTagId": "",
    "Level": 0,
    "ChildrenCount": 3,
    "UserCount": 50,
    "PathNodes": [
      {
        "UserTagId": "tag001",
        "UserTagName": "R&D Center",
        "Level": 0
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.UserTagNotExist",
      "Message": "The user tag information was not found."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUserTagList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserTagName	No	String	The tag name. Fuzzy search is supported.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The total number of tags that meet the conditions.
UserTagList	Array of DescribeUserTagListResponseUserTagItem	The tag information list. See the DescribeUserTagListResponseUserTagItem structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "R&D",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "UserTagList": [
      {
        "UserTagId": "tag001",
        "UserTagName": "R&D Center",
        "UserCount": 50,
        "ParentTagId": "",
        "Level": 0,
        "ChildrenCount": 3,
        "PathNodes": [
          {
            "UserTagId": "tag001",
            "UserTagName": "R&D Center",
            "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User Tag Tree Structure

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Query the user tag tree structure, returning the tag hierarchy relationships.

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

2. Input Parameters

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

3. Output Parameters

Parameter Name	Type	Description
Tree	Array of UserTagTreeNode	The tag tree node list. See the UserTagTreeNode structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "R&D Department",
        "UserCount": 50,
        "Level": 0,
        "ParentTagId": "",
        "Children": [
          {
            "UserTagId": "tag002",
            "UserTagName": "Frontend Team",
            "UserCount": 20,
            "Level": 1,
            "ParentTagId": "tag001",
            "Children": []
          }
        ]
      }
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

User Palm Management Interfaces

Delete User Palm Information

1. Interface Description

Interface request domain: 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 interface request frequency limit: 20 times/second/AppId.

2. Input Parameters

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

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The user palm information does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query User Palm Information

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeUserPalm.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.

3. Output Parameters

Parameter Name	Type	Description
UserId	String	The unique user identifier.
PalmState	PalmState	The main palm registration status.
UserName	String	The user name.
UserState	UserState	The user status. See the UserState enum.
PalmDirection	PalmDirection	The main palm direction. See the PalmDirection enum.
LeftPalm	PalmInfo	The left palm registration information. See the PalmInfo structure.
RightPalm	PalmInfo	The right palm registration information. See the PalmInfo structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang San",
    "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": "The user palm information was not found."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Device Management Interfaces

Create Device

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to create a new device, supporting the setting of basic device information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateDevice.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
DeviceSn	Yes	String	The device serial number.
DeviceName	Yes	String	The device name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Access Control No.1"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.DeviceSnEmpty",
      "Message": "The device SN is empty"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Modify Device

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to modify device information, supporting updates to the basic device information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: ModifyDevice.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
DeviceSn	Yes	String	The device serial number.
DeviceName	Yes	String	The device name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Access Control No.1 (Updated)"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.DeviceNotExist",
      "Message": "The device does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete Device

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to delete a specified device. After deletion, the device data cannot be recovered.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeleteDevice.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
DeviceSn	Yes	String	The device serial number.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The device does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Device Details

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeDevice.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
DeviceSn	Yes	String	The device serial number.

3. Output Parameters

Parameter Name	Type	Description
DeviceSn	String	The device SN.
DeviceName	String	The associated device name.
DeviceType	String	The device type.
ModuleType	String	The module type.
ModuleExpireTime	Timestamp	The module validity period, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
AppVersion	String	The application version.
ModuleVersion	String	The module version.
SystemVersion	String	The system version.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Access Control Device",
    "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": "The device does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Device List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeDeviceList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
DeviceSn	No	String	The device serial number. Exact match.
DeviceName	No	String	The device name. Fuzzy search is supported.
Status	No	DeviceStatus	The device status filter.
SceneId	No	String	The scene ID, used to filter devices bound to the specified scene.
DeviceType	No	String	The device type. For values, see the Glossary.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The total number of devices that meet the conditions.
DeviceList	Array of DescribeDeviceListResponseDevice	The device list. See the DescribeDeviceListResponseDevice structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Access Control",
  "Status": "online",
  "Offset": 0,
  "Limit": 10
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "DeviceList": [
      {
        "DeviceSn": "SN001",
        "DeviceType": "M4",
        "DeviceName": "Shenzhen Nanshan Access Control Device",
        "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": "Shenzhen Nanshan Access Control No.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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Scene Management Interfaces

Create Scene

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateScene.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneName	Yes	String	The scene name.
SceneGroupId	Yes	String	The scene group ID.
DeviceSn	No	String	The device serial number.
VerifyRuleIdList	No	Array of String	The list of verification rule IDs.
SceneId	No	String	The scene ID (optional; auto-generated if not passed).
ScenarioStrategy	Yes	ScenarioStrategy	The scene strategy. See the ScenarioStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
SceneId	String	The unique scene identifier.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Access Control No.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": "The scene name cannot be empty."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Modify Scene

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: ModifyScene.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneId	Yes	String	The scene ID.
SceneName	Yes	String	The scene name.
DeviceSn	No	String	The device serial number.
VerifyRuleIdList	No	Array of String	The list of verification rule IDs.
ScenarioStrategy	Yes	ScenarioStrategy	The scene strategy. See the ScenarioStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Access Control No.1 (Updated)",
  "DeviceSn": "device002",
  "VerifyRuleIdList": ["verifyrule001"],
  "ScenarioStrategy": "AccessOnDeviceRecognition50k"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "The scene does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete Scene

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to delete a specified scene. After deletion, the scene data cannot be recovered.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeleteScene.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneId	Yes	String	The scene ID.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The scene does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Scene Details

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeScene.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneId	Yes	String	The scene ID.

3. Output Parameters

Parameter Name	Type	Description
SceneId	String	The scene ID.
SceneName	String	The scene name.
SceneGroupId	String	The scene group ID.
SceneGroupName	String	The scene group name.
DeviceSn	String	The associated device SN.
DeviceName	String	The associated device name.
ScenarioStrategy	ScenarioStrategy	The scene strategy. See the ScenarioStrategy enum.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Access Control No.1",
    "SceneGroupId": "scenegroup001",
    "SceneGroupName": "Shenzhen Nanshan Area",
    "DeviceSn": "device001",
    "DeviceName": "Shenzhen Nanshan Access Control Device",
    "ScenarioStrategy": "AccessOnDeviceRecognition50k",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneNotExist",
      "Message": "The scene does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Create Scene Group

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateSceneGroup.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneGroupName	Yes	String	The scene group name.
ParentSceneGroupId	Yes	String	The parent scene group ID.

3. Output Parameters

Parameter Name	Type	Description
SceneGroupId	String	The unique scene group identifier.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Area",
  "ParentSceneGroupId": "scene_group_root"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.SceneGroupNameEmpty",
      "Message": "The scene group name cannot be empty."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Modify Scene Group

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to modify scene group information, supporting updates to the basic scene group information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: ModifySceneGroup.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneGroupId	Yes	String	The scene group ID.
SceneGroupName	Yes	String	The scene group name.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Area (Updated)"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "FailedOperation.SceneGroupNotExist",
      "Message": "The scene group does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete Scene Group

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to delete a specified scene group. After deletion, the scene group data cannot be recovered.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeleteSceneGroup.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneGroupId	Yes	String	The scene group ID.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The scene group does not exist or has been deleted."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Scene List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeSceneList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneIdList	No	Array of String	The list of scene IDs. Exact match, supporting batch query.
SceneName	No	String	The scene name. Fuzzy search is supported.
SceneGroupId	No	String	The scene group ID, used to filter scenes belonging to the specified scene group.
DeviceSn	No	String	The device serial number. Exact match.
VerifyRuleId	No	String	The verification rule ID, used to filter scenes bound to the specified rule.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The total number of scenes that meet the conditions.
SceneList	Array of DescribeSceneListResponseSceneItem	The scene information list. See the DescribeSceneListResponseSceneItem structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Access Control",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "SceneList": [
      {
        "SceneId": "scene001",
        "SceneName": "Shenzhen Nanshan Access Control No.1",
        "SceneGroupId": "sg001",
        "SceneGroupName": "Shenzhen Nanshan Area",
        "DeviceSn": "SN001",
        "DeviceName": "Shenzhen Nanshan Access Control Device",
        "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Scene Group List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeSceneGroupList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SceneGroupIdList	No	Array of String	The list of scene group IDs. Exact match, supporting batch query.
SceneGroupName	No	String	The scene group name. Fuzzy search is supported.
ParentSceneGroupId	No	String	The parent scene group ID. When passed, only the direct child scene groups under this parent are returned; if not passed, all scene groups are returned.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The total number of scene groups that meet the conditions.
SceneGroupList	Array of DescribeSceneGroupListResponseSceneGroupItem	The scene group information list. See the DescribeSceneGroupListResponseSceneGroupItem structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Shenzhen Nanshan Area",
        "ParentSceneGroupId": "sg_root",
        "ParentSceneGroupName": "All Scene Groups",
        "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Verification Record Interfaces

Create Verification Record

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to create a verification record.

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

2. Input Parameters

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

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Li Si",
  "Source": "device"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.UserIdEmpty",
      "Message": "The user ID cannot be empty."
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Verification Record List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeVerificationRecordList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	No	String	The user ID.
UserName	No	String	The user name.
VerificationMedium	No	VerificationMedium	The verification medium.
DeviceSn	No	String	The device SN.
SceneId	No	String	The scene ID.
StartTime	No	Timestamp	The verification start time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
EndTime	No	Timestamp	The verification end time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
SceneGroupIds	No	Array of String	The list of scene group IDs. Exact match (with child scene groups expanded).
SceneGroupName	No	String	The scene group name. Fuzzy search.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.
OrderBy	No	OrderBy	The sorting condition. See the OrderBy structure.
Source	No	VerificationRecordSource	The verification record source filter (optional).
SkipTotalCount	No	Boolean	Whether to skip the total count. When set to true, TotalCount is not returned (to avoid slow queries), and HasMore is used instead to determine whether there is a next page.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The number of verification records that meet the conditions. When SkipTotalCount=true is requested, this field is not returned.
VerificationRecordList	Array of DescribeVerificationRecordListResponseVerificationRecord	The verification record list. See the DescribeVerificationRecordListResponseVerificationRecord structure.
HasMore	Boolean	Whether there is more data. When SkipTotalCount=true is requested, this field is used to determine whether there is a next page.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang San",
  "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": "Zhang San",
        "VerificationTime": "2024-06-10T09:15:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device001",
        "SceneId": "scene001",
        "SceneName": "Shenzhen Nanshan Access Control No.1",
        "VerifierId": "verifier001",
        "VerifierName": "Li Si",
        "Source": "device",
        "Reason": ""
      },
      {
        "UserId": "user001",
        "UserName": "Zhang San",
        "VerificationTime": "2024-06-11T18:30:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device002",
        "SceneId": "scene002",
        "SceneName": "Shenzhen Nanshan Access Control No.2",
        "VerifierId": "verifier002",
        "VerifierName": "Wang Wu",
        "Source": "device",
        "AccessDenied": true,
        "Reason": "Not within the allowed access time period"
      }
    ],
    "HasMore": false,
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.FiltersLimitExceed",
      "Message": "The number of filters exceeds the limit"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Verification Record (Push Only)

1. Interface Description

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

Interface description: Used to receive the verification record information pushed by the open platform. This interface only supports push, not active pull.

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

2. Push Content (Parameter Structure)

Parameter Name	Type	Description
UserId	String	The user ID
UserName	String	The user name
VerificationTime	Timestamp	The verification time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
VerificationMedium	VerificationMedium	The verification medium
DeviceSn	String	The device SN
SceneId	String	The scene ID
SceneName	String	The scene name
VerifierId	String	The verifier ID
VerifierName	String	The verifier name
AccessDenied	Boolean	Whether the verification result is denied. false indicates verification succeeded; true indicates verification failed.
Reason	String	The verification description
RequestId	String	The unique request ID

3. Push Example

POST / HTTP/1.1
Host: <customer push address domain>
Content-Type: application/json; charset=utf-8
X-TC-Action: CreateVerificationRecord

{
  "UserId": "user001",
  "UserName": "Zhang San",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "Shenzhen Nanshan Access Control No.1",
  "VerifierId": "verifier001",
  "VerifierName": "Li Si",
  "AccessDenied": false,
  "Reason": "",
  "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
}

After receiving the push, the customer only needs to return HTTP 200 OK, without returning business data.

Verification Rule Interfaces

Create Verification Rule

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateVerifyRule.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
VerifyRuleName	Yes	String	The verification rule name.
EnableTimeRule	Yes	Boolean	Whether to enable the time rule. false indicates disabled; true indicates enabled.
TimeRule	No	TimeRule	The time rule. Must be configured when the time rule is enabled. See the TimeRule structure.
EnableUserRule	Yes	Boolean	Whether to enable the user rule. false indicates all users; true indicates specified users.
UserRule	No	UserRule	The user rule. Must be configured when the user rule is enabled. See the UserRule structure.
EnableWebhookRule	No	Boolean	Whether to enable the Webhook rule. Optional; if not passed, it defaults to true.
BindSceneIdList	No	Array of String	The list of bound scene IDs. Multiple scenes can be bound.

3. Output Parameters

Parameter Name	Type	Description
VerifyRuleId	String	The verification rule ID.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Weekday Morning and Evening Peak",
  "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": "R&D Center"}
    ],
    "UserInfos": [
      {"UserId": "user001", "UserName": "Zhang San"}
    ]
  },
  "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Modify Verification Rule

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to modify existing verification rule information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: ModifyVerifyRule.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
VerifyRuleId	Yes	String	The globally unique ID of the verification rule.
VerifyRuleName	Yes	String	The verification rule name.
EnableTimeRule	Yes	Boolean	Whether to enable the time rule.
TimeRule	No	TimeRule	The time rule. See the TimeRule structure.
EnableUserRule	Yes	Boolean	Whether to enable the user rule.
UserRule	No	UserRule	The user rule. See the UserRule structure.
EnableWebhookRule	Yes	Boolean	Whether to enable the Webhook rule.
BindSceneIdList	No	Array of String	The list of bound scene IDs.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Weekday Peak and Noon",
  "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete Verification Rule

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to delete a specified verification rule.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeleteVerifyRule.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
VerifyRuleId	Yes	String	The verification rule ID.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Verification Rule

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeVerifyRule.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
VerifyRuleId	Yes	String	The verification rule ID.

3. Output Parameters

Parameter Name	Type	Description
VerifyRuleId	String	The verification rule ID.
VerifyRuleName	String	The verification rule name.
EnableTimeRule	Boolean	Whether the time rule is enabled.
TimeRule	TimeRule	The time rule. See the TimeRule structure.
EnableUserRule	Boolean	Whether the user rule is enabled.
UserRule	UserRule	The user rule. See the UserRule structure.
EnableWebhookRule	Boolean	Whether the Webhook rule is enabled.
BindSceneIdList	Array of String	The list of bound scene IDs.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Weekday Morning and Evening Peak",
    "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": "R&D Center"
        }
      ],
      "UserInfos": [
        {
          "UserId": "user001",
          "UserName": "Zhang San"
        }
      ]
    },
    "EnableWebhookRule": false,
    "BindSceneIdList": [
      "scene001",
      "scene002"
    ],
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Verification Rule List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeVerifyRuleList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
VerifyRuleIdList	No	Array of String	The list of verification rule IDs. Exact match, supporting batch query.
VerifyRuleName	No	String	The verification rule name. Fuzzy search is supported.
Offset	No	Integer	The offset. Default 0.
Limit	No	Integer	The number of records to return. Default 20, maximum 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The total number of verification rules that meet the conditions.
VerifyRuleList	Array of DescribeVerifyRuleListResponseVerifyRuleItem	The verification rule list. See the DescribeVerifyRuleListResponseVerifyRuleItem structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Weekday",
  "Offset": 0,
  "Limit": 20
}

Output Example

{
  "Response": {
    "TotalCount": 1,
    "VerifyRuleList": [
      {
        "VerifyRuleId": "vr_20250715001",
        "VerifyRuleName": "Weekday Morning and Evening Peak",
        "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Check Access Permission

1. Interface Description

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

Interface description: Used to check the user's access permission. This interface only supports callback, not active pull. 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 determines whether to allow access and the reason based on their own rules.

2. Input Parameters

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

3. Output Parameters

Parameter Name	Type	Description
Allowed	Boolean	Whether access is allowed
Reason	String	The access reason description, e.g., "Matched verification rule: Visitor Appointment Access"
RequestId	String	The unique request ID. RequestId is returned for each request.

4. Request and Response Examples

Request Example

POST / HTTP/1.1
Host: <customer callback address domain>
Content-Type: application/json; charset=utf-8
X-TC-Action: CheckAccessPermission

{
  "UserId": "user001",
  "UserName": "Zhang San",
  "VerificationTime": "2025-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "Shenzhen Nanshan Access Control No.1"
}

Response Example (Access Allowed)

{
  "Response": {
    "Allowed": true,
    "Reason": "Matched verification rule: Visitor Appointment Access",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Response Example (Access Denied)

{
  "Response": {
    "Allowed": false,
    "Reason": "The user is not within the allowed time range",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

QR Code Palm Registration Interfaces

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 completes palm registration, the Palm Verification Device displays a QR code that 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 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. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to notify the server of the user's QR code scan event. This interface only verifies the Token, not the signature; the HTTP header does not require an Authorization field.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: NotifyQrCodeScanEvent.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SessionId	Yes	String	The session ID
EventType	No	NotifyQrCodeScanEventRequestQrCodeScanEventType	The event type. See the NotifyQrCodeScanEventRequestQrCodeScanEventType enum. If not passed, it is equivalent to scanned.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID. RequestId is returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

QR Code Palm Binding

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to bind a palm print by scanning a QR code. This interface only verifies the Token, not the signature; the HTTP header does not require an Authorization field.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: BindQrCodeScanPalm.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SessionId	Yes	String	The session ID
UserId	Yes	String	The unique user identifier
UserName	Yes	String	The user name
ReplacePalm	No	Boolean	Whether to replace the palm

3. Output Parameters

Parameter Name	Type	Description
UserSessionId	String	The user session ID
RequestId	String	The unique request ID. RequestId is returned for each request.

4. Examples

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": "Zhang San",
  "ReplacePalm": false
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query QR Code Palm Registration User Information

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to query the QR Code Palm Registration user information. This interface only verifies the Token, not the signature; the HTTP header does not require an Authorization field.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeQrCodeScanUser.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SessionId	Yes	String	The session ID
UserId	Yes	String	The unique user identifier

3. Output Parameters

Parameter Name	Type	Description
UserId	String	The unique user identifier
PalmState	PalmState	The main palm registration status
UserName	String	The user name
UserState	UserState	The user status. See the UserState enum.
PalmDirection	PalmDirection	The main palm direction. See the PalmDirection enum.
LeftPalm	PalmInfo	The left palm registration information. See the PalmInfo structure.
RightPalm	PalmInfo	The right palm registration information. See the PalmInfo structure.
PhoneNo	String	The phone number (with area code).
RequestId	String	The unique request ID. RequestId is returned for each request.

4. Examples

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": "Zhang San",
    "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Create QR Code Palm Registration Session

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Creates a QR Code Palm Registration session, used to generate the QR code or URL for the user to scan and register their palm. It supports three session purposes: QR Code Palm Registration (scan_register), Tap Code Palm Registration (tap_register), and Tap Code Additional Verification (tap_verify). This interface only verifies the Token, not the signature; the HTTP header does not require an Authorization field.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: CreateQrCodeScanSession.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
Ttl	No	String	The expected session lifetime. Effective in the scan_register/tap_register scenarios; in the tap_verify scenario it is determined by the tenant configuration (this field is not effective). If not specified, scan_register defaults to 1 hour and tap_register defaults to 15 minutes. The maximum is 24 hours. String format, e.g., "3600s".
ResponseFormat	No	ResponseFormat	The response data format. Options: metadata (default, returns metadata), url (returns the QR code URL), image (returns the QR code image).
PalmDirection	No	PalmDirection	The palm direction, specifying the palm direction for this registration.
QrCodeSessionType	No	QrCodeSessionType	The session purpose. If 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	The user ID. Required in the tap_register/tap_verify scenarios.
UserName	No	String	The user name. Required in the tap_register scenario; optional in the tap_verify scenario.
PhoneNo	No	String	The phone number. Optional in the Tap Code Palm Registration scenario; when passed, it is validated against the backend user's phone number.

3. Output Parameters

Parameter Name	Type	Description
SessionId	String	The session ID.
ExpireTime	Timestamp	The session expiration time, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
AppId	String	The application ID. Subsequent QR Code Palm Registration requests for this session must carry it in the HTTP request header "X-Palm-Appid".
AccessToken	String	The access token. Subsequent QR Code Palm Registration requests for this session must carry it in the HTTP request header "X-Palm-Openapi-Token".
AccessTokenExpireTime	Timestamp	The token expiration time, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
SessionUrl	String	The session URL. In the scan_register scenario, it is a complete H5 link; in the tap_register/tap_verify scenarios, it is a session identifier. Returned only when ResponseFormat=url.
SessionImage	String	The session QR code image (base64-encoded binary data). Returned only when ResponseFormat=image.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query QR Code Palm Registration Session Status

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to query the QR Code Palm Registration session status. This interface only verifies the Token, not the signature; the HTTP header does not require an Authorization field.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeQrCodeScanSession.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SessionId	Yes	String	The session ID.

3. Output Parameters

Parameter Name	Type	Description
QrCodeScanState	QrCodeScanState	The QR code scan status.
UserId	String	The unique user identifier.
UserName	String	The user name.
ReplacePalm	Boolean	Whether to replace the palm.
PalmDirection	PalmDirection	The palm direction.
QrCodeSessionType	QrCodeSessionType	The session purpose. The device uses this field to distinguish between QR Code Palm Registration, Tap Code Palm Registration, or Tap Code Additional Verification scenarios.
PhoneNo	String	The phone number (with area code).
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Zhang San",
    "ReplacePalm": false,
    "PalmDirection": "right",
    "QrCodeSessionType": "scan_register",
    "PhoneNo": "+8613800138000",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Send SMS Verification Code

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Used to send an SMS verification code to a specified phone number. This interface is an open interface that does not verify the Token or the signature; the HTTP header does not require the Authorization or X-Palm-Openapi-Token fields.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: SendPalmMaSmsCode.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
PhoneNo	Yes	String	The phone number (with area code).

3. Output Parameters

Parameter Name	Type	Description
SessionId	String	The session ID, used for subsequent verification code checks.
ExpireTime	Timestamp	The session expiration time, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
ResendInterval	String	The verification code resend interval for the session, e.g., "60s".
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

Note: This interface requires providing the X-Palm-Appid field in the HTTP request header. The verification code can be used only once, and the SessionId becomes invalid immediately after a successful verification.

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: LoginPalmMaSmsCode.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
SmsCode	No	String	The SMS verification code (verification is required each time; the verification 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 (one-time use; becomes invalid immediately after a successful verification). If SMS capability is not configured during deployment, this field does not need to be passed.
UserId	Yes	String	The user ID.
PhoneNo	No	String	The phone number (with area code), used to validate against the phone number bound to the backend user. If not passed, the validation is skipped.
GrantType	No	GrantType	The grant type. When calling the open interfaces of the Palm Application Platform, you must use `client_credential`. Value enum: - client_credential_user: Applicable to scenarios where a third-party platform integrates the Mobile Palm Registration SDK, i.e.: a. The mobile client uses the SDK to initiate registration or obtain a liveness video upload address; 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 also be passed in. - client_credential: Applicable to scenarios where an ordinary server calls the open interfaces, i.e.: a. This type does not bind a specific user and only uses the application-level key to obtain an access credential; b. The `UserId` field does not need to be passed in. If not passed, it defaults to the `client_credential_user` type. See the GrantType enum.

3. Output Parameters

Parameter Name	Type	Description
AccessToken	String	The access token (short-lived, e.g., 2 hours). Subsequent requests in the current session must carry this token in the HTTP request header "X-Palm-Openapi-Token".
AccessTokenExpireTime	Timestamp	The access token expiration time, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
RefreshToken	String	The refresh token (long-lived, e.g., 30 days), used to refresh the access token.
RefreshTokenExpireTime	Timestamp	The refresh token expiration time, in RFC3339 string format, e.g., "2025-07-03T09:30:15.500Z".
RequestId	String	The unique request ID, returned for each request.

4. Examples

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",
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Palm Print Management Interfaces (Palm Algorithm Platform)

Create Palm Print

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Upload a palm image to create a palm print and return the palm print ID. Two-factor authentication.

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

2. Input Parameters

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

3. Output Parameters

Parameter Name	Type	Description
PalmId	String	The palm print ID.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "... feature data, base64 required",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 1
  },
  "IrImage": {
    "Data": "... feature data, base64 required",
    "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": "The palm print ID is empty"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Bind Palm Print

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Bind a created palm print ID to a specified user. Two-factor authentication.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: BindPalm.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
PalmId	Yes	String	The palm print ID.
IsForce	No	Boolean	Whether to force re-binding.
AlgorithmStrategy	No	AlgorithmStrategy	The 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 palm print ID remains unchanged) and returns the palm print ID already registered by the user.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The user does not exist"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Register Palm Print

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Upload a palm image to create a palm print and bind it to a specified user. Two-factor authentication.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: RegisterPalm.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
RgbImage	Yes	Image	The RGB image data. See the Image structure.
IrImage	Yes	Image	The IR image data. See the Image structure.
PalmDirection	Yes	PalmPaasPalmDirection	The palm direction. See the PalmPaasPalmDirection enum.
IsForce	No	Boolean	Whether to force re-binding.
AlgorithmStrategy	No	AlgorithmStrategy	The algorithm strategy type. See the AlgorithmStrategy enum.
HighSimilarityResolutionStrategy	No	HighSimilarityResolutionStrategy	The resolution strategy when a high-similarity user is 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 palm print ID remains unchanged) and returns the palm print ID already registered by the user.
CheckErrors	Array of Integer	The list of registration check errors. See the CheckError enum. An empty list indicates that registration succeeded; a non-empty list indicates that registration was rejected. Only when HighSimilarityResolutionStrategy = 2 (REJECT_WITH_SIMILAR_USERS) is the rejection reason returned via this field instead of as an error.
HighSimilarityUserIdList	Array of String	The list of high-similarity user IDs. This field has a value when CheckErrors contains 1 (HIGH_SIMILARITY_DETECTED).
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "... feature data, base64 required",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 1
  },
  "IrImage": {
    "Data": "... feature data, base64 required",
    "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": "The user does not exist"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Mobile Palm Registration Search

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Upload RGB+IR palm images to perform a 1:N search for the user, and return additional verification information.

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

2. Input Parameters

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

3. Output Parameters

Parameter Name	Type	Description
VerifyInfo	VerifyInfo	The additional verification information. See the VerifyInfo structure.
PalmId	String	The palm print ID.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Internal error"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

User Additional Verification

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Complete the user identity additional verification and bind the palm print.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: Verify.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
VerifyId	Yes	String	The additional verification ID. Source: VerifyInfo.VerifyId returned by SearchMobilePalm.
UserId	Yes	String	The unique identifier of the user being additionally verified.
VerifyResult	Yes	VerifyResult	The additional verification result. See the VerifyResult enum.
AlgorithmStrategy	No	AlgorithmStrategy	The algorithm strategy type. See the AlgorithmStrategy enum.

3. Output Parameters

Parameter Name	Type	Description
VerifyInfo	VerifyInfo	The additional verification information, returned when further additional verification is required. See the VerifyInfo structure.
PalmId	String	The palm print ID of the user, returned upon successful additional verification.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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 When Further Additional Verification Is Required

{
  "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": "The user ID is empty"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Delete Palm Print

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DeletePalm.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
PalmDirectionList	Yes	Array of PalmPaasPalmDirection	The list of palm print directions. You can pass both the left and right hands, or the left or right hand individually.

3. Output Parameters

Parameter Name	Type	Description
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The user does not exist"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Palm Print

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribePalm.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
UserId	Yes	String	The unique user identifier.
UserToken	No	String	The user token. The client SDK queries via the Token.

3. Output Parameters

Parameter Name	Type	Description
LeftPalm	PalmPaasPalmInfo	The left-hand palm print information. See the PalmPaasPalmInfo structure.
RightPalm	PalmPaasPalmInfo	The right-hand palm print information. See the PalmPaasPalmInfo structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "The user does not exist"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Synchronize Palm Print Feature

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Synchronize palm print features.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: SynchronizePalmFeature.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
ProductVersion	Yes	String	The product version to synchronize, e.g., v20250715. This version number must match the version number on the device.
QueryPosition	Yes	String	The current synchronization position. Pass an empty string for the first time, and use the QueryPosition data from the response the next time.
DeviceId	Yes	String	The device ID. Currently used only for troubleshooting.
DisableFeature	No	Boolean	Whether to disable returning the feature value. Default is false (returned); true means not returned.
Operations	No	Array of PalmPaasOperation	Filter 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	The 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, synchronization can continue; other statuses may be added in the future, and the documentation will be updated accordingly if so.
QueryPosition	String	The current synchronization position.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "... feature data, base64 required",
          "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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Query Product Version List

1. Interface Description

Interface request domain: open.intl.palm.tencent.com

Interface description: Query the product version list.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this interface: DescribeVersionList.
Version	Yes	String	Common parameter. The value for this interface: 2025-07-15.
ProductName	Yes	String	The product name. For the Standard edition, fixed at: standard.

3. Output Parameters

Parameter Name	Type	Description
VersionList	Array of ProductVersionInfo	The version information list. See the ProductVersionInfo structure.
RequestId	String	The unique request ID, returned for each request.

4. Examples

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": "Invalid parameter value"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Data Structures

Common Business Structures

PalmInfo

Single palm registration information.

Name	Type	Description
PalmState	PalmState	The palm status.
RegisterType	RegisterType	The registration method.
PreRegisterTime	Timestamp	The mobile palm registration time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
RegisterTime	Timestamp	The palm registration completion time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
ExpireTime	Timestamp	The palm print expiration time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

TimeRule

Name	Type	Description
AllowDateRange	DateRange	The allowed verification date range. Empty means no limit.
DisallowDateList	Date[]	The list of disallowed verification dates.
AllowDayOfWeekList	DayOfWeek[]	The valid days of the week.
AllowTimePeriodList	TimePeriod[]	The daily allowed access time periods.

DateRange

Name	Type	Description
StartDate	Date	The start date.
EndDate	Date	The end date.

Date

Name	Type	Description
Year	Integer	The year.
Month	Integer	The month.
Day	Integer	The day.

TimeOfDay

Name	Type	Description
Hours	Integer	The hour.
Minutes	Integer	The minute.
Seconds	Integer	The second.

TimePeriod

Name	Type	Description
StartTime	TimeOfDay	The start time.
EndTime	TimeOfDay	The end time.
MaxVerificationCount	Integer	The allowed number of verifications. 0 means no limit.

UserRule

Name	Type	Description
UserTags	UserTagInfo[]	The user tag list.
UserInfos	UserInfo[]	The user information list.

UserTagInfo

Name	Type	Description
UserTagId	String	The unique user tag identifier.
UserTagName	String	The user tag name.

UserInfo

Name	Type	Description
UserId	String	The unique user identifier.
UserName	String	The user name.

OrderBy

The sorting condition.

Name	Type	Description
Field	VerificationRecordOrderField	The sort field.
Order	SortOrder	The sort direction.

Image

Image.

Name	Type	Description
Data	String	The image data, which requires base64.
ThreePointList	Array of Pointf	The three-point data.
ImageType	ImageType	The image type. See the ImageType enum.
DataDigest	String	The MD5 computed over the image data.

Pointf

Point.

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

Feature

Feature.

Name	Type	Description
FeatureValue	String	The feature value.
FeatureType	FeatureType	The feature type. See the FeatureType enum.
FeatureDigest	String	The feature signature.
FeatureDimension	Integer	The 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 this is true.
UserId	String	The user ID being additionally verified.
VerifyId	String	The additional verification ID.
VerifyType	VerifyType	The additional verification type. See the VerifyType enum.
HighSimilarityUserIdList	Array of String	Returned when the additional verification type is high-similarity verification, indicating the list of high-similarity user IDs that require additional verification.

PalmFeatureDetail

Palm print feature detail.

Name	Type	Description
PalmId	String	The palm print ID.
Status	PalmStatus	The palm print status. See the PalmStatus enum.
ImageType	ImageType	The image type. See the ImageType enum.
Feature	Feature	The feature. See the Feature structure.
PalmDirection	PalmPaasPalmDirection	The palm print direction. See the PalmPaasPalmDirection enum.
PalmDataVersion	Integer	The 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 is automatically incremented. During data synchronization, the system uses a version comparison mechanism: only when the locally stored version number is strictly greater than the version number obtained during synchronization does the local data need to be overwritten.
UserId	String	The user ID.
Operation	PalmPaasOperation	The operation type. See the PalmPaasOperation enum.

ProductVersionInfo

Product version information.

Name	Type	Description
ProductVersion	String	The Palm product algorithm version, provided by the integrated product, e.g., v20250715.
ProductVersionCreateTime	Integer	The product version creation time.
Status	Integer	The Palm product algorithm version type. 1: the currently used version; 2: the version pending upgrade.
OldProductName	String	The original product name.

CustomFieldValueItem

The user-dimension custom additional verification field value item.

Name	Type	Description
FieldName	String	The 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).

Interface-Specific Structures

Palm Print Management Interfaces

PalmPaasPalmInfo

The single palm registration information returned by the Query Palm Print interface (DescribePalm).

Note: This structure is used only for palm print management interfaces, and its field set differs from the PalmInfo used by user management interfaces (no PreRegisterTime, with additional PalmDirection / MobileRegisterTime).

Name	Type	Description
PalmState	PalmPaasPalmState	The palm status. See the PalmPaasPalmState enum.
PalmDirection	PalmPaasPalmDirection	The palm direction. See the PalmPaasPalmDirection enum.
RegisterTime	Integer	The registration time, a Unix second-level timestamp.
ExpireTime	Integer	The palm print expiration time, a Unix second-level timestamp. Returned only when the user's palm print is in the mobile palm pre-registration stage (PalmState=2, pending activation); not returned in other states.
MobileRegisterTime	Integer	The mobile palm registration time.
RegisterType	PalmPaasRegisterType	The registration type. See the PalmPaasRegisterType enum.

User Management Interfaces

CreateUserResponsePartialFailureError

The partial failure error information of the Create User interface.

Name	Type	Description
NotExistUserTagIdList	Array of String	The list of non-existent user tag IDs.

ModifyUserResponsePartialFailureError

The partial failure error information of the Modify User interface.

Name	Type	Description
NotExistUserTagIdList	Array of String	The list of non-existent user tag IDs.

DescribeUserResponseUserTag

The element structure of the output parameter UserTagList of the Query User (DescribeUser) interface.

Field Name	Type	Description
UserTagId	String	The user tag ID.
UserTagName	String	The user tag name.

DescribeUserListResponseUser

The element structure of the output parameter UserList of the Query User Information List (DescribeUserList) interface.

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

DescribeUserListResponseUserTag

The element structure of the output parameter UserList[i].UserTagList of the Query User Information List (DescribeUserList) interface.

Field Name	Type	Description
UserTagId	String	The user tag ID.
UserTagName	String	The user tag name.

User Tag Management Interfaces

DescribeUserTagListResponseUserTagItem

The element structure of the output parameter UserTagList of the Query User Tag List (DescribeUserTagList) interface.

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

UserTagNode

The user tag level path node structure, used to represent the complete level path from the root tag to the current tag.

Field Name	Type	Description
UserTagId	String	The user tag ID.
UserTagName	String	The user tag name.
Level	Integer	The tag level: 0=L1 (top level), 1=L2 (second level), 2=L3 (third level).

UserTag

The user tag information structure.

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

UserTagTreeNode

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

Field Name	Type	Description
UserTagId	String	The tag ID.
UserTagName	String	The tag name.
UserCount	Integer	The number of users associated with the tag.
Level	Integer	The level depth: 0=L1, 1=L2, 2=L3.
ParentTagId	String	The parent tag ID. Empty for a top-level tag.
Children	Array of UserTagTreeNode	The child tag nodes.

User Access Scope

AccessScopeItem

The element structure of the output parameter AccessScopeList of the Query User Access Scope (DescribeUserAccessScope) interface.

Field Name	Type	Description
SceneId	String	The scene ID.
SceneName	String	The scene name.
SceneGroupId	String	The scene group ID.
SceneGroupName	String	The scene group name.
DeviceSn	String	The device SN (empty when no device is bound).
DeviceName	String	The device name (empty when no device is bound).
VerifyRules	Array of VerifyRuleInfo	The list of bound verification rules (an empty array when no rule is bound).

VerifyRuleInfo

The verification rule information structure.

Field Name	Type	Description
VerifyRuleId	String	The verification rule ID.
VerifyRuleName	String	The verification rule name.

AccessScopeSummary

The structure of the output parameter Summary of the Query User Access Scope Summary (DescribeUserAccessScopeSummary) interface.

Field Name	Type	Description
SceneGroupCount	Integer	The number of accessible scene groups.
SceneCount	Integer	The number of accessible scenes.
DeviceCount	Integer	The number of accessible devices.

Device Management Interfaces

DescribeDeviceListResponseDevice

The element structure of the output parameter DeviceList of the Query Device List (DescribeDeviceList) interface.

Field Name	Type	Description
DeviceSn	String	The device serial number.
DeviceType	String	The device type.
DeviceName	String	The device name.
HeartbeatTime	Timestamp	The device heartbeat time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
ModuleHeartbeatTime	Timestamp	The module heartbeat time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
SystemVersion	String	The system version.
AppVersion	String	The application version.
ModuleType	String	The module type.
ModuleVersion	String	The module version.
ModuleExpireTime	Timestamp	The module expiration time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
Status	DeviceStatus	The device's real-time status.
SceneId	String	The bound scene ID.
SceneName	String	The bound scene name.
CreatedTime	Timestamp	The device creation time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

Scene Management Interfaces

DescribeSceneListResponseSceneItem

The element structure of the output parameter SceneList of the Query Scene List (DescribeSceneList) interface.

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

DescribeSceneGroupListResponseSceneGroupItem

The element structure of the output parameter SceneGroupList of the Query Scene Group List (DescribeSceneGroupList) interface.

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

Verification Record Interfaces

DescribeVerificationRecordListResponseVerificationRecord

The element structure of the output parameter VerificationRecordList of the Query Verification Record List (DescribeVerificationRecordList) interface.

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

Verification Rule Interfaces

DescribeVerifyRuleListResponseVerifyRuleItem

The element structure of the output parameter VerifyRuleList of the Query Verification Rule List (DescribeVerifyRuleList) interface.

Field Name	Type	Description
VerifyRuleId	String	The globally unique ID of the verification rule.
VerifyRuleName	String	The verification rule name.
EnableTimeRule	Boolean	Whether the time rule is enabled.
TimeRule	TimeRule	The time rule. See the TimeRule structure.
EnableUserRule	Boolean	Whether the user rule is enabled.
UserRule	UserRule	The user rule. See the UserRule structure.
EnableWebhookRule	Boolean	Whether the Webhook rule is enabled.
BindSceneIdList	Array of String	The list of bound scene IDs.
CreatedTime	Timestamp	The creation time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, e.g., "2025-07-03T09:30:15.500Z".

Enum Types

PalmState

The palm status.

Return type: string, with values being 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, with values being the enum value names in the table below.
The user status indicates the status of each 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 palm is activated
user_state_abnormal	Abnormal: the user status is abnormal (at least one palm is abnormal, and no palm is activated)
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, with values being the enum value names in the table below.

Enum Value	Description
verification_medium_unspecified	Unspecified medium
palm	Palm
card	Card
code	Code

NotifyQrCodeScanEventRequestQrCodeScanEventType

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

Return type: string, with values being 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, with values being 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, with values being 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

The registration type.

Return type: string, with values being the enum value names in the table below.

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

PalmDirection

The palm print direction.

Return type: string, with values being 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

The additional verification method.

Return type: string, with values being 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	The last four digits of the phone number
custom_field	Custom field digit verification
qr_code	QR code tap verification

VerificationRecordSource

The verification record source.

Return type: string, with values being the enum value names in the table below.

Enum Value	Description
verification_record_source_unspecified	Unspecified source
device	Reported by the device
mobile	Reported by the mobile
server	Reported by the server
h5	Reported by H5
wechat	Reported by the WeChat Mini Program

DeviceStatus

The device status.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
0	Device status unspecified
1	Online
2	Offline

VerificationRecordOrderField

The verification record sort field.

Return type: string, with values being the enum value names in the table below.

Enum Value	Description
verification_record_order_field_unspecified	Unspecified
verification_time	Verification time

SortOrder

The sort direction.

Return type: string, with values being the enum value names in the table below.

Enum Value	Description
sort_order_unspecified	Unspecified
asc	Ascending
desc	Descending

ImageType

The image type.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
1	Rgb
2	Ir

PalmPaasPalmDirection

The palm direction.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
1	Left hand
2	Right hand

FeatureType

The feature type.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
1	float32
2	int8
3	int7

PalmStatus

The palm print data status.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
1	Normal
2	Deleted

PalmPaasOperation

The operation type.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
1	Create
2	Update
3	Delete

PalmPaasPalmState

The palm status.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
1	Pending collection: the user exists but has not registered a palm
2	Pending activation: the user has enabled mobile palm registration but has not yet bound a palm
3	Activated: the user has bound a palm via an offline device
100	First registration, awaiting additional verification
101	High-similarity status
102	The user was mis-bound
103	The user has enabled mobile palm registration, but this user was found during a mobile palm search while another user was binding their palm

PalmPaasRegisterType

The registration type.

Return type: integer, with values being 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, with values being the enum values in the table below.

Enum Value	Description
1	No more data
2	More data available

AlgorithmStrategy

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

Return type: integer, with values being the enum values in the table below.

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

HighSimilarityResolutionStrategy

The resolution strategy when a high-similarity user is detected during palm registration.

Return type: integer, with values being the enum values in the table below.

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

CheckError

The registration check error code.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
0	Unspecified
1	High-similarity user detected

VerifyType

The additional verification type.

Return type: integer, with values being the enum values in the table below.

Enum Value	Description
0	Unspecified, the default value
1	High-similarity additional verification
2	Does not meet the first-level threshold but meets the second-level threshold, and the Auxiliary Background Image comparison threshold does not pass
3	Mobile palm registration additional verification
4	New registration type additional verification

VerifyResult

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

Return type: integer, with values being the enum values in the table below.

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

GrantType

The grant type.

Return type: string, with values being the enum value names in the table below.

Enum Value	Description
grant_type_unspecified	Unspecified; defaults to client_credential_user
client_credential_user	Applicable to scenarios where a third-party platform integrates the Mobile Palm Registration SDK. In this case, the UserId field must also be passed in.
client_credential	Applicable to scenarios where an ordinary server calls the open interfaces. The UserId field does not need to be passed in. This type must be used when calling the open interfaces of the Palm Application Platform.

QrCodeScanState

The QR code scan status.

Return type: string, with values being the enum value names in the table below.

Enum Value	Description
pending	Awaiting scan
scanned	Scanned, awaiting information entry
success	QR Code Palm Registration succeeded
failed	QR Code Palm Registration failed
expired	The QR Code Palm Registration session has expired

ResponseFormat

The response data format.

Return type: string, with values being the enum value names in the table below.

Enum Value	Description
metadata	Returns metadata (default, recommended); returns all fields except 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

The QR code session purpose.

Return type: string, with values being 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 it → palm registration and binding
tap_register	Tap Code Palm Registration: the app generates a QR code (carrying user information) → the device scans it → palm registration and binding
tap_verify	Tap Code Additional Verification: the app generates a QR code (carrying user information) → the device scans it → identity verification

Common Structures

Error

Name	Type	Description
Code	String	The error code.
Message	String	The error message.

Error Codes

Function Description

If the Error field is present in the return result, it indicates that the API interface 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"
  }
}

Code in Error indicates the error code, and Message indicates the specific information for that error.

Common Error Codes

Error Code	Description
InvalidParameter	Parameter error (including errors in parameter format, type, etc.)
InvalidParameterValue	Invalid parameter value
MissingParameter	Missing parameter error; a required parameter was not filled in
UnknownParameter	Unknown parameter error; passing extra undefined parameters will cause an error
AuthFailure	CAM signature/authentication error
InternalError	Internal error. The business must uniformly use InternalError or the InternalError.xxx form to indicate an internal error.
InvalidAction	The interface does not exist
UnauthorizedOperation	Unauthorized operation
RequestLimitExceeded	The number of requests exceeded the frequency limit
NoSuchVersion	The interface version does not exist
UnsupportedRegion	The interface does not support the specified region
UnsupportedOperation	The operation is not supported
ResourceNotFound	The resource does not exist
LimitExceeded	The quota limit was exceeded
ResourceUnavailable	The resource is unavailable
ResourceInsufficient	Insufficient resources
ResourceExhausted	Insufficient resource quota or rate limit reached
FailedOperation	The operation failed
ResourceInUse	The resource is in use
DryRunOperation	DryRun operation; indicates that the request would have succeeded, but the DryRun parameter was passed
ResourcesSoldOut	The resources are sold out
OperationDenied	The operation was denied

Business Error Codes

Error Code	Description
InvalidParameterValue.FiltersLimitExceed	The number of Filters exceeds the limit
InvalidParameterValue.PageLimitExceed	The pagination parameter exceeds the limit
InvalidParameterValue.PageTokenExpired	The pagination token has expired
InvalidParameterValue.PageTokenSignatureFailure	The pagination token signature verification failed
InvalidParameterValue.PageTokenQueryMismatch	The pagination token query condition does not match
ResourceNotFound.TenantNotFound	The specified tenant does not exist, or you do not have permission to access this tenant
InvalidParameterValue.UserIdEmpty	The user ID is empty
InvalidParameterValue.UserIdLengthNotAllowed	The user ID length does not meet the limit
InvalidParameterValue.UserIdShouldOnlyContainLettersAndDigits	The user ID can only contain letters and digits
InvalidParameterValue.UserIdShouldOnlyContainGraphicsAscii	The user ID can only contain ASCII graphic characters (ASCII range: 33-126)
InvalidParameterValue.UserNameEmpty	The user name is empty
InvalidParameterValue.UserNameLengthNotAllowed	The user name length does not meet the limit
InvalidParameterValue.UserNameOrPasswordEmpty	The user name or password is empty
InvalidParameterValue.PhoneNoEmpty	The phone number is empty
InvalidParameterValue.PhoneNoLengthNotAllowed	The phone number length does not meet the limit
InvalidParameterValue.InvalidPhoneNo	The phone number format is incorrect
InvalidParameterValue.PhysicalCardNoLengthNotAllowed	The physical card number length does not meet the limit
InvalidParameterValue.PhysicalCardNoShouldOnlyContainLettersAndDigits	The physical card number can only contain letters and digits
InvalidParameterValue.PalmIdEmpty	The palm print ID is empty
InvalidParameterValue.SessionIdEmpty	The session ID is empty
InvalidParameterValue.SessionIdLengthNotAllowed	The session ID length does not meet the limit
InvalidParameterValue.SessionNotExist	The session does not exist
InvalidParameterValue.InvalidUserId	The user ID format is incorrect; it can only contain digits, letters, and hyphens
InvalidParameterValue.RegisterTypeNotAllowed	The registration type does not meet the limit
InvalidParameterValue.UserTagIdEmpty	The user tag ID is empty
InvalidParameterValue.UserTagIdLengthNotAllowed	The user tag ID length does not meet the limit
InvalidParameterValue.InvalidUserTagId	The user tag ID format is incorrect
InvalidParameterValue.UserTagNameEmpty	The user tag name is empty
InvalidParameterValue.UserTagNameLengthNotAllowed	The user tag name length does not meet the limit
InvalidParameterValue.DeviceSnEmpty	The device SN is empty
InvalidParameterValue.DeviceSnLengthNotAllowed	The device SN length does not meet the limit
InvalidParameterValue.DeviceSnShouldOnlyContainLettersAndDigits	The device SN can only contain letters and digits
InvalidParameterValue.InvalidDeviceSn	The device SN format is incorrect
InvalidParameterValue.DeviceNameEmpty	The device name is empty
InvalidParameterValue.DeviceNameLengthNotAllowed	The device name length does not meet the limit
InvalidParameterValue.ErrDeviceNameInvalid	The device name format is incorrect
InvalidParameterValue.SceneIdEmpty	The scene ID is empty
InvalidParameterValue.SceneIdLengthNotAllowed	The scene ID length does not meet the limit
InvalidParameterValue.SceneIdShouldOnlyContainLettersAndDigits	The scene ID can only contain letters and digits
InvalidParameterValue.InvalidSceneId	The scene ID format is incorrect
InvalidParameterValue.SceneNameEmpty	The scene name is empty
InvalidParameterValue.SceneNameLengthNotAllowed	The scene name length does not meet the limit
InvalidParameterValue.SceneGroupIdEmpty	The scene group ID is empty
InvalidParameterValue.SceneGroupIdLengthNotAllowed	The scene group ID length does not meet the limit
InvalidParameterValue.SceneGroupIdShouldOnlyContainLettersAndDigits	The scene group ID can only contain letters and digits
InvalidParameterValue.InvalidSceneGroupId	The scene group ID format is incorrect
InvalidParameterValue.SceneGroupNameEmpty	The scene group name is empty
InvalidParameterValue.SceneGroupNameLengthNotAllowed	The scene group name length does not meet the limit
InvalidParameterValue.VerifierIdEmpty	The verifier ID is empty
InvalidParameterValue.VerifierIdLengthNotAllowed	The verifier ID length does not meet the limit
InvalidParameterValue.VerifierIdShouldOnlyContainLettersAndDigits	The verifier ID can only contain letters and digits
InvalidParameterValue.InvalidVerifierId	The verifier ID format is incorrect
InvalidParameterValue.VerifierNameEmpty	The verifier name is empty
InvalidParameterValue.VerifierNameLengthNotAllowed	The verifier name length does not meet the limit
InvalidParameterValue.QrCodeScanSessionIdEmpty	The QR Code Palm Registration session ID is empty
InvalidParameterValue.QrCodeScanSessionTtlNotAllowed	The expected lifetime of the QR Code Palm Registration session 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 within the scene group
FailedOperation.DuplicateSceneGroupNameInSceneGroup	Duplicate scene group name within the scene group
FailedOperation.DeviceSceneBindingLimitExceeded	The device-scene binding exceeds the limit
FailedOperation.QrCodeExpired	The QR Code Palm Registration QR code has expired
FailedOperation.QrCodeFinished	The QR Code Palm Registration QR code has already been used
FailedOperation.QrCodeStatusInvalid	The QR Code Palm Registration QR code status is invalid
FailedOperation.BindPalmUserIdAndUserNameNotMatch	The user ID and user name for binding the palm print 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 it is 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 obtain 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 via the PaaS channel
InternalError.DeleteUserPalmByPaaSChannelFailed	Failed to delete the user's palm via the PaaS channel
InternalError.DescribeUserPalmByPaaSChannelFailed	Failed to query the user's palm via the PaaS channel
InternalError.CreateAccessTokenFailed	Failed to create the open interface access token
InternalError.CreateDeviceAccessTokenFailed	Failed to create the open interface device access token
InternalError.DescribeSecretKeyFailed	Failed to query the open interface 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	The image MD5 is 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	The verification user ID does not match
FailedOperation.VerifyIdExpire	The verification ID has expired
FailedOperation.PalmIdAlreadyExist	The palm ID already exists
FailedOperation.HighSimilarity	A high-similarity palm exists
FailedOperation.PalmCapacityFull	The user's palm print search hot library capacity has reached its 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	The SMS verification code is empty
InvalidParameterValue.RefreshTokenEmpty	The refresh token is empty
InvalidParameterValue.SmsCodeNotMatch	The SMS verification code is incorrect
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	The SMS verification code is being sent too frequently
ResourceExhausted.SmsMaxVerifyAttempts	Too many verification code attempts
FailedOperation.SmsSendFailed	Failed to send the SMS

Version History​

Introduction​

Overview​

Glossary​

API Overview​

Function Classification​

Authentication Management Interfaces​

User Management Interfaces​

User Tag Management Interfaces​

User Palm Management Interfaces​

Device Management Interfaces​

Scene Management Interfaces​

Verification Record Interfaces​

Verification Rule Interfaces​

QR Code Palm Registration Interfaces​

PalmMa Login Interfaces​

Palm Print Management Interfaces (Palm Algorithm Platform)​

How to Call​

Basic Call Flow​

Request Structure​

1. Service Endpoint​

2. Communication Protocol​

3. Request Method​

4. Character Encoding​

Common Parameters​

Request Header Example​

Signature Method​

Why Signing Is Required​

Applying for Security Credentials​

Signature Process (v3)​

Signature Demo (Python)​

Common Signature Failure Error Codes​

Return Result​

Successful Response​

Error Response​

Common Error Codes​

Parameter Types​

Partial Failure​

What Is Partial Failure​

How to Use Partial Failure​

Example Scenarios​

Scenario 1: Create a user and batch bind tags​

Best Practices​

Interfaces That Support Partial Failure​

Authentication Management Interfaces​

Obtain Access Credentials​

1. Interface Description​

2. Input Parameters​

3. Output Parameters​

4. Examples​

Input Example​

Output Example​

Error Output Example​

Query Authorization Information​

1. Interface Description​

2. Input Parameters​

3. Output Parameters​

4. Examples​

Input Example​

Output Example​

Error Output Example​

User Management Interfaces​

Create User​

1. Interface Description​

2. Input Parameters​

3. Output Parameters​

4. Examples​

Input Example​

Output Example​

Partial Failure Output Example​

Error Output Example​

Modify User​

1. Interface Description​

2. Input Parameters​

3. Output Parameters​

4. Examples​

Input Example​

Output Example​

Partial Failure Output Example​

Error Output Example​

Version History

Introduction

Overview

Glossary

API Overview

Function Classification

Authentication Management Interfaces

User Management Interfaces

User Tag Management Interfaces

User Palm Management Interfaces

Device Management Interfaces

Scene Management Interfaces

Verification Record Interfaces

Verification Rule Interfaces

QR Code Palm Registration Interfaces

PalmMa Login Interfaces

Palm Print Management Interfaces (Palm Algorithm Platform)

How to Call

Basic Call Flow

Request Structure

1. Service Endpoint

2. Communication Protocol

3. Request Method

4. Character Encoding

Common Parameters

Request Header Example

Signature Method

Why Signing Is Required

Applying for Security Credentials

Signature Process (v3)

Signature Demo (Python)

Common Signature Failure Error Codes

Return Result

Successful Response

Error Response

Common Error Codes

Parameter Types

Partial Failure

What Is Partial Failure

How to Use Partial Failure

Example Scenarios

Scenario 1: Create a user and batch bind tags

Best Practices

Interfaces That Support Partial Failure

Authentication Management Interfaces

Obtain Access Credentials

1. Interface Description

2. Input Parameters

3. Output Parameters

4. Examples

Input Example

Output Example

Error Output Example

Query Authorization Information

1. Interface Description

2. Input Parameters

3. Output Parameters

4. Examples

Input Example

Output Example

Error Output Example

User Management Interfaces

Create User

1. Interface Description

2. Input Parameters

3. Output Parameters

4. Examples

Input Example

Output Example

Partial Failure Output Example

Error Output Example

Modify User

1. Interface Description

2. Input Parameters

3. Output Parameters

4. Examples

Input Example

Output Example

Partial Failure Output Example

Error Output Example