Serial number decoder API
A finance file, an auction lot or an inspection form often carries a serial number and little else that can be trusted. The AssetGym serial number decoder API turns that serial into the manufacturer, the model or the candidate models, and the year where the serial encodes one, each matched to the AssetBase catalogue. It reads construction, material handling and agriculture equipment, and the VINs of trucks, vans and cars. You send the serial alone: no make, model or description.
A free-text description depends on whoever typed it and on every system it passed through. The serial was stamped by the manufacturer, in that manufacturer’s format, and that format is all the decoder needs.
Serial only
Send the serial on its own. The decoder works out the manufacturer from the serial’s format and reads the model and year from the positions that encode them. When the serial alone cannot settle it, the result lists the candidates instead of guessing.
Serial and manufacturer
When the make is known, send its AssetBase id as a manufacturer hint. The decoder then tries only that manufacturer’s formats, a manufacturer prefix in the serial still takes precedence, and the hint draws no credits. The id is the first entry of asset_chain in any result.
A call to the decode endpoint with two serials: a Komatsu product identification number (PIN) and a string no supported format accepts. Results come back in request order, and a serial that cannot be decoded never fails the rest of the call.
AssetGymcurl -X POST 'https://asset-gym.com/api/v1/catalog/serial-numbers/decode' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"serial_numbers": [
{
"serial_number": "KMTPC180JMKK00001"
},
{
"serial_number": "XXXXXXXXX"
}
]
}'{
"results": [
{
"serial_number": "KMTPC180JMKK00001",
"status": "decoded",
"year": 2021,
"asset": {
"asset_id": 36988,
"asset_display_name": "Komatsu PC 210LC-8",
"asset_chain": [
{
"id": 1777,
"name": "Komatsu"
},
{
"id": 6272,
"name": "PC"
},
{
"id": 36988,
"name": "210LC-8"
}
],
"taxonomy_id": 1063,
"taxonomy_display_name": "76-130 KW",
"taxonomy_chain": [
{
"id": 3,
"name": "Construction"
},
{
"id": 51,
"name": "Excavator"
},
{
"id": 474,
"name": "Crawler Excavator"
},
{
"id": 1063,
"name": "76-130 KW"
}
]
}
},
{
"serial_number": "XXXXXXXXX",
"status": "no_match"
}
]
}Example serials follow each manufacturer’s format and do not belong to specific machines. Every example on this page is decoded through the live API by our automated tests on each release. Ids are AssetBase catalogue ids.
There is no confidence score. Decoding is rule-based, so the same serial always returns the same result, and each result carries a status that says how far the serial could be trusted.
| Serial sent | Status | What comes back |
|---|---|---|
KMTPC180JMKK00001 | decoded | Komatsu PC 210LC-8, year 2021. The PIN carries Komatsu's type code (PC180), not the model name. |
CAT0320FHMKK00001 | decoded | Caterpillar 320F L. Caterpillar's PIN encodes no year, so the year is null. |
KMTPC257EMKK00001 | ambiguous_model | Komatsu PC, year 2021, with the PC 210 variants that share this type code (PC 210LC-11, PC 210NLC-11E0 and others) as candidates. |
120000002 | ambiguous_manufacturer | Two manufacturers' formats accept it: Liebherr LH 30 M or Takeuchi TB 20 e. Both decodes come back and neither is picked for you. |
120000002with the Takeuchi hint | decoded | Takeuchi TB 20 e. The manufacturer hint settles the tie. |
DBDLX100PKSS01362 | model_not_in_catalog | Case IH Luxxum 100, year 2019. The model is decoded but not yet in the AssetBase catalogue, so the catalogue reference is the manufacturer and the model name comes back in decoded_name_path. |
KMTPC181C55K51386 | unknown_model | Komatsu. The format matched, but this type code is not in the decoding rules yet. |
KMTPC209TPUF77490 | checksum_failed | Komatsu only. The check character does not match, so nothing else in the serial is trusted. |
CAT0320EBNAZ00731 | unrecognized_format | Caterpillar only, proven by the CAT prefix. No Caterpillar format accepts the rest of the serial. |
XXXXXXXXX | no_match | Nothing. No supported format accepts the serial. |
Two statuses are not in the table because they need a manufacturer hint or a catalogue gap to occur. unsupported_manufacturer means the hint names a make the decoder has no formats for, so the serial was never tried and may still be valid. error means the hint is not a manufacturer id, or the serial belongs to a manufacturer the catalogue does not have yet. The other serials in the request decode normally either way.
The decoder reads serial numbers of construction, material handling and agriculture equipment, and trucks, vans and cars. Manufacturers covered today:
Iveco, Renault and Scania are road-vehicle makes read from the VIN: Iveco vans and trucks, Renault cars and vans, and Scania trucks, whose models the catalogue does not hold yet, so they answer model_not_in_catalog. Volvo covers its construction equipment as well as its trucks and cars.
Coverage grows as decoding rules are added. If your fleet includes other makes, send us sample serials and we will tell you what decodes today.
Step 1
We set up an AssetGym workspace for your team. Pick a time.
Step 2
Signed-in users generate keys themselves in settings. Give the key the Identification scope, which covers serial decoding. Every request authenticates with Authorization: Bearer <key>.
Step 3
POST /api/v1/catalog/serial-numbers/decode with up to 10 serials. The API reference and the OpenAPI spec describe every field.
Each serial draws 4 credits, whatever its outcome. The manufacturer hint is free. See pricing.
Yes. Send the serial number alone. The decoder recognises the manufacturer from the serial's format and returns the model or the candidate models, plus the year where the format encodes one. No make, model or description is needed.
The decoder covers construction, material handling and agriculture equipment, and trucks, vans and cars from Bobcat, Case, Case IH, Caterpillar, Hyundai, Iveco, JCB, Komatsu, Kubota, Liebherr, New Holland, Renault, Scania, Takeuchi, Volvo and Yanmar. Coverage grows as decoding rules are added; contact us to check the makes in your fleet.
The result says so instead of guessing. If the serial names one manufacturer but several models, you get the candidate models and the family they share. If several manufacturers' formats accept it, you get one complete decode per manufacturer, and a manufacturer hint on the next call settles the tie.
Add manufacturer_id, the manufacturer's AssetBase asset id, next to the serial. The decoder then tries only that manufacturer's formats, a manufacturer prefix in the serial still takes precedence, and the hint is not billed. The id is the first entry of asset_chain in any result, and the catalogue suggest endpoint returns it for a manufacturer name without drawing credits.
No. Decoding is rule-based and deterministic, so the same serial always returns the same result. Each result carries a status instead, from decoded (one catalogue model) to no_match (no supported format accepts the serial).
The API returns the year the serial encodes and does not say whether it is a model year or a build year. It is null where the format encodes no year, as Caterpillar's PIN does not, and it is left out when the check character fails, since nothing in such a serial counts as evidence.
Exactly as stamped on the identification plate, 1 to 64 characters. Decoding is case-sensitive and dashes are part of some formats, so keep both, and leave out label text such as "SERIAL NO".
Up to 10. Each serial gets its own result, in request order, and a serial that cannot be decoded never fails the others.
The whole call answers 503 with the error code serial_decoding_unavailable and none of its serials is decoded; retry shortly. A fault on one serial, such as a hint that is not a manufacturer id, is different: that serial gets an error result and the others decode normally.
4 credits per serial, whatever the outcome. The manufacturer hint is not billed. Plans and credit prices are on the pricing page.
Send us a sample and we show you what decodes today, what comes back ambiguous, and why. Or book a demo to get API access.