Tencent Palm Service-side API Documentation (v2.3.0)

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

Version History

Version	Release Date	Update Description
v2.3.0	2026-07-13	New APIs • Added DescribeUserAccessScope (Query User Access Scope) and DescribeUserAccessScopeSummary (Query User Access Scope Summary) APIs • Added DescribeUserTagTree (Query User Tag Tree Structure) API APIs Opened Externally • SendPalmMaSmsCode (Send SMS Verification Code) and LoginPalmMaSmsCode (SMS Verification Code Login) APIs are changed from internal to externally open; a new "PalmMa Login APIs" category is added • CreateQrCodeScanSession (Create QR Code Palm Registration Session) and DescribeQrCodeScanSession (Query QR Code Palm Registration Session Status) APIs are changed from internal to externally open API Parameter Changes • The LoginPalmMaSmsCode API adds PhoneNo (phone number verification) and GrantType (grant type) parameters; SmsCode and SessionId are changed to optional • The DescribeQrCodeScanSession API response adds the PhoneNo (phone number) field • The DescribeQrCodeScanUser API response adds the PhoneNo (phone number) field • The DescribeUserTag API response adds ParentTagId (parent tag ID), Level (level depth), ChildrenCount (number of direct child tags), UserCount (number of users associated with the tag), and PathNodes (hierarchical path) fields • The DescribeUserTagList API response UserTagItem adds ParentTagId, Level, ChildrenCount, and PathNodes fields New Enums and Data Structures • Added GrantType enum (grant type: client_credential_user / client_credential) • Added UserTagNode common data structure (tag hierarchical path node) • Added UserTag common data structure (user tag information, including PathNodes hierarchical path) • Added UserTagTreeNode common data structure (tag tree node) • Added AccessScopeItem, AccessScopeSummary, and VerifyRuleInfo common data structures • Added error code FailedOperation.PhoneNoAlreadyExists (1113, Phone number already exists) • The DeviceStatus enum serialization is changed from string to integer (int32)
v2.2.0	2026-06-17	Version upgrade only; no API changes.
v2.1.0	2026-05-07	New APIs • Added 6 list query APIs: DescribeUserList (Query User Information List), DescribeUserTagList (Query User Tag List), DescribeDeviceList (Query Device List), DescribeSceneList (Query Scene List), DescribeSceneGroupList (Query Scene Group List), DescribeVerifyRuleList (Query Verification Rule List) API Parameter Changes • The CreateUser and ModifyUser APIs add the CustomFieldValue parameter (custom additional verification field value) • The DescribeUser API response adds the CustomFieldValue field • The DescribeUserList API adds PhoneNo, PhysicalCardNo, and UserTagId filter parameters; the response adds CreatedTime and UpdatedTime fields • The DescribeDeviceList API is opened externally; it adds Status, SceneId, and DeviceType filter parameters; the response adds Status, SceneId, SceneName, CreatedTime, and UpdatedTime fields • The DescribeVerificationRecordList API adds SceneGroupIds, SceneGroupName, and OrderBy parameters; the response adds SceneGroupId and SceneGroupName fields • The NotifyQrCodeScanEvent API adds the EventType parameter (QR code scan event type) • The Verify API's VerifyResult parameter type is changed from Integer to the VerifyResult enum (values: 1: Success, 2: Failure); valid values are now explicit (semantics unchanged; historical callers passing 1/2 remain fully compatible) New Enums and Data Structures • Added DeviceStatus enum (device status: online / offline) • Added AdditionalVerifyMethod enum (additional verification method: phone_no / custom_field / qr_code) • Added VerificationRecordOrderField enum (verification record ordering field) • Added SortOrder enum (sort direction: asc / desc) • Added QrCodeScanEventType enum (QR code scan event type, used as the value of NotifyQrCodeScanEvent.EventType) • Added VerifyResult enum (additional verification result, used as the value of the Verify API's VerifyResult parameter) • Added OrderBy common data structure (sorting condition)
v2.0.0	2026-04-03	• Added Palm Print management related APIs (8 APIs: CreatePalm, BindPalm, SearchMobilePalm, Verify, DeletePalm, DescribePalm, SynchronizePalmFeature, DescribeVersionList) • Added authentication API DescribePalmLicense (Query License Information) • The DescribeUser API output adds the UserState (user status) field • The DescribeUserPalm API output adds UserName (user name), UserState (user status), PalmDirection (main palm direction), LeftPalm (left palm registration information), and RightPalm (right palm registration information) fields • The DescribeQrCodeScanUser API output adds 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 UserState enum type • Added Image, Pointf, Feature, VerifyInfo, PalmFeatureDetail, and ProductVersionInfo common business data structures • Added ImageType, PalmPaasPalmDirection, FeatureType, PalmStatus, PalmPaasOperation, HasMoreType, AlgorithmStrategy, and VerifyType enum types
v1.8.1	2026-03-05	• The DescribeUser API output adds PalmDirection (palm direction), LeftPalm (left palm registration information), RightPalm (right palm registration information), and CreateTime (user creation time) fields • Added PalmInfo common business data structure (single palm registration information)
v1.8.0	2026-02-02	• Added DescribeScene (Query Scene Details) API under Scene Management • Added DescribeDevice (Query Device Details) API under Device Management • The CreateScene API adds SceneId (optional) and ScenarioStrategy (required) parameters • The ModifyScene API adds the ScenarioStrategy (required) parameter • Added 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 CreateVerifyRule API's EnableWebhookRule parameter is changed to optional; if not provided, the default is true.
v1.7.0	2026-01-05	• Added user tag management (4 APIs: CreateUserTag, ModifyUserTag, DeleteUserTag, DescribeUserTag) • User management APIs support tag binding and partial failure (CreateUser and ModifyUser support UserTagIdList and PartialFailure parameters) • Added complete documentation for the partial failure mechanism • Unified API naming (interface tables use Action names) • Added 14 business error codes (user tag, pagination, session, tenant related) • Optimized 4 error codes' format; removed 39 deprecated error codes

Introduction

Overview

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

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

Glossary

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

Term	Description
AppId	The unique application identifier. It is a unique identifier 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 across different AppIds.
RGB	Color image.
IR	Infrared image.
Three points	Data output after image detection and alignment.
Feature value	Data output after an image is fed into the recognition model.
Palm Print Search Hot Library	A high-performance data structure loaded in GPU memory or RAM to improve retrieval and matching efficiency. Data in the system is divided into search hot library data stored in GPU memory or RAM, and general storage data (including regular databases, object storage, file storage, etc.).
Device type	The model identifier of a palm verification device. Current values: M3, M3B, M4, O1, O2.
Module type	The model identifier of the recognition module used by the palm verification device. Current 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.

