Hallmark (HUID) Verification API
Send the HUID stamped on a piece of jewellery and get back its purity, product, weight, hallmarking date, centre and jeweller.
The documentation opens in the VerifyAll dashboard after sign-in, for accounts with approved API access. New to the API? Start with the developer guide.
Overview
What the Hallmark (HUID) Verification API does
The Hallmark (HUID) Verification API takes the hallmark unique ID stamped on a gold or silver article and answers with the hallmark details on record for it: the purity grade as marked (for example 22K916), the material, the product type, the weight in grams, the date the article was hallmarked, the assaying and hallmarking centre that marked it, the jeweller it was hallmarked for, the job number and the article’s current status.
A HUID that answers with a different product, a different weight or a different jeweller from the piece in front of you is a strong sign that the stamp has been copied or that the article is not what it is said to be. Because the answer is structured JSON, your system can compare the returned weight and purity with what was weighed and tested at the counter, without anyone reading a certificate by hand.
Gold-loan lenders, pawnbrokers, jewellers buying back old gold, resale marketplaces and insurers use it at the moment an article is accepted, pledged, listed or insured. The answer comes back in the same call and is stored with a checkResultId, with a PDF report you can attach to the loan file or the purchase record.
How it works
- 1
Your server sends POST /universal/huid-verification with the huid in capital letters and digits, and an optional client_ref.
- 2
The request is checked first: a HUID in the wrong format is refused with a 400 and the list of problems, before anything runs or is charged.
- 3
The HUID is checked against live records and the answer comes back in the same call, usually within seconds, in VerifyAll’s standard JSON envelope.
- 4
The result is stored in your VerifyAll account with a checkResultId, so you can read it again with GET /check-results/{id}, find it by your client_ref and download the hallmark PDF report.
Request and response
Hallmark verification API endpoints and fields
The main fields; the full reference with every field, error code and a cURL sample is in the dashboard docs.
| Endpoint | What it does |
|---|---|
| POST/universal/huid-verification | Verify a jewellery article’s hallmark by its HUID |
Request fields
| Field | What it is |
|---|---|
| huidRequired | The HUID printed on the article: capital letters and digits, 6 characters on current hallmarks (the field takes 6 to 20). |
| client_refOptional | Your own reference, stored with the result (up to 100 characters). The X-Client-Ref header does the same. |
What the answer returns
| Field | What it is |
|---|---|
| huid / status | The HUID checked and the article’s status as recorded, for example Available at Jeweller. |
| purity | Purity grade as marked, for example 22K916. |
| material / product | Gold, silver and so on, and the article type as recorded. |
| weight_grams | Weight of the article in grams. |
| hallmarked_on | The date the article was hallmarked, YYYY-MM-DD. |
| hallmarking_centre | The assaying and hallmarking centre that marked the article: name, registration number and address. |
| jeweller | The jeweller (outlet) the article was hallmarked for: name and registration number. |
| job_number | The hallmarking job number. |
Base URL https://api.verifyall.ai. Authenticate with the X-API-Key header (a va_sandbox_ or va_live_ key). Every answer carries data, status_code, success, message and message_code; checks add outcome, checkResultId, charged and charged_amount.
Key features
Hallmark (HUID) Verification API features and capabilities
Weight and purity to compare
weight_grams is a number and purity the grade as marked, so your system can compare them with the counter’s own weighing and testing.
Centre and jeweller named
See which hallmarking centre marked the article and which jeweller it was marked for, with their registration numbers.
Stored with a PDF report
Each result is kept with a checkResultId and can be downloaded as a PDF report for the loan file, the purchase record or an audit.
Format checked before any charge
A malformed HUID is refused with a list of problems before the check runs, so a typing error at the counter costs nothing.
Use cases
Where businesses use the Hallmark (HUID) Verification API
Gold loans and pawn
Confirm the purity and weight of each pledged article before you fix the loan amount.
Old-gold buy-back and exchange
Check that the HUID on an article brought in for exchange matches its product type, weight and purity.
Jewellery resale marketplaces
Verify each listed piece’s hallmark before it goes live, and show buyers the purity, weight and hallmarking date.
Jewellery insurance
Record the hallmark details of insured articles at proposal and at claim.
Industries
- Jewellery & Gold Loans
- BFSI & Fintech
- Insurance
- Real Estate & Marketplaces
- E-commerce, Logistics & Gig
Coverage
Gold and silver articles hallmarked in India that carry a HUID. Older hallmarks without a HUID cannot be checked by this API.
Limitations to plan for
- The answer describes the article as it was hallmarked. It does not test the metal in your hand; compare the returned weight and purity with your own testing.
- A HUID with no record answers record_not_found. The lookup ran, so it is charged like any completed check.
- Fields the record does not hold come back as null, never guessed.
Integration
How to integrate the Hallmark (HUID) Verification API
From a business account to your first live call.
Step 1
Create a business account on VerifyAll and get it approved, as for running checks in the dashboard.
Step 2
Request Developer API access under Developers in the dashboard: the APIs you need, your expected monthly volume and your use case. The VerifyAll team reviews it and shares the API Services Agreement.
Step 3
Once the agreement is signed and access is approved, create your Sandbox key and build against sample data. Sandbox calls are never charged.
Step 4
Create your Production key, recharge your wallet and switch the key in your code: the endpoint and fields stay the same.
Get started
Request access to the Hallmark (HUID) Verification API
Tell us what you want to verify. We reply within one business day with access steps, Sandbox details and your API pricing.
View API documentation
The full reference for Hallmark (HUID) Verification API (endpoints, fields, errors, cURL) opens in the dashboard once your access is approved.
Open the docs (sign-in)Create a business account
API keys are issued to an approved business account. Sign up, then request access under Developers.
Create account
Pricing
Production calls are charged per check from your prepaid VerifyAll wallet, at your account’s API price; GST is added separately when you recharge. Sandbox calls are never charged. Your API prices are shown in the dashboard once access is approved. How pricing works
Already have a business account? Sign in to request access
Hallmark (HUID) Verification API: frequently asked questions
Answers for teams planning an integration.
Still have questions? Our team is happy to help.
Contact SupportRelated APIs
PAN Verification API
LiveInstant answerConfirm a PAN exists, see who holds it and match the name and date of birth your customer typed, in one call.
View API detailsGST Verification API
LiveInstant answerSend a GSTIN and get the business behind it: names, status, place of business and the returns it has filed, in one call.
View API detailsAML Screening API
LiveInstant answerScreen a person or an entity against sanctions, enforcement and regulatory watch lists and adverse media in one call, with every hit scored.
View API details
All other verifications APIsRun Hallmark verification in the dashboard, without codeBrowse the API Marketplace
Start with the Hallmark (HUID) Verification API
Request access, build against the Sandbox, then go live with your Production key.