> For the complete documentation index, see [llms.txt](https://docs.fill-easy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fill-easy.com/sino-connect.md).

# Sino Connect

Documentation for China NFC eID for the various endpoints that we offer.

Should be used in conjuction with the SDK provided by Fill Easy, to read Chinese ID card data.

Clients retrieve the `reqId` from their mobile application after the NFC scan. Pass it to NFC Poll to retrieve the encrypted card data, and optionally pass the same `reqId` to Face Recognition Request to have the live face compared against the card portrait during Face Recognition Poll.

## NFC Poll

> Used in conjunction with the SDK that we provide.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"Sino Connect","description":"Documentation for China NFC eID for the various endpoints that we offer.\n\n\nShould be used in conjuction with the SDK provided by Fill Easy, to read\nChinese ID card data.\n\n\nClients retrieve the `reqId` from their mobile application after the NFC\nscan. Pass it to NFC Poll to retrieve the encrypted card data, and\noptionally pass the same `reqId` to Face Recognition Request to have the\nlive face compared against the card portrait during Face Recognition Poll.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"responses":{"BadRequest":{"description":"Bad Request - Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message"}}}}},"paths":{"/sino-connect/nfc/callback":{"post":{"tags":["Sino Connect"],"summary":"NFC Poll","description":"Used in conjunction with the SDK that we provide.","operationId":"nfcPoll","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reqid"],"properties":{"reqid":{"type":"string","minLength":1,"description":"Request ID from NFC scan"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["message","token"],"properties":{"message":{"type":"string","description":"Status message"},"token":{"type":"string","description":"JWE encrypted token containing NFC data"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Face Recognition Request

> Initialize a face recognition session by passing your redirect URL.\
> \
> Returns a \*\*launch URL\*\* (open on a \*\*mobile browser\*\*) and a \*\*JWT\*\* \*\*\`token\`\*\* that you must keep for polling status.\
> Use the returned \*\*\`url\`\*\* to open an in-app web view or the system browser on the phone.\
> After the user completes or cancels the H5 flow, the browser is redirected to your provided callback URL.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"Sino Connect","description":"Documentation for China NFC eID for the various endpoints that we offer.\n\n\nShould be used in conjuction with the SDK provided by Fill Easy, to read\nChinese ID card data.\n\n\nClients retrieve the `reqId` from their mobile application after the NFC\nscan. Pass it to NFC Poll to retrieve the encrypted card data, and\noptionally pass the same `reqId` to Face Recognition Request to have the\nlive face compared against the card portrait during Face Recognition Poll.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}},"schemas":{"RedirectUri":{"type":"string","description":"Redirect URI after user authorization.\n\nBrowser: HTTPS URL to your website.\n\niOS: HTTPS Universal link\n\nAndroid: Package name (com.filleasy.app)\n"}}},"paths":{"/sino-connect/face-rec/request":{"post":{"tags":["Sino Connect"],"summary":"Face Recognition Request","description":"Initialize a face recognition session by passing your redirect URL.\n\nReturns a **launch URL** (open on a **mobile browser**) and a **JWT** **`token`** that you must keep for polling status.\nUse the returned **`url`** to open an in-app web view or the system browser on the phone.\nAfter the user completes or cancels the H5 flow, the browser is redirected to your provided callback URL.","operationId":"faceReqRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect"],"properties":{"redirect":{"$ref":"#/components/schemas/RedirectUri"},"reqId":{"type":"string","description":"Optional request ID from the NFC scan (the same value passed to NFC Poll). When supplied, the live face captured during the liveness flow is compared against that card's portrait at Face Recognition Poll, and the match is returned there. Omit it for a liveness-only check."}}}}}},"responses":{"200":{"description":"200 Success","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"token":{"type":"string"},"url":{"type":"string"}}}}}}}}}}}
```

## Face Recognition Poll

> Used to poll for the face recognition result after user action.

```json
{"openapi":"3.1.0","info":{"title":"Fill Easy Services","version":"1.0.0"},"tags":[{"name":"Sino Connect","description":"Documentation for China NFC eID for the various endpoints that we offer.\n\n\nShould be used in conjuction with the SDK provided by Fill Easy, to read\nChinese ID card data.\n\n\nClients retrieve the `reqId` from their mobile application after the NFC\nscan. Pass it to NFC Poll to retrieve the encrypted card data, and\noptionally pass the same `reqId` to Face Recognition Request to have the\nlive face compared against the card portrait during Face Recognition Poll.\n"}],"servers":[{"url":"sandbox.staging-api.fill-easy.com"}],"security":[{"ClientID":[],"ClientSecret":[]}],"components":{"securitySchemes":{"ClientID":{"type":"apiKey","description":"Client ID in x-client-id header.","name":"x-client-id","in":"header"}}},"paths":{"/sino-connect/face-rec/callback":{"post":{"tags":["Sino Connect"],"summary":"Face Recognition Poll","description":"Used to poll for the face recognition result after user action.","operationId":"faceReqPoll","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"200 Success","content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Status message"},"token":{"type":"string","description":"JWE encrypted token. Decrypts to an object containing the captured `faceImage` (raw base64), `livenessResult` (the liveness verdict as readable text), and — only when a `reqId` was supplied to Face Recognition Request — `similarityScore` (the 0–100 face-match score between the live face and the NFC portrait) plus `similarityResult`: \"Match\" when `similarityScore` ≥ 45, otherwise \"No match\", or the compare error status if the comparison could not run."}}}}}},"202":{"description":"Pending","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}}
```