Authentication APIs

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

User Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateUser	Create user	20
ModifyUser	Modify user	20
DeleteUser	Delete user	20
DescribeUser	Query user	20
DescribeUserList	Query user information list	20
DescribeUserAccessScope	Query user access scope	20
DescribeUserAccessScopeSummary	Query user access scope summary	20

User Tag Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateUserTag	Create user tag	20
ModifyUserTag	Modify user tag	20
DeleteUserTag	Delete user tag	20
DescribeUserTag	Query user tag	20
DescribeUserTagList	Query user tag list	20
DescribeUserTagTree	Query user tag tree structure	20

User Palm Management APIs

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

Device Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateDevice	Create device	20
ModifyDevice	Modify device	20
DeleteDevice	Delete device	20
DescribeDevice	Query device details	20
DescribeDeviceList	Query device list	20

Scene Management APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateScene	Create scene	20
ModifyScene	Modify scene	20
DeleteScene	Delete scene	20
DescribeScene	Query scene details	20
DescribeSceneList	Query scene list	20
CreateSceneGroup	Create scene group	20
ModifySceneGroup	Modify scene group	20
DeleteSceneGroup	Delete scene group	20
DescribeSceneGroupList	Query scene group list	20

Verification Record APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateVerificationRecord	Create verification record	20
DescribeVerificationRecordList	Query verification record list	20
DescribeVerificationRecord	Query verification record (push only)	20

Verification Rule APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateVerifyRule	Create verification rule	20
ModifyVerifyRule	Modify verification rule	20
DeleteVerifyRule	Delete verification rule	20
DescribeVerifyRule	Query verification rule	20
DescribeVerifyRuleList	Query verification rule list	20
CheckAccessPermission	Check access permission (callback only)	20

QR Code Palm Registration APIs

Interface name	Interface function	Frequency limit (times/second/AppId)
CreateQrCodeScanSession	Create QR code palm registration session	20
NotifyQrCodeScanEvent	User QR code scan event notification	20
BindQrCodeScanPalm	QR code palm print binding	20
DescribeQrCodeScanSession	Query QR code palm registration session status	20
DescribeQrCodeScanUser	Query QR code palm registration user information	20

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

Palm Print Management APIs (Palm Algorithm Platform)

Interface name	Interface function	Frequency limit (times/second/AppId)
CreatePalm	Create palm print	20
BindPalm	Bind palm print	20
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 scenarios	Request headers
Signature + Token	Most management APIs (user, device, scene, palm print, etc.)	`Authorization` + `X-Palm-Openapi-Token`
Token only	QR code palm registration APIs (NotifyQrCodeScanEvent, BindQrCodeScanPalm, DescribeQrCodeScanSession, DescribeQrCodeScanUser)	`X-Palm-Openapi-Token` only; `Authorization` not required

Notes:

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

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

Token-only APIs only need to carry X-Palm-Openapi-Token; no signature computation is required.

Request Structure

The request structure of the Palm API is as follows:

1. Service Endpoint

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

Default access domain (recommended): open.intl.palm.tencent.com (example only; the actual access domain is subject to assignment, and private deployment scenarios are supported)
Region-specific access (extensible for multi-region deployments): for example, open.intl.palm.tencent.com (example only; the actual access domain is subject to assignment)

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

2. Communication Protocol

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

3. Request Method

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

4. Character Encoding

All requests and responses use UTF-8 encoding.

Common Parameters

Common parameters are used to identify the user's identity, sign the request, and provide 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 API to operate. 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	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 AppId, SecretId, and SecretKey. Keep the above information safe and pass it in API requests as required by your business.
X-Palm-Openapi-Token	String	Yes	The temporary security credential Token. Before calling a Tencent API, you must first obtain the access credential via the [Obtain Access Credentials] API (Action: CreateAccessToken). Note that the access credential is time-limited and must be reapplied for after it expires.

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

Verify the identity of the requester to ensure that the request comes from a user holding a valid key.
Protect the data in transit and prevent the request from being tampered with.

Applying for Security Credentials

The security credential used in this document is a key, which includes a SecretId and a SecretKey.

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

You must strictly safeguard your security credentials to avoid leakage; otherwise, your property security will be endangered. If a leak occurs, disable the security credential immediately.

The specific steps for applying for a security credential 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 a key pair.

Signature Process (v3)

The API currently supports only 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 binding a user's palm print as an example to introduce the signature computation 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 computation process in detail.

Concatenate the canonical request string

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

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

Field	Description
HTTPRequestMethod	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 URL of the HTTP request. It is fixed as an empty string `""` for POST requests, and for GET requests it is the string content after the question mark (?) in the URL, for example: `Limit=10&Offset=0`. Note: CanonicalQueryString needs to be URL-encoded per RFC3986, with the UTF-8 charset. 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, containing 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 requests. Concatenation rules: 1) Convert both the header key and value to lowercase and trim leading and trailing spaces, then concatenate in the format `key:value\n`; 2) For multiple headers, concatenate in ascending ASCII order of the header key (lowercase). The computed result in this example is: `content-type:application/json\nhost:open.intl.palm.tencent.com\nx-palm-appid:223\nx-tc-nonce:c68bf577-60f1-45d8-a9ef-7a0a8c59690f\nx-tc-timestamp:1752587686\n`. Note: The content-type must match what is actually sent. Some programming language network libraries add a charset value automatically even if not specified; if the value used at signing differs from what is sent, the server will return a signature verification failure.
SignedHeaders	The header information involved in the signature, indicating which headers of this request participated in the signature, corresponding one-to-one with the headers contained in CanonicalHeaders. content-type and host are required headers. Concatenation rules: 1) Convert all header keys to lowercase; 2) Concatenate multiple header keys (lowercase) in ascending ASCII order, separated by semicolons (;). In this example: `content-type;host;x-palm-appid;x-tc-nonce;x-tc-timestamp`
HashedRequestPayload	The hash value of the request body (Payload, i.e., the Body). The computation pseudocode is `Lowercase(HexEncode(Hash.SHA256(RequestPayload)))`, i.e., perform a SHA256 hash 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 represented 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 in 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 header, taken as 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 be consistent with the UTC standard time date converted from the common parameter X-TC-Timestamp; service is the product name and must match the product domain being called, which is `palm` here. The computed result in this example is: `2025-07-15/palm/tc3_request`.
HashedCanonicalRequest	The hash value of the canonical request string concatenated in the preceding step. The computation pseudocode is `Lowercase(HexEncode(Hash.SHA256(CanonicalRequest)))`. The computed result in this example is 3044b1650deaa09d3d1e93d63c15fd76c7c764254b3a1cba9c6b321eda191774.

