HUID Verification

Endpoint Overview

POST /api/v1/huid/verify

Description

The HUID Verification API allows you to validate and retrieve detailed information about jewelry items based on their Hallmark Unique Identification (HUID) number. This endpoint verifies the authenticity of gold and other precious metal items by checking their official hallmarking details against government records.

Key Benefits

Instant verification of jewelry authenticity through official HUID records

Access to comprehensive hallmarking details including purity, weight, and material

Verification of hallmarking center credentials and registration information

Real-time status tracking of hallmarked items

Use Cases

Jewelry Retail

Financial Services

Regulatory Compliance

Verify authenticity of jewelry items before purchase

Confirm hallmarking details during inventory management

Provide customers with verification certificates for purchased items

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT format)
Content-Type	Yes	Application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	Enter Hallmark Unique Identification (HUID) Number

Example Request

{
    "id_number": "2979"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the HUID verification data
data.client_id	String	Unique Client ID
data.id_number	String	Identification number
data.huid_number	String	Unique identifier for the item
data.address	String	Address of the item
data.product	String	Name of the product
data.hallmarking_center_name	String	Name of the hallmarking center
data.hallmarking_center_registration_number	String	Registration number of the hallmarking center
data.purity	String	Purity level of the item
data.job_no	String	Job number
data.outlet_name	String	Name of the outlet
data.weight	String	Weight of the item
data.registration_number	String	Registration number
data.material	String	Material of the item
data.hallmark_date	String	Date when the item was hallmarked in "YYYY-MM-DD" format
data.status	String	Current status of the item
status_code	Integer	HTTP status code
success	Boolean	Indicates if the request was successful
message	String	Response message
message_code	String	Code indicating the type of message

Example Successful Response

{
    "data": {
        "client_id": "huid_BedayPWyAvlxyChVilut",
        "id_number": "297VR9",
        "huid_number": "297VR9",
        "address": "FIST FLOOR,, R.S. NO-185 P, T.P.S. NO-8, PLOT NO- -26/BRAHMANIYA PARA, TRASIYO ROAD,, KRISHNA VASAN",
        "product": "LEDIS RING",
        "hallmarking_center_name": "MEDDOX ASSAYING & HALLMARKING CENTRE",
        "hallmarking_center_registration_number": "WRO/RAHC/R-3623462",
        "purity": "22K916",
        "job_no": "106830909",
        "outlet_name": "DASHRATH GOLD ART PRIVATE LIMITED",
        "weight": "3.345",
        "registration_number": "7690218927",
        "material": "Gold",
        "hallmark_date": "2023-03-07",
        "status": "Available at Jeweller"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid HUID

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid HUID number provided",
    "message_code": "invalid_input"
}

This error occurs when the provided HUID number is not in the correct format or does not exist in the system.

Integration Best Practices

Security Recommendations

Store API keys securely and never expose them in client-side code

Implement proper error handling to prevent information leakage

Use HTTPS for all API communications

Rotate JWT tokens periodically and implement token expiration

User Experience Guidelines

Provide clear feedback to users when verification is in progress

Display comprehensive hallmarking details in an organized, easy-to-understand format

Include visual indicators for verification status (verified, pending, failed)

Allow users to save or print verification results for their records

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API: Verify Permanent Account Number details

GST Verification API: Verify Goods and Services Tax registration details

Business Verification API: Verify business registration and details

Compliance and Legal Considerations

The HUID verification process is governed by the Bureau of Indian Standards (BIS) regulations. Ensure that you have proper authorization to access and store hallmarking information. The data retrieved should be handled in accordance with data protection regulations and should not be used for purposes other than verification.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/huid/verify' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "2979" }'

{ "data": { "client_id": "huid_BedayPWyAvlxyChVilut", "id_number": "297VR9", "huid_number": "297VR9", "address": "FIST FLOOR,, R.S. NO-185 P, T.P.S. NO-8, PLOT NO- -26/BRAHMANIYA PARA, TRASIYO ROAD,, KRISHNA VASAN", "product": "LEDIS RING", "hallmarking_center_name": "MEDDOX ASSAYING & HALLMARKING CENTRE", "hallmarking_center_registration_number": "WRO/RAHC/R-3623462", "purity": "22K916", "job_no": "106830909", "outlet_name": "DASHRATH GOLD ART PRIVATE LIMITED", "weight": "3.345", "registration_number": "7690218927", "material": "Gold", "hallmark_date": "2023-03-07", "status": "Available at Jeweller" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

HUID

HUID Verification#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses