search

userIAM Smart

hashtag
Hong Kong's eID

For further details, please refer to the official iAM Smart developer guidearrow-up-right.

hashtag
General Usage Flow

  1. Send a request to your service of choice (Authentication, AnonymousForm Filling, Signing, etc.)

  2. Send follow up request(s) to Poll Data to obtain the results.*

*As the data requires user approval, your system may have to short poll to obtain the results in a timely manner.

hashtag
Anonymous vs Authenticated Flow:

  • Anonymous: No prior authentication needed, single-step process Examples: Anonymous Form Filling, Anonymous Signing, Anonymous PDF Signing

  • Authenticated: Requires prior authentication, two-step process Examples: Form Filling, Signing, PDF Signing

hashtag
Multi-device user journey

There are 2 types of user journeys:

  1. single device (mobile with iAM Smart installed)

  2. two device (mobile with iAM Smart installed AND any second device)

The primary difference is that two device workflows typically includes displaying a iAM Smart website with a iAM Smart QR code that needs to be scanned to link the request across devices.

Implementation details are in the endpoints documentation.

hashtag
Authentication

post

Initialize user authentication with iAM Smart eID service.

Browser Flow:

Returns a TempAuthToken (store for subsequent calls) and a URL to iAM Smart's QR page. User scans the QR code with their iAM Smart mobile app, then the browser redirects to your specified redirect URL.

Mobile App Flow:

Returns a universal link to launch the iAM Smart authentication app. After authentication, iAM Smart returns an auth_code via GET request to your redirect URI. Your mobile app must handle this redirect URI and pass the auth_code to the token endpoint.