⚠️ Notes:

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

Timestamp must be the current system time, and you must ensure the system time is synchronized with the standard time. If the difference exceeds five minutes, it will definitely fail. If the system time is not synchronized with the standard time for a long time, requests may fail after running for a while, returning 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

Compute the signature

Compute the derived signing key, with the pseudocode as follows:

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

The derived keys SecretDate, SecretService, and SecretSigning are binary data that may contain non-printable characters. Their hex string representations for printing are, respectively:
2fbd1f93d8d1aae5c0a4e2df255519752e1e4be521b9edae832930379544679c,
45589385000e5972fe3fb6ca9f07339289dee6e33e0b5bb9022308d69eb15fc9,
a116ccc06739ebac6c1c54514ace4229c98847c5f1ee5abc395eafab262b0246.
Note that in different programming languages, the order of parameters in the HMAC library function may differ; use the actual situation as the standard. Here, the pseudocode key parameter comes first, and the message parameter comes after. Standard library functions usually provide return values in binary format, and may also provide print-friendly hex-format return values; 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`.

Compute the signature, with the pseudocode as follows:

Signature = HexEncode(HMAC_SHA256(SecretSigning, StringToSign))

The computed result in this example is f4b012d34bd468efb5cb90cb6c326ed42ec0f7de22accb38350606d95fa6b5db.

Concatenate Authorization

Concatenate Authorization in 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, as described above. In this example: `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. The computed result in this example 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 with the request must be exactly the same as the content used in the signature computation process; otherwise, a signature mismatch error will be returned. You can compare and troubleshoot by printing the actual request content, capturing network packets, etc.

Signature Demo (Python)

The following is the complete signature process demo code implemented in Python:

def get_openapi_request_header(secret_id, secret_key, access_token, appid, action, nonce, data, svr_version = "standard"):
    version = "2025-07-15"
    timestamp = int(time.time())
    host = "open.intl.palm.tencent.com"
    service = "palm"
    algorithm = "TC3-HMAC-SHA256"
    date = datetime.utcfromtimestamp(timestamp).strftime("%Y-%m-%d")
 
    # ************* 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: Compute the signature *************
    # Signature digest function
    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	The signature has expired. The difference between the Timestamp and the time the server received the request must not exceed five minutes.
AuthFailure.SecretIdNotFound	The key does not exist. Check in the console whether the key is disabled, and whether characters were missing or extra when copying.
AuthFailure.SignatureFailure	Signature error. This may be caused by a signature computation error, a mismatch between the signature and the content actually sent, or an incorrect SecretKey.
AuthFailure.TokenFailure	Temporary certificate Token error.
AuthFailure.InvalidSecretId	The key is invalid (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 be described in the documentation. The maximum limit for returned JSON data 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 size of the returned data using the filtering or pagination features in the API documentation.

Note: As long as the request is processed normally by the server, the HTTP status code of the response is 200. For example, 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 API as an example, a successful call returns the following:

{
  "Response": {
    "UserId": "user123456",
    "UserName": "John Doe",
    "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 is used to uniquely identify an API request, facilitating troubleshooting.
The remaining fields are business fields defined by the specific API.

Error Response

A failed call returns the following:

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

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

Common Error Codes

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

Parameter Types

The 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. In different languages, it is recommended to use the largest integer type for definition.	123456
Boolean	Boolean, true/false	true
Float	Floating-point number	3.14
Double	Double-precision floating-point number	3.1415926535
Date	String, in date format	"2022-01-01"
Timestamp	String, in time format	"2022-01-01 00:00:00"
Timestamp RFC3339	String, in time format, RFC3339 standard time format; it is recommended to parse it with a standard library	"2022-01-01T00:00:20.021Z"
Binary	Binary content, which must be requested and parsed with 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.
You can retry the failed operations based on the returned error information.

How to Use Partial Failure

APIs that support partial failure provide the PartialFailure parameter:

Request 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 there are failed items, the response contains the PartialFailureError field, which describes the reason for the 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": "John Doe",
  "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: If you need to retry, after fixing tag003 you must pass 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 creation, modification, and other operations, 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 correct return result, 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.
- After fixing the cause of failure, re-initiate the request.
- Note: For overwrite operations such as batch binding of user tags, when retrying you must pass the complete tag list (including previously successful items), rather than only retrying 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).

APIs That Support Partial Failure

The following APIs support the partial failure mechanism:

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

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

Authentication APIs

Obtain Access Credentials

1. API Description

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

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateAccessToken.
Version	Yes	String	Common parameter. The value for this API is: 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 hash of the customer's key. The computation rule is: hex.EncodeToString(sha256.Sum256(secretKey)).
GrantType	Yes	String	Grant type. When calling the open APIs 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, that is: a. The mobile side uses the SDK to initiate registration or to obtain the liveness video upload address; b. The third-party server needs to apply for an access credential for a specified user, to be used by the SDK; c. In this case, the `UserId` field must be passed as well. - client_credential: Applicable to scenarios where a regular server calls the open APIs, that is: a. This type is not bound to a specific user and only uses the application-level key to obtain the access credential; b. The `UserId` field does not need to be passed.
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. You can subsequently access other APIs based on this credential.
ExpiresIn	Integer	The validity period of the AccessToken, in seconds. The token is invalid after it expires.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

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

Output Example

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

Error Output Example

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

Query Authorization Information

1. API Description

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

API description: Query server-side authorization information, including the palm database capacity limit, the current usage, and the License expiration time.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribePalmLicense.
Version	Yes	String	Common parameter. The value for this API is: 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 it expires.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

{
  "AppId": 223
}

Output Example

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

Error Output Example

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

User Management APIs

Create User

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateUser.
Version	Yes	String	Common parameter. The value for this API is: 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), such as "(+86)13530612342". If the area code is not provided, "(+86)" is used by default.
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	The custom additional verification field value (digits only). It is recommended to fill it in when the tenant enables the custom_field additional verification method.

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. Example

Input Example

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

{
  "UserId": "user123456",
  "UserName": "John Doe",
  "PhoneNo": "(+86)13530612342",
  "PhysicalCardNo": "CARD001",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true
}

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. API Description

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

API description: Used to modify user information, supporting the update of the user's basic information.

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: ModifyUser.
Version	Yes	String	Common parameter. The value for this API is: 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), such as "(+86)13530612342". If the area code is not provided, "(+86)" is used by default.
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	The custom additional verification field value (digits only). It is recommended to fill it in when the tenant enables the custom_field additional verification method.

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. Example

