idcard-face-validate
Face to ID Match
Provides a three-factor consistency verification service for name, ID number, and facial photo. By comparing the photo with identity information, it returns consistency status and similarity score, assisting in determining user identity authenticity.
Usage Cost
30 coins/call
Quick Start
Use a unified response envelope and call directly from your backend.
https://openapi.toolkk.com/v1/idcard-face-validatecURL Example
curl --request POST \
--url 'https://openapi.toolkk.com/v1/idcard-face-validate' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "name": "张三",\n "idCardNo": "110105199003078887",\n "facePhotoUrl": "https://example.com/face.jpg"\n}'Python Example
import os
import requests
url = "https://openapi.toolkk.com/v1/idcard-face-validate"
payload = {
"name": "张三",
"idCardNo": "110105199003078887",
"facePhotoUrl": "https://example.com/face.jpg"
}
headers = {
"Content-Type": "application/json",
"X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"),
}
response = requests.request("POST", url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())Go Example
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
endpoint := "https://openapi.toolkk.com/v1/idcard-face-validate"
payload := []byte("{\n \"name\": \"张三\",\n \"idCardNo\": \"110105199003078887\",\n \"facePhotoUrl\": \"https://example.com/face.jpg\"\n}")
req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}Java Example
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ToolkkExample {
public static void main(String[] args) throws Exception {
String payload = "{\n \"name\": \"张三\",\n \"idCardNo\": \"110105199003078887\",\n \"facePhotoUrl\": \"https://example.com/face.jpg\"\n}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://openapi.toolkk.com/v1/idcard-face-validate"))
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.header("Content-Type", "application/json")
.header("X-API-Key", "YOUR_API_KEY")
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}PHP Example
<?php
$endpoint = 'https://openapi.toolkk.com/v1/idcard-face-validate';
$payload = "{\n \"name\": \"张三\",\n \"idCardNo\": \"110105199003078887\",\n \"facePhotoUrl\": \"https://example.com/face.jpg\"\n}";
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: YOUR_API_KEY',
],
CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
echo $response;Response Example
{
"code": "SUCCESS",
"message": "success",
"data": {
"result": "一致",
"similarity": 0.92,
"threshold": 0.7
}
}Examples illustrate the response structure. Actual results depend on the API response.
- Authentication
- Send X-API-Key in request headers
- Rate limit
- 600 req/min
- Timeout
- 5000 ms
Send your API Key in the X-API-Key header from your backend.
Check both HTTP status and business fields before treating a call as successful.
Use retries and backoff together with rate limits in high-frequency scenarios.
Request Fields
Send requests from your server with the key in the X-API-Key header.
Request Fields
The fields below are derived from example JSON for integration reference only.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| name | string | Unspecified | Unspecified | 张三 |
| idCardNo | string | Unspecified | Unspecified | 110105199003078887 |
| facePhotoUrl | string | Unspecified | Unspecified | https://example.com/face.jpg |
Request Example
{
"name": "张三",
"idCardNo": "110105199003078887",
"facePhotoUrl": "https://example.com/face.jpg"
}- Authentication
- Send X-API-Key in request headers
- Rate limit
- 600 req/min
- Timeout
- 5000 ms
Response Fields
Examples illustrate the response structure. Actual results depend on the API response.
Response Fields
The fields below are derived from example JSON for integration reference only.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| code | string | Unspecified | Unspecified | SUCCESS |
| message | string | Unspecified | Unspecified | success |
| data | object | Unspecified | Unspecified | {...} |
| data.result | string | Unspecified | Unspecified | 一致 |
| data.similarity | number | Unspecified | Unspecified | 0.92 |
| data.threshold | number | Unspecified | Unspecified | 0.7 |
Response Example
{
"code": "SUCCESS",
"message": "success",
"data": {
"result": "一致",
"similarity": 0.92,
"threshold": 0.7
}
}$.code == 200 Documentation
Capabilities, use cases, and considerations.
API Capabilities
This API provides a consistency verification service for facial features and ID card information. By inputting the user's name, ID card number, and a live-captured facial photo, the system will compare these three elements for a match, returning the comparison result (consistent or inconsistent), a similarity score, and a comparison threshold. This API can serve as an important auxiliary tool in real-name authentication processes.
Request and Response
- Request Parameters: Real name (
name), 18-digit ID card number (idCardNo), and a valid network address for the facial photo (facePhotoUrl) must be provided. - Return Results: The
resultfield indicates the comparison conclusion (e.g., "Consistent"), thesimilarityfield represents the facial similarity score (between 0-1), and thethresholdfield is the recommended judgment threshold. When the similarity is greater than or equal to the threshold, it is generally considered consistent.
Use Cases
- Financial Account Opening and Transactions: In financial services such as banking, securities, and insurance, assist in verifying user identity and preventing fraud risks.