Redirect URI Requirements:

  • Browser: Must be an HTTPS URL registered with iAM Smart

  • Mobile: Must be a universal link or custom scheme (e.g., your-app://auth) that your mobile app can handle

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
langstring · enumOptional

iAM Smart App display language (case sensitive). Will default to 'en-US' if not specified

Default: en-USPossible values:
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
redirectstringRequired

Redirect URI after user authorization.

Browser: https URL to your website.

Mobile: Universal link (your-app://) or app scheme.

Example: https://www.yourwebsite.com/callback
scopestringOptional

Setting the scope is required only in cases where operations are chained, e.g auth + formfilling, auth + signing. By default, the scope is set to the value required for the operation. Requested scope of authorization based on available services. Multiple scopes should be space-separated. Valid scopes are: eidapi_auth, eidapi_profiles, eidapi_formFilling, eidapi_sign, eidapi_fr, eidapi_bulksign

Example: eidapi_auth eidapi_formFilling eidapi_signPattern: ^(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign)(\s+(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign))*$
Responses
chevron-right
200

Authentication request successfully initialized. Store the token for subsequent API calls.

application/json
tokenstringRequired

Store this token for subsequent API calls

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
urlstring · uriRequired

Browser: URL to iAM Smart QR page for scanning. Mobile: Universal link to launch iAM Smart app.

Example: https://hk.gov.iamsmart.testapp://auth?clientID=...
post
/iamsmart/v2/request/auth

hashtag
Form Filling

post

Request form filling data from authenticated user.

Pass the form details, source, and AuthToken (from Authentication endpoint) to initialize the form filling request.

Returns a temporary token to be used with Poll Data endpoint to retrieve the requested form filling details.

Note on Profile Fields:

If you request overlapping fields in both profileFields and formData.formFields, the profileFields takes precedence. You must display a consent page per iAM Smart UI/UX requirements when using profile fields.

Note on Form Fields:

The formFields array specifies which detail fields to request from the user. All requested fields will be displayed to the user in their iAM Smart app for approval.

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
tokenstringRequired

The authenticated user token from the Authentication workflow

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
Responses
chevron-right
200

Form filling request successfully initialized. Poll with the returned token to retrieve form data when ready.

application/json
tokenstringRequired

Use this token in Poll Data to retrieve form filling results

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
post
/iamsmart/v2/request/formfilling

hashtag
Signing

post

Request digital signature for a document hash using iAM Smart.

Pass the document details (name and SHA-256 hash), source platform, and the authenticated user token to initialize the signing request.

Returns a temporary token and HKIC check digits. Use the token with the Poll Data endpoint to retrieve the signature results after the user approves the signing request in their iAM Smart app.

Hash Requirements:

  • Must be a SHA-256 hash of the document content

  • Must be exactly 64 hexadecimal characters

  • Use SHA256withRSA signature algorithm (default)

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
tokenstringRequired

The authenticated user token from the Authentication workflow

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
namestring · max: 200Required

Document title displayed to user

Example: Sample Credit Card Application Form
hashstringRequired

SHA-256 hash of the document file's content (64 hex characters)

Example: af8b6f626242f214be360fa7d412e42dacb2f48bc11bb089019a912930019300Pattern: ^[a-f0-9]{64}$
servicestring · max: 200Optional

Service description to be displayed to user

Example: Digital Signing of Application Form
organisationstring · max: 200Optional

Organisation name

Example: Fill Easy Limited
Responses
chevron-right
200

Signing request successfully initialized. Poll with the returned token to get signature results.

application/json
tokenstringRequired

Use this token in Poll Data to retrieve signing results

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
hkicinteger · min: 1000 · max: 9999Required

HKIC check digits for verification

Example: 1524
post
/iamsmart/v2/request/signing

hashtag
PDF Signing

post

Request PDF document signing with embedded digital signature using iAM Smart.

Pass the PDF document details (name and base64-encoded hash), service description, and the authenticated user token to initialize the PDF signing request.

Returns a temporary token and HKIC check digits. Use the token with the Poll Data endpoint to retrieve the signed PDF after the user approves the signing request in their iAM Smart app.

File Hash Requirements:

  • Must be a base64-encoded hash of the PDF file

  • The signed PDF will be returned with the signature embedded

  • PDF signature will be visible in PDF readers that support digital signatures

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
tokenstringRequired

The authenticated user token from the Authentication workflow

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
namestring · max: 200Required

Document title displayed to user

Example: Landsurvey Purchase Form
fileHashstring · byteRequired

Base64-encoded hash of the PDF file

Example: R3fJTKFPwkRw019fLk+L19y91DVgI9hy/G7u6+YiECk=
servicestring · max: 200Required

Service description to be displayed to user

Example: Digital PDF Signing Powered by Fill Easy
hkicHashstringOptional

Hash of HKIC for verification (optional)

Pattern: ^[a-f0-9]{64}$
departmentstring · max: 100Optional

Department name (optional)

Responses
chevron-right
200

PDF signing request successfully initialized. Poll with the returned token to retrieve signed PDF when ready.

application/json
tokenstringRequired

Use this token in Poll Data to retrieve PDF signing results

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
hkicinteger · min: 1000 · max: 9999Required

HKIC check digits for verification

Example: 4303
post
/iamsmart/v2/request/pdf-signing

hashtag
Re-authentication

post

Re-authenticate a previously authenticated user to verify their identity again.

Pass the authenticated user token and source platform to initialize the re-authentication request. This is useful for high-security operations that require fresh user verification.

Returns a temporary token. Use this token with the Poll Data endpoint to retrieve the re-authentication results after the user approves the request in their iAM Smart app.

Use Cases:

  • Verify user identity before sensitive operations

  • Refresh user authentication for extended sessions

  • Comply with security policies requiring periodic re-verification

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
tokenstringRequired

The authenticated user token to re-validate

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
Responses
chevron-right
200

Re-authentication request successfully initialized. Poll with the returned token to get re-authentication results.

application/json
tokenstringRequired

Use this token in Poll Data to check re-authentication status

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
post
/iamsmart/v2/request/reauth

hashtag
CCIC

post
Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
Responses
chevron-right
200

Success

application/json
messagestringOptional
tokenstringOptional
post
/iamsmart/v2/request/ccic
200

Success

hashtag
Anonymous Form Filling

post

Request form filling data without requiring prior authentication.

This endpoint combines authentication and form filling in a single flow. Pass the scope, language, source, redirect URL, and form details to initialize the anonymous form filling request.

Returns a token and URL. The URL redirects users to iAM Smart where they can authenticate and approve the form filling request in one step.

Note on Profile Fields:

If you request overlapping fields in both profileFields and formData.formFields, the profileFields takes precedence. You must display a consent page per iAM Smart UI/UX requirements when using profile fields.

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
langstring · enumOptional

iAM Smart App display language (case sensitive). Will default to 'en-US' if not specified

Default: en-USPossible values:
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
redirectstringRequired

Redirect URI after user authorization.

Browser: https URL to your website.

Mobile: Universal link (your-app://) or app scheme.

Example: https://www.yourwebsite.com/callback
scopestringOptional

Setting the scope is required only in cases where operations are chained, e.g auth + formfilling, auth + signing. By default, the scope is set to the value required for the operation. Requested scope of authorization based on available services. Multiple scopes should be space-separated. Valid scopes are: eidapi_auth, eidapi_profiles, eidapi_formFilling, eidapi_sign, eidapi_fr, eidapi_bulksign

Example: eidapi_auth eidapi_formFilling eidapi_signPattern: ^(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign)(\s+(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign))*$
activityClassstring · nullableOptional

Android activity class (required if source is android)

Example: com.filleasy.app.MainActivity
activityParamsstring · nullableOptional

Additional activity parameters (optional if source is android)

Responses
chevron-right
200

Anonymous form filling request successfully initialized. Redirect user to the URL, then poll with the token to retrieve form data.

application/json
tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
urlstring · uriRequired

URL to redirect user for anonymous form filling

post
/iamsmart/v2/request/formfilling-anonymous

hashtag
Anonymous Hash Signing

post

Request digital signature for a document hash without requiring prior authentication.

This endpoint combines authentication and signing in a single flow. Pass the scope, language, source, redirect URL, and document details to initialize the anonymous signing request.

Returns a token, URL, and HKIC check digits. The URL redirects users to iAM Smart where they can authenticate and approve the signing request in one step.

Hash Requirements:

  • Must be a SHA-256 hash of the document content

  • Must be exactly 64 hexadecimal characters

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
langstring · enumOptional

iAM Smart App display language (case sensitive). Will default to 'en-US' if not specified

Default: en-USPossible values:
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
redirectstringRequired

Redirect URI after user authorization.

Browser: https URL to your website.

Mobile: Universal link (your-app://) or app scheme.

Example: https://www.yourwebsite.com/callback
scopestringOptional

Setting the scope is required only in cases where operations are chained, e.g auth + formfilling, auth + signing. By default, the scope is set to the value required for the operation. Requested scope of authorization based on available services. Multiple scopes should be space-separated. Valid scopes are: eidapi_auth, eidapi_profiles, eidapi_formFilling, eidapi_sign, eidapi_fr, eidapi_bulksign

Example: eidapi_auth eidapi_formFilling eidapi_signPattern: ^(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign)(\s+(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign))*$
namestring · max: 200Required

Document title

fileHashstringRequired

SHA-256 hash of document (64 hex characters)

Pattern: ^[a-f0-9]{64}$
hkicHashstringOptional

Hash of HKIC for verification

Pattern: ^[a-f0-9]{64}$
servicestring · max: 200Required

Service description

organisationstring · max: 200Optional

Organisation name

Responses
chevron-right
200

Anonymous signing request successfully initialized. Redirect user to the URL, then poll with the token to retrieve signature.

application/json
tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
urlstring · uriRequired

URL to redirect user for anonymous signing

hkicinteger · min: 1000 · max: 9999Required

HKIC check digits

post
/iamsmart/v2/request/signing-anonymous

hashtag
Anonymous PDF Signing

post

Request digital signature for a PDF document without requiring prior authentication. This endpoint enables anonymous PDF signing where users can sign documents using their iAM Smart identity without a separate authentication step.

The response includes a URL to the iAM Smart QR code page and a temporary token. Users scan the QR code with their iAM Smart mobile app (for desktop) or are redirected to the iAM Smart app (for mobile). After signing, users are redirected to the specified redirect URL.

Use the temporary token with the polling endpoint to retrieve the signed document once the user completes the signing process.

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
langstring · enumOptional

iAM Smart App display language (case sensitive). Will default to 'en-US' if not specified

Default: en-USPossible values:
sourcestring · enumRequired

The device platform and browser combination

Example: PC_BrowserPossible values:
redirectstringRequired

Redirect URI after user authorization.

Browser: https URL to your website.

Mobile: Universal link (your-app://) or app scheme.

Example: https://www.yourwebsite.com/callback
scopestringOptional

Setting the scope is required only in cases where operations are chained, e.g auth + formfilling, auth + signing. By default, the scope is set to the value required for the operation. Requested scope of authorization based on available services. Multiple scopes should be space-separated. Valid scopes are: eidapi_auth, eidapi_profiles, eidapi_formFilling, eidapi_sign, eidapi_fr, eidapi_bulksign

Example: eidapi_auth eidapi_formFilling eidapi_signPattern: ^(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign)(\s+(eidapi_auth|eidapi_profiles|eidapi_formFilling|eidapi_sign|eidapi_fr|eidapi_bulksign))*$
namestring · max: 200Required

PDF document title

fileHashstring · byteRequired

Base64-encoded hash of PDF

hkicHashstringOptional

Hash of HKIC for verification

Pattern: ^[a-f0-9]{64}$
servicestring · max: 200Required

Service description

Responses
chevron-right
200

Successfully initiated anonymous PDF signing request

application/json
tokenstringRequired

JWT token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8UPattern: ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*$
urlstring · uriRequired
hkicinteger · min: 1000 · max: 9999Required
post
/iamsmart/v2/request/pdf-signing-anonymous

hashtag
Redirect

get

iAM Smart redirects the user to this endpoint after completing the authentication or service request flow. It processes the authorization code or error from iAM Smart and again redirects to the client's specified redirect URL.

Path parameters
servicestring · enumRequired

The iAM Smart service type

Example: authPossible values:
Query parameters
codestringOptional

Authorization code from iAM Smart (present on success)

Example: a51c81dce74743359c0a1d639369311f
error_codestringOptional

Error code from iAM Smart (present on failure/rejection)

statestringOptional

State parameter used to match the request.

Example: 9boB90uhibYcO3FdPp8fWFLmOOCmTVGUH4Ld
businessIDstringOptional

Business ID to identify the transaction. Not received if service is auth

Example: HjlSqLBzQARhhHV8O44wQuR0upfiHTjj6ckh
sourcestringOptional

Source platform (optional)

Responses
get
/iamsmart/v2/redirect/user/{service}
No content

hashtag
Poll Data

post

Used for all iAM Smart services to poll for final results after user action.

Short poll this endpoint, passing in the token (from any iAM Smart endpoint) to obtain the results.

The response's token is a JWT or JWE depending if there's sensitive personal data. You should handle them like so:

  • JWT verify* token

  • JWE decrypt using the private keys that Fill Easy has previously provided.

Please note that the data result is returned only once and is deleted immediately.

*you can try using online decoder like https://jwt.io/arrow-up-right

Authorizations
x-client-idstringRequired

Client ID in x-client-id header.

x-client-secretstringRequired

Client Secret in x-client-secret header.

Body
tokenstringRequired
codestringOptional
error_codestringOptional
Responses
chevron-right
200

Returns the final result with personal information, encoded in a JWE token.

application/json
messagestringOptional
tokenstringOptional
post
/iamsmart/v2/callback/client

Last updated