Input Example

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

{
  "UserId": "user001",
  "UserName": "John Doe",
  "PhoneNo": "(+86)13800138000",
  "UserTagIdList": ["tag001", "tag002"],
  "PartialFailure": true,
  "CustomFieldValue": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteUser.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "UserId": "user001"
}

Output Example

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

Error Output Example

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

Query User

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUser.
Version	Yes	String	Common parameter. The value for this API is: 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), such as "(+86)13530612342". If the area code is not provided, "(+86)" is used by default.
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, such as "2025-07-03T09:30:15.500Z".
UserState	UserState	The user status. See the UserState enum.
CustomFieldValue	String	The custom additional verification field value. Empty when not set.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "UserId": "user001",
    "UserName": "John Doe",
    "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",
    "CustomFieldValue": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
UserId	No	String	The unique user identifier. Supports fuzzy query.
UserName	No	String	The user name. Supports fuzzy query.
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. Filters users that have the specified tag.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 100.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The number of users that meet the conditions.
UserList	Array of DescribeUserListResponseUser	The user list. See the DescribeUserListResponseUser structure.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

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

Output Example

{
  "Response": {
    "TotalCount": 1,
    "UserList": [
      {
        "UserId": "user001",
        "UserName": "John Doe",
        "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"
      }
    ],
    "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. API Description

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

API description: Query the detailed information of the scenes, devices, access time periods, etc. that the user can access, based on the user ID.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserAccessScope.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
UserId	Yes	String	The unique user identifier.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 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 dimension). See the AccessScopeItem structure.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

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

Output Example

{
  "Response": {
    "TotalCount": 1,
    "AccessScopeList": [
      {
        "SceneId": "scene001",
        "SceneName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserAccessScopeSummary.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "UserId": "user001"
}

Output Example

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

Error Output Example

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

User Tag Management APIs

Create User Tag

1. API Description

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

API description: Used to create a new user tag.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateUserTag.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "UserTagName": "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. API Description

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

API description: Used to modify user tag information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: ModifyUserTag.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "UserTagId": "tag001",
  "UserTagName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteUserTag.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "UserTagId": "tag001"
}

Output Example

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

Error Output Example

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

Query User Tag

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserTag.
Version	Yes	String	Common parameter. The value for this API is: 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 (level 2), 2=L3 (level 3).
ChildrenCount	Integer	The number of direct child tags.
UserCount	Integer	The number of users associated with the tag.
PathNodes	Array of UserTagNode	The complete hierarchical 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. Example

Input Example

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

{
  "UserTagId": "tag001"
}

Output Example

{
  "Response": {
    "UserTagId": "tag001",
    "UserTagName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserTagList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
UserTagName	No	String	The tag name. Supports fuzzy search.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 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. Example

Input Example

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

{
  "UserTagName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserTagTree.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "RootTagId": ""
}

Output Example

{
  "Response": {
    "Tree": [
      {
        "UserTagId": "tag001",
        "UserTagName": "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 APIs

Delete User Palm Information

1. API Description

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

API description: Used to delete the palm information of a specified user. After deletion, palm registration is required again.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteUserPalm.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

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

Output Example

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

Error Output Example

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

Query User Palm Information

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeUserPalm.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "UserId": "user001"
}

Output Example

{
  "Response": {
    "UserId": "user001",
    "PalmState": "registered",
    "UserName": "John Doe",
    "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 APIs

Create Device

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateDevice.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "DeviceSn": "device001",
  "DeviceName": "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. API Description

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

API description: Used to modify device information, supporting the update of the device's basic information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: ModifyDevice.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "DeviceSn": "device001",
  "DeviceName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteDevice.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "DeviceSn": "device001"
}

Output Example

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

Error Output Example

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

Query Device Details

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeDevice.
Version	Yes	String	Common parameter. The value for this API is: 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, such as "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. Example

Input Example

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

{
  "DeviceSn": "device001"
}

Output Example

{
  "Response": {
    "DeviceSn": "device001",
    "DeviceName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeDeviceList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
DeviceSn	No	String	The device serial number. Exact match.
DeviceName	No	String	The device name. Supports fuzzy search.
Status	No	DeviceStatus	The device status filter.
SceneId	No	String	The scene ID. Filters devices bound to the specified scene.
DeviceType	No	String	The device type. For values, see the Glossary.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 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. Example

Input Example

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

{
  "DeviceName": "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 APIs

Create Scene

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateScene.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneName": "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. API Description

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

API description: Used to modify scene information, supporting the update of the scene's basic information, binding devices, and verification rules.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: ModifyScene.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneId": "scene001",
  "SceneName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteScene.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneId": "scene001"
}

Output Example

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

Error Output Example

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

Query Scene Details

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeScene.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneId": "scene001"
}

Output Example

{
  "Response": {
    "SceneId": "scene001",
    "SceneName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateSceneGroup.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneGroupName": "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. API Description

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

API description: Used to modify scene group information, supporting the update of the scene group's basic information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: ModifySceneGroup.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneGroupId": "scenegroup001",
  "SceneGroupName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteSceneGroup.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SceneGroupId": "scenegroup001"
}

Output Example

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

Error Output Example

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

Query Scene List

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeSceneList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
SceneIdList	No	Array of String	The list of scene IDs. Exact match. Supports batch query.
SceneName	No	String	The scene name. Supports fuzzy search.
SceneGroupId	No	String	The scene group ID. Filters scenes belonging to the specified scene group.
DeviceSn	No	String	The device serial number. Exact match.
VerifyRuleId	No	String	The verification rule ID. Filters scenes bound to the specified rule.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 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. Example

Input Example

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

{
  "SceneName": "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeSceneGroupList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
SceneGroupIdList	No	Array of String	The list of scene group IDs. Exact match. Supports batch query.
SceneGroupName	No	String	The scene group name. Supports fuzzy search.
ParentSceneGroupId	No	String	The parent scene group ID. When passed, only the direct child scene groups under that parent are returned; if not passed, all scene groups are returned.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 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. Example

Input Example

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

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

Output Example

{
  "Response": {
    "TotalCount": 1,
    "SceneGroupList": [
      {
        "SceneGroupId": "sg001",
        "SceneGroupName": "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 APIs

Create Verification Record

1. API Description

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

API description: Used to create a verification record.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateVerificationRecord.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
UserId	Yes	String	The user ID.
VerificationTime	Yes	Timestamp	The verification time, in RFC3339 format, such as "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.

3. Output Parameters

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

4. Example

Input Example

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

{
  "UserId": "user001",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "VerifierId": "verifier001",
  "VerifierName": "Jane Smith"
}

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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeVerificationRecordList.
Version	Yes	String	Common parameter. The value for this API is: 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, such as "2025-07-03T09:30:15.500Z".
EndTime	No	Timestamp	The verification end time, in RFC3339 format, such as "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. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 100.
OrderBy	No	OrderBy	The sorting condition. See the OrderBy structure.

3. Output Parameters

Parameter Name	Type	Description
TotalCount	Integer	The number of verification records that meet the conditions.
VerificationRecordList	Array of DescribeVerificationRecordListResponseVerificationRecord	The verification record list. See the DescribeVerificationRecordListResponseVerificationRecord structure.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

{
  "UserId": "user001",
  "UserName": "John Doe",
  "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": "John Doe",
        "VerificationTime": "2024-06-10T09:15:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device001",
        "SceneId": "scene001",
        "SceneName": "Shenzhen Nanshan Access Control No.1",
        "VerifierId": "verifier001",
        "VerifierName": "Jane Smith"
      },
      {
        "UserId": "user001",
        "UserName": "John Doe",
        "VerificationTime": "2024-06-11T18:30:00+08:00",
        "VerificationMedium": "palm",
        "DeviceSn": "device002",
        "SceneId": "scene002",
        "SceneName": "Shenzhen Nanshan Access Control No.2",
        "VerifierId": "verifier002",
        "VerifierName": "Alex Lee"
      }
    ],
    "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. API Description

Push endpoint: provided by the customer to the platform; the platform actively pushes.

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

The pushed content is the verification record details (see the table below). After the customer receives the push, returning HTTP 200 OK is sufficient.

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, such as "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.
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": "John Doe",
  "VerificationTime": "2024-07-15T09:30:15.500Z",
  "VerificationMedium": "palm",
  "DeviceSn": "device001",
  "SceneId": "scene001",
  "SceneName": "Shenzhen Nanshan Access Control No.1",
  "VerifierId": "verifier001",
  "VerifierName": "Jane Smith",
  "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
}

After the customer receives the push, returning HTTP 200 OK is sufficient; no business data needs to be returned.

Verification Rule APIs

Create Verification Rule

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreateVerifyRule.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
VerifyRuleName	Yes	String	The verification rule name.
EnableTimeRule	Yes	Boolean	Whether to enable the time rule. false means not enabled, true means enabled.
TimeRule	No	TimeRule	The time rule. It must be configured when the time rule is enabled. See the TimeRule structure.
EnableUserRule	Yes	Boolean	Whether to enable the user rule. false means all users, true means specified users.
UserRule	No	UserRule	The user rule. It 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, the default is 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. Example

Input Example

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

{
  "VerifyRuleName": "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": "John Doe"}
    ]
  },
  "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. API Description

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

API description: Used to modify existing verification rule information.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: ModifyVerifyRule.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
VerifyRuleId	Yes	String	The globally unique verification rule ID.
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. Example

Input Example

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

{
  "VerifyRuleId": "vr_20250715001",
  "VerifyRuleName": "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. API Description

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

API description: Used to delete a specified verification rule.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeleteVerifyRule.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "VerifyRuleId": "vr_20250715001"
}

Output Example

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

Error Output Example

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

Query Verification Rule

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeVerifyRule.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "VerifyRuleId": "vr_20250715001"
}

Output Example

{
  "Response": {
    "VerifyRuleId": "vr_20250715001",
    "VerifyRuleName": "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": "John Doe"
        }
      ]
    },
    "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeVerifyRuleList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
VerifyRuleIdList	No	Array of String	The list of verification rule IDs. Exact match. Supports batch query.
VerifyRuleName	No	String	The verification rule name. Supports fuzzy search.
Offset	No	Integer	The offset. The default is 0.
Limit	No	Integer	The number of records to return. The default is 20, and the maximum is 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. Example

Input Example

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

{
  "VerifyRuleName": "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. API Description

Callback endpoint: provided by the customer to the platform; the platform actively calls it.

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

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, such as "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 description of the access reason, such as "Hit verification rule: visitor reservation 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": "John Doe",
  "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": "Hit verification rule: visitor reservation 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 APIs

QR code palm registration service, suitable for open user registration scenarios.

The QR code is generated by the palm verification device. After the user registers their palm, the palm verification device displays 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 from scanning the QR code: https://app.intl.palm.tencent.com/local_h5/brushAuth?ocode=***&session_id=***&session_key=***&app_id=***&access_token=***

QR Code Scan Event Notification

1. API Description

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

API description: Used to notify the server of a user's QR code scan event. This API only verifies the Token, not the signature; the Authorization field is not required in the HTTP header.

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

Note: This API requires 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 API is: NotifyQrCodeScanEvent.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
SessionId	Yes	String	The session ID.
EventType	No	NotifyQrCodeScanEventRequestQrCodeScanEventType	The event type. See the NotifyQrCodeScanEventRequestQrCodeScanEventType enum. When 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. Example

Input Example

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

{
  "SessionId": "session_001"
}

Output Example

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

Error Output Example

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

QR Code Palm Print Binding

1. API Description

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

API description: Used to bind a palm print via QR code. This API only verifies the Token, not the signature; the Authorization field is not required in the HTTP header.

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

Note: This API requires 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 API is: BindQrCodeScanPalm.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

{
  "SessionId": "session_001",
  "UserId": "user001",
  "UserName": "John Doe",
  "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. API Description

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

API description: Used to query QR code palm registration user information. This API only verifies the Token, not the signature; the Authorization field is not required in the HTTP header.

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

Note: This API requires 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 API is: DescribeQrCodeScanUser.
Version	Yes	String	Common parameter. The value for this API is: 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. Example

Input Example

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

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

Output Example

{
  "Response": {
    "UserId": "user001",
    "PalmState": "registered",
    "UserName": "John Doe",
    "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. API Description

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

API description: Creates a QR code palm registration session, used to generate the QR code or URL for users to scan and register their palm. It supports three session purposes: scan registration (scan_register), tap registration (tap_register), and tap verification (tap_verify). This API only verifies the Token, not the signature; the Authorization field is not required in the HTTP header.

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

Note: This API requires 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 API is: CreateQrCodeScanSession.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
Ttl	No	String	The expected session lifetime. Takes effect for scan_register/tap_register scenarios. For tap_verify scenarios, it is determined by the tenant configuration (this field does not take effect). When not specified, the default is 1 hour for scan_register and 15 minutes for tap_register. Up to 24 hours. String format, such as "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. When not passed or passed as scan_register, it is scan registration (default behavior); tap_register is tap registration; tap_verify is tap verification.
UserId	No	String	The user ID. Required for tap_register/tap_verify scenarios.
UserName	No	String	The user name. Required for tap_register scenarios, optional for tap_verify scenarios.
PhoneNo	No	String	The phone number. Optional in tap registration scenarios. When passed, it checks whether it matches 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, such as "2025-07-03T09:30:15.500Z".
AppId	String	The application ID. Subsequent palm registration requests for this session must carry it in the HTTP request header "X-Palm-Appid".
AccessToken	String	The access token. Subsequent 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, such as "2025-07-03T09:30:15.500Z".
SessionUrl	String	The session URL. For scan_register scenarios, it is a complete H5 link; for 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. Example

Input Example

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

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

Output Example

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

Error Output Example

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

Query QR Code Palm Registration Session Status

1. API Description

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

API description: Used to query the QR code palm registration session status. This API only verifies the Token, not the signature; the Authorization field is not required in the HTTP header.

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

Note: This API requires 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 API is: DescribeQrCodeScanSession.
Version	Yes	String	Common parameter. The value for this API is: 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 distinguishes whether it is a scan registration, tap registration, or tap verification scenario based on this field.
PhoneNo	String	The phone number (with area code).
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

{
  "SessionId": "session_001"
}

Output Example

{
  "Response": {
    "QrCodeScanState": "scanned",
    "UserId": "user001",
    "UserName": "John Doe",
    "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. API Description

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

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: SendPalmMaSmsCode.
Version	Yes	String	Common parameter. The value for this API is: 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 validation.
ExpireTime	Timestamp	The session expiration time, in RFC3339 string format, such as "2025-07-03T09:30:15.500Z".
ResendInterval	String	The session verification code resend interval, such as "60s".
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

{
  "PhoneNo": "+8613800138000"
}

Output Example

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

Error Output Example

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

1. API Description

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

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: LoginPalmMaSmsCode.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
SmsCode	No	String	The SMS verification code (verified each time; the code can only be used once). If SMS capability is not configured at deployment, this field does not need to be passed.
SessionId	No	String	The SessionId returned when sending the verification code (one-time use; becomes invalid immediately after successful verification). If SMS capability is not configured at 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 verify against the phone number bound to the backend user. If not passed, the verification is skipped.
GrantType	No	GrantType	Grant type. When calling the open APIs 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, that is: a. The mobile side uses the SDK to initiate registration or to obtain the liveness video upload address; b. The third-party server needs to apply for an access credential for a specified user, to be used by the SDK; c. In this case, the `UserId` field must be passed as well. - client_credential: Applicable to scenarios where a regular server calls the open APIs, that is: a. This type is not bound to a specific user and only uses the application-level key to obtain the access credential; b. The `UserId` field does not need to be passed. If not passed, the default is 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, such as "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, such as "2025-07-03T09:30:15.500Z".
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

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

Output Example

{
  "Response": {
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "AccessTokenExpireTime": "2025-07-03T11:30:15.500Z",
    "RefreshToken": "refresh_token_xxx",
    "RefreshTokenExpireTime": "2025-08-02T09:30:15.500Z",
    "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 APIs (Palm Algorithm Platform)

Create Palm Print

1. API Description

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

API description: Upload palm images to create a palm print and return the palm print ID, with two-factor authentication.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: CreatePalm.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
RgbImage	Yes	Image	The RGB image data. See the Image structure.
IrImage	Yes	Image	The infrared 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. Example

Input Example

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

{
  "RgbImage": {
    "Data": "... feature data, requires base64",
    "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, requires base64",
    "ThreePointList": [
      {"PointX": 279.19387799999998, "PointY": 283.87393200000002},
      {"PointX": 355.835083, "PointY": 282.88299599999999},
      {"PointX": 429.38259900000003, "PointY": 321.33651700000001}
    ],
    "ImageType": 2
  },
  "PalmDirection": 1
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue.PalmIdEmpty",
      "Message": "The palm print ID is empty"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

Bind Palm Print

1. API Description

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

API description: Bind an already-created palm print ID to a specified user, with two-factor authentication.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: BindPalm.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
UserId	Yes	String	The unique user identifier.
PalmId	Yes	String	The palm print ID.
IsForce	No	Boolean	Whether to force rebinding.
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. Example

Input Example

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

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

Output Example

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

Error Output Example

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

Mobile Palm Registration Search

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: SearchMobilePalm.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
ProductVersion	No	String	The palm product algorithm version, provided by the integrated product, such as v20250715.
RgbImage	Yes	Image	The RGB image data. See the Image structure.
IrImage	No	Image	The infrared image data, used to supplement the palm database 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. Example

Input Example

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

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

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InternalError",
      "Message": "Internal error"
    },
    "RequestId": "d6a4c45b-d30f-49c8-a724-ecc37d0f0c42"
  }
}

User Additional Verification

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: Verify.
Version	Yes	String	Common parameter. The value for this API is: 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 to be 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 verification is required. See the VerifyInfo structure.
PalmId	String	Returns the user's palm print ID when the additional verification succeeds.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

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

Output Example

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

Further Additional Verification Required Output Example

{
  "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. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DeletePalm.
Version	Yes	String	Common parameter. The value for this API is: 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 hand, 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. Example

Input Example

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

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

Output Example

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

Error Output Example

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

Query Palm Print

1. API Description

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

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

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribePalm.
Version	Yes	String	Common parameter. The value for this API is: 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 palm print information. See the PalmPaasPalmInfo structure.
RightPalm	PalmPaasPalmInfo	The right palm print information. See the PalmPaasPalmInfo structure.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

{
  "UserId": "user001"
}

Output Example

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

Error Output Example

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

Synchronize Palm Print Feature

1. API Description

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

API description: Synchronize palm print features.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: SynchronizePalmFeature.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
ProductVersion	Yes	String	The product version to synchronize, such as v20250715. This version number must match the version number on the device.
QueryPosition	Yes	String	The current synchronization position. Fill in an empty string for the first time, and use the QueryPosition data from the response for the next time.
DeviceId	Yes	String	The device ID. Currently it is only used for troubleshooting.
DisableFeature	No	Boolean	Prohibit returning the feature value. The 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 for continued synchronization; there may be other statuses in the future, and if added, the documentation will be updated accordingly.
QueryPosition	String	The current synchronization position.
RequestId	String	The unique request ID, returned for each request.

4. Example

Input Example

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

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

Output Example

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

Error Output Example

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

Query Product Version List

1. API Description

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

API description: Query the product version list.

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

2. Input Parameters

Parameter Name	Required	Type	Description
Action	Yes	String	Common parameter. The value for this API is: DescribeVersionList.
Version	Yes	String	Common parameter. The value for this API is: 2025-07-15.
ProductName	Yes	String	The product name. For the Standard version, this is fixed as: 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. Example

Input Example

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

{
  "ProductName": "standard"
}

Output Example

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

Error Output Example

{
  "Response": {
    "Error": {
      "Code": "InvalidParameterValue",
      "Message": "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, such as "2025-07-03T09:30:15.500Z".
RegisterTime	Timestamp	The palm registration completion time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".
ExpireTime	Timestamp	The palm print expiration time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

TimeRule

Name	Type	Description
AllowDateRange	DateRange	The allowed verification date range. Empty means no restriction.
DisallowDateList	Date[]	The list of dates on which verification is not allowed.
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	Year.
Month	Integer	Month.
Day	Integer	Day.

TimeOfDay

Name	Type	Description
Hours	Integer	Hours.
Minutes	Integer	Minutes.
Seconds	Integer	Seconds.

TimePeriod

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

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

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. Requires base64.
ThreePointList	Array of Pointf	The three-point data.
ImageType	ImageType	The image type. See the ImageType enum.
DataDigest	String	The MD5 computed for 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 returns true.
UserId	String	The user ID to be 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 additional verification, indicating the list of high-similarity user IDs to be verified.

PalmFeatureDetail

Palm print feature details.

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 automatically increments. During data synchronization, the system uses a version comparison mechanism: the local data needs to be overwritten only when the locally stored version number is strictly greater than the synchronized version number.
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, such as v20250715.
ProductVersionCreateTime	Integer	The product version creation time.
Status	Integer	The palm product algorithm version type. 1: the current version in use; 2: the version to be upgraded.
OldProductName	String	The original product name.

API-Specific Structures

Palm Print Management APIs

PalmPaasPalmInfo

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

Note: This structure is used only for palm print management APIs. Its field set differs from the PalmInfo used by user management APIs (no PreRegisterTime, but has 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 registration pending 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 APIs

CreateUserResponsePartialFailureError

The partial failure error information for the Create User API.

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

ModifyUserResponsePartialFailureError

The partial failure error information for the Modify User API.

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) API.

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) API.

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, such as "2025-07-03T09:30:15.500Z".
PalmRegisterTime	Timestamp	The main palm registration time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".
PalmExpireTime	Timestamp	The main palm feature expiration time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".
UserState	UserState	The user status.
CreatedTime	Timestamp	The user creation time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The user's last update time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

DescribeUserListResponseUserTag

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

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

User Tag Management APIs

DescribeUserTagListResponseUserTagItem

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

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 (level 2), 2=L3 (level 3).
ChildrenCount	Integer	The number of direct child tags.
PathNodes	Array of UserTagNode	The complete hierarchical 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, such as "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

UserTagNode

The user tag hierarchical path node structure, used to represent the complete hierarchical 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 (level 2), 2=L3 (level 3).

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 hierarchical 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 (DescribeUserTagTree) API.

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 top-level tags.
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) API.

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 rules are 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) API.

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 APIs

DescribeDeviceListResponseDevice

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

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, such as "2025-07-03T09:30:15.500Z".
ModuleHeartbeatTime	Timestamp	The module heartbeat time, in RFC3339 format, such as "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, such as "2025-07-03T09:30:15.500Z".
Status	DeviceStatus	The device real-time status.
SceneId	String	The bound scene ID.
SceneName	String	The bound scene name.
CreatedTime	Timestamp	The device creation time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

Scene Management APIs

DescribeSceneListResponseSceneItem

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

Field Name	Type	Description
SceneId	String	The scene ID.
SceneName	String	The scene name.
SceneGroupId	String	The ID of the scene group it belongs to.
SceneGroupName	String	The name of the scene group 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, such as "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

DescribeSceneGroupListResponseSceneGroupItem

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

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 top-level scene groups.
ParentSceneGroupName	String	The parent scene group name. This value is empty for top-level scene groups.
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, such as "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

Verification Record APIs

DescribeVerificationRecordListResponseVerificationRecord

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

Field Name	Type	Description
UserId	String	The user ID.
UserName	String	The user name.
VerificationTime	Timestamp	The verification time, in RFC3339 format, such as "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.

Verification Rule APIs

DescribeVerifyRuleListResponseVerifyRuleItem

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

Field Name	Type	Description
VerifyRuleId	String	The globally unique 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.
CreatedTime	Timestamp	The creation time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".
UpdatedTime	Timestamp	The last update time, in RFC3339 format, such as "2025-07-03T09:30:15.500Z".

Enums

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 represents the respective statuses 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 scan.
card	Card swipe.
code	Code scan.

NotifyQrCodeScanEventRequestQrCodeScanEventType

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

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

Enum Value	Description
qrcode_scan_event_type_unspecified	The event type is 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	The registration type is unspecified.
device	Device registration.
mobile	Mobile registration.

PalmDirection

The palm direction.

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

Enum Value	Description
palm_direction_unspecified	The palm direction is 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.

DeviceStatus

The device status.

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

Enum Value	Description
0	The device status is unspecified.
1	Online.
2	Offline.

VerificationRecordOrderField

The verification record ordering 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 capture; 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 incorrectly bound.
103	The user has enabled mobile palm registration, but the user was found during mobile palm registration when 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 version supports strategies A and B; the Max version 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: 100 User Demo On-device Recognition.
2	Strategy B: 50k User Access Control On-device Recognition.
3	Strategy C: 1M User eKYC Cloud Recognition.
4	Strategy D: 1M User eKYC Hybrid Recognition.

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) API.

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; by default equivalent 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 be passed as well.
client_credential	Applicable to scenarios where a regular server calls the open APIs; the UserId field does not need to be passed. This type must be used when calling the open APIs 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	Waiting to scan the code.
scanned	Scanned, waiting to fill in information.
success	QR code palm registration succeeded.
failed	QR code palm registration failed.
expired	The QR code palm registration QR code 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 fields other than SessionUrl and SessionImage.
url	Returns the QR code URL; returns SessionId, ExpireTime, and SessionUrl.
image	Returns the QR code image (PNG); returns SessionId, ExpireTime, and SessionImage.

QrCodeSessionType

The QR code session purpose.

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

Enum Value	Description
scan_register	Scan registration: the device generates a QR code → the user scans the code → palm registration and binding.
tap_register	Tap registration: the app generates a QR code (carrying user information) → the device scans the code → palm registration and binding.
tap_verify	Tap verification: the app generates a QR code (carrying user information) → the device scans the code → 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 exists in the return result, it indicates that the API call failed. For example:

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

The Code in Error indicates the error code, and the Message indicates the specific information of the 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 is not filled in.
UnknownParameter	Unknown parameter error; passing extra undefined parameters causes an error.
AuthFailure	CAM signature/authentication error.
InternalError	Internal error. Businesses must uniformly use InternalError or InternalError.xxx to indicate internal errors.
InvalidAction	The API does not exist.
UnauthorizedOperation	Unauthorized operation.
RequestLimitExceeded	The number of requests exceeds the rate limit.
NoSuchVersion	The API version does not exist.
UnsupportedRegion	The API does not support the region passed.
UnsupportedOperation	The operation is not supported.
ResourceNotFound	The resource does not exist.
LimitExceeded	The quota limit is exceeded.
ResourceUnavailable	The resource is unavailable.
ResourceInsufficient	Insufficient resources.
ResourceExhausted	Insufficient resource quota or the rate limit is reached.
FailedOperation	The operation failed.
ResourceInUse	The resource is in use.
DryRunOperation	DryRun operation, indicating that the request would have been successful; the DryRun parameter was just additionally passed.
ResourcesSoldOut	The resource is sold out.
OperationDenied	The operation is 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 QR code palm registration session expected lifetime does not meet the limit.
FailedOperation.UserNotExist	The user does not exist.
FailedOperation.UserAlreadyExists	The user already exists.
FailedOperation.UserIdAlreadyExists	The user ID already exists.
FailedOperation.PhoneNoAlreadyExists	The phone number already exists.
FailedOperation.UserPalmAlreadyBound	The user's palm is already bound.
FailedOperation.SceneNotExist	The scene does not exist.
FailedOperation.SceneAlreadyExists	The scene already exists.
FailedOperation.SceneGroupNotExist	The scene group does not exist.
FailedOperation.SceneGroupAlreadyExists	The scene group already exists.
FailedOperation.DuplicateSceneNameInSceneGroup	Duplicate scene name 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 palm registration QR code has expired.
FailedOperation.QrCodeFinished	The palm registration QR code has been used.
FailedOperation.QrCodeStatusInvalid	The palm registration QR code status is invalid.
FailedOperation.BindPalmUserIdAndUserNameNotMatch	The user ID and user name 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 bound to a scene.
FailedOperation.DeviceNotBoundWithScene	The device is not bound to a scene.
FailedOperation.UserTagNotExist	The user tag does not exist.
FailedOperation.UserTagAlreadyExists	The user tag already exists.
FailedOperation.UserTagNameAlreadyExists	The user tag name already exists.
InternalError.GetPaaSChannelFailed	Failed to get the PaaS channel.
InternalError.UpdateUserPalmFailed	Failed to update the user's palm.
InternalError.CreateUserTokenFailed	Failed to create the user token.
InternalError.BindUserPalmByPaaSChannelFailed	Failed to bind the user's palm 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 API access token.
InternalError.CreateDeviceAccessTokenFailed	Failed to create the open API device access token.
InternalError.DescribeSecretKeyFailed	Failed to query the open API access key.
FailedOperation.MemberNotExist	The member does not exist.
FailedOperation.MemberAlreadyExists	The member already exists.
FailedOperation.MemberLoginExpired	The member login has expired.
FailedOperation.NoAvailableVersion	No available version.
FailedOperation.UnknownImageType	Unknown image type.
FailedOperation.PicInconsistent	The image MD5 is inconsistent.
FailedOperation.LivenessCheckNoPass	Liveness detection failed.
FailedOperation.QualityCheckNoPass	Quality detection failed.
FailedOperation.LivenessWithVideoCheckNoPass	Liveness video detection failed.
FailedOperation.PalmIdNoExistInCache	The palmID 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 palmID already exists.
FailedOperation.HighSimilarity	A high-similarity palm exists.
FailedOperation.PalmCapacityFull	The user's palm print search hot library capacity has reached the upper 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	SMS verification codes are being sent too frequently.
ResourceExhausted.SmsMaxVerifyAttempts	Too many verification code attempts.
FailedOperation.SmsSendFailed	SMS sending failed.

Version History​

Introduction​

Overview​

Glossary​

API Overview​

Function Categories​

Authentication APIs​

User Management APIs​

User Tag Management APIs​

User Palm Management APIs​

Device Management APIs​

Scene Management APIs​

Verification Record APIs​

Verification Rule APIs​

QR Code Palm Registration APIs​

PalmMa Login APIs​

Palm Print Management APIs (Palm Algorithm Platform)​

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​

APIs That Support Partial Failure​

Authentication APIs​

Obtain Access Credentials​

1. API Description​

2. Input Parameters​

3. Output Parameters​

4. Example​

Input Example​

Output Example​

Error Output Example​

Query Authorization Information​

1. API Description​

2. Input Parameters​

3. Output Parameters​

4. Example​

Input Example​

Output Example​

Error Output Example​

User Management APIs​

Create User​

1. API Description​

2. Input Parameters​

3. Output Parameters​

4. Example​

Input Example​

Output Example​

Partial Failure Output Example​

Error Output Example​

Modify User​

1. API Description​

2. Input Parameters​

3. Output Parameters​

4. Example​

Input Example​

Output Example​

Partial Failure Output Example​

Error Output Example​

Version History

Introduction

Overview

Glossary

API Overview

Function Categories

Authentication APIs

User Management APIs

User Tag Management APIs

User Palm Management APIs

Device Management APIs

Scene Management APIs

Verification Record APIs

Verification Rule APIs

QR Code Palm Registration APIs

PalmMa Login APIs

Palm Print Management APIs (Palm Algorithm Platform)

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

APIs That Support Partial Failure

Authentication APIs

Obtain Access Credentials

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Input Example

Output Example

Error Output Example

Query Authorization Information

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Input Example

Output Example

Error Output Example

User Management APIs

Create User

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Input Example

Output Example

Partial Failure Output Example

Error Output Example

Modify User

1. API Description

2. Input Parameters

3. Output Parameters

4. Example

Input Example

Output Example

Partial Failure Output Example

Error Output Example