IAM Smart

Hong Kong's eID

For further details, please refer to the official iAM Smart developer guide.

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.

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

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.

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

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

application/json
post
/iamsmart/v2/request/auth
POST /iamsmart/v2/request/auth HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "lang": "en-US",
  "redirect": "https://based.fill-easy.com/callback",
  "source": "PC_Browser"
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "url": "https://apigw-isit.staging-eid.gov.hk/api/v1/auth/getQR?clientID=7688ff3048ff49b2b64578cf40867d1d&responseType=code&source=PC_Browser&redirectURI=https%3A%2F%2Fbased.fill-easy.com%2Fdev-eric%2Fiamsmart%2Fv2%2Fredirect%2Fuser%2Fauth&scope=eidapi_auth%20eidapi_formFilling%20eidapi_sign%20eidapi_fr&lang=en-US&state=gandRsHwuJEeWu7fUXsjHvzbXxDw3dEgnwMm&brokerPage=true"
}

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

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

application/json
post
/iamsmart/v2/request/formfilling
POST /iamsmart/v2/request/formfilling HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 384

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "source": "PC_Browser",
  "profileFields": [
    "idNo",
    "enName",
    "chName",
    "gender"
  ],
  "formData": {
    "formName": "Fill Easy Contact Form",
    "formNum": "FE_001",
    "formDesc": "Contact Fill Easy",
    "formFields": [
      "prefix",
      "maritalStatus",
      "mobileNumber",
      "emailAddress",
      "residentialAddress"
    ]
  }
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
}

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

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

application/json
post
/iamsmart/v2/request/signing
POST /iamsmart/v2/request/signing HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 296

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "source": "PC_Browser",
  "name": "Fill Easy Contact Form",
  "hash": "af8b6f626242f214be360fa7d412e42dacb2f48bc11bb089019a912930019300",
  "service": "Digital Signing of Application Form"
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "hkic": 1524
}

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

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

application/json
post
/iamsmart/v2/request/pdf-signing
POST /iamsmart/v2/request/pdf-signing HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 287

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "source": "PC_Browser",
  "name": "Landsurvey Purchase Form",
  "fileHash": "R3fJTKFPwkRw019fLk+L19y91DVgI9hy/G7u6+YiECk=",
  "service": "Digital PDF Signing Powered by Fill Easy"
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "hkic": 4303
}

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

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

application/json
post
/iamsmart/v2/request/reauth
POST /iamsmart/v2/request/reauth HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "source": "PC_Browser"
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
}

CCIC

post
Authorizations
x-client-idstringRequired

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

Responses
200

Success

No content
post
/iamsmart/v2/request/ccic
POST /iamsmart/v2/request/ccic HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Accept: */*
200

Success

No content

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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 | nullOptional

Android activity class (Android only)

Example: com.filleasy.app.MainActivity
activityParamsstring | nullOptional

Additional activity parameters (Android only)

Responses
200

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

application/json
post
/iamsmart/v2/request/formfilling-anonymous
POST /iamsmart/v2/request/formfilling-anonymous HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 377

{
  "lang": "en-US",
  "source": "PC_Browser",
  "redirect": "https://www.yourwebsite.com/callback",
  "profileFields": [
    "idNo",
    "enName",
    "chName",
    "birthDate",
    "gender"
  ],
  "formData": {
    "formName": "Standard Chartered Credit Card Application Form",
    "formNum": "SC_001",
    "formDesc": "Application for Credit Card",
    "formFields": [
      "prefix",
      "maritalStatus",
      "mobileNumber",
      "emailAddress",
      "residentialAddress"
    ]
  }
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "url": "https://apigw-isit.staging-eid.gov.hk/api/v1/auth/getQR?clientID=7688ff3048ff49b2b64578cf40867d1d&responseType=code&source=PC_Browser&redirectURI=https%3A%2F%2Fbased.fill-easy.com%2Fdev-eric%2Fiamsmart%2Fv2%2Fredirect%2Fuser%2Fformfilling-anonymous&scope=eidapi_auth%20eidapi_formFilling%20eidapi_sign%20eidapi_fr&ticketID=c75989047e9f450aa77b1a289cb8ec9c&lang=en-US&state=APkv28rUmcpzOP8VawtPES2yGIfU0TVnIqwZ&brokerPage=true"
}

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

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

application/json
post
/iamsmart/v2/request/signing-anonymous
POST /iamsmart/v2/request/signing-anonymous HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 310

{
  "lang": "en-US",
  "source": "PC_Browser",
  "redirect": "https://www.yourwebsite.com/callback",
  "name": "Credit Card Application Form",
  "fileHash": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
  "hkicHash": "4753bd125a926815892a6551933d70d687e2bcef17b608863cd8bd4e0e709f23",
  "service": "Digital Signing of Application Form"
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "url": "https://apigw-isit.staging-eid.gov.hk/api/v1/auth/getQR?clientID=7688ff3048ff49b2b64578cf40867d1d&responseType=code&source=PC_Browser&redirectURI=https%3A%2F%2Fbased.fill-easy.com%2Fdev-eric%2Fiamsmart%2Fv2%2Fredirect%2Fuser%2Fsigning-anonymous&scope=eidapi_auth%20eidapi_formFilling%20eidapi_sign%20eidapi_fr&ticketID=cc100a3e33254841a09d90ab65cf944b&lang=en-US&state=YCGedqGuxcG5gWa6m4WTuGlnxDPd6HjQAwO9&brokerPage=true",
  "hkic": 4801
}

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

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

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
200

Successfully initiated anonymous PDF signing request

application/json
post
/iamsmart/v2/request/pdf-signing-anonymous
POST /iamsmart/v2/request/pdf-signing-anonymous HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 352

{
  "fileHash": "af8b6f626242f214be360fa7d412e42dacb2f48bc11bb089019a912930019301",
  "hkicHash": "ac3704c5e852cec884a7695a2da26aaed697dae6bdb1d6ae830698e4e3666309",
  "lang": "en-US",
  "name": "Credit Card Application Form",
  "redirect": "https://www.yourwebsite.com/callback",
  "service": "Digital Signing of Credit Card Application by YourCompany",
  "source": "PC_Browser"
}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
  "url": "https://apigw-isit.staging-eid.gov.hk/api/v1/auth/getQR?clientID=7688ff3048ff49b2b64578cf40867d1d&responseType=code&source=PC_Browser&redirectURI=https%3A%2F%2Fbased.fill-easy.com%2Fdev-eric%2Fiamsmart%2Fv2%2Fredirect%2Fuser%2Fpdf-signing-anonymous&scope=eidapi_auth%20eidapi_sign&ticketID=8e3fd6021c21407588d37af90520ab5e&lang=en-US&state=yKsCIXC0VpDxbyrLiHeRCrLSnOmen0mpWhFI&brokerPage=true",
  "hkic": 4184
}

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
200

Success

No content
get
/iamsmart/v2/redirect/user/{service}
GET /iamsmart/v2/redirect/user/{service} HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
Accept: */*

No content

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/

Authorizations
x-client-idstringRequired

API Key authentication using x-client-id and x-client-secret headers.

x-client-secretstringRequired

The client secret used for API key authentication.

Body
tokenstringRequired
codestringOptional
error_codestringOptional
Responses
200

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

application/json
post
/iamsmart/v2/callback/client
POST /iamsmart/v2/callback/client HTTP/1.1
Host: sandbox.staging-api.fill-easy.com
x-client-id: YOUR_API_KEY
x-client-secret: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 21

{
  "token": "{{token}}"
}
{
  "message": "Authentication success",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U"
}
NextSingpass

Last updated