1. API Docs

    Vehicle queries

    Query vehicle details, ownership details, money owing and more.

    API Endpoint URL

    Production:
    https://www.carjam.co.nz/api/car/

    Test:
    https://test.carjam.co.nz/api/car/

    Test Plates

    Navigate to https://test.carjam.co.nz/?testplates=1 and scroll down the page to get test registration number plates.

    Request GET Parameters

    • plate — plate or VIN
    • key — API key
    • basic —  "1" to return basic vehicle information. Default: 1. To disable set it to "0".
    • owners — "1" to return ownership history information. Default: 0.
    • owner — "1" to return current owner details. Default: 0.
    • s241_purpose — "PURPOSE" to specify the intended purpose of personal ownership enquiry as required by NZTA. This parameter is required when owner=1 or owners=1 is specified AND the account and user are s241 authorized (for personal ownership details). The applicable purpose values for your account can be found in the member dashboard under the s241 section.
    • ppsr — "1" to return PPSR, money owing information. Default: 0.
    • ppsrh — it is a complementary parameter to "ppsr". When set to "1" the past plates will be searched to find money owing hidden on the past plates. Additional charges will apply.
    • rucs — "1" to return RUC history. Default: 0.
    • ruc_outstanding — "1" to check if there is any outstanding RUC. Default: 0. Note, this requires basic=1, rucs=1 and will only work if the vehicle is subject to RUC.
    • motfuel — "1" to return Motfuel/FuelSaver information. Default: 0.
    • translate — "1" to provide human translations for the raw encoded values. Separate tags prefixed with 'h' are created. Default: 0.
    • cache — enables lookup of basic information in CarJam cache before going to NZTA. More details below.
    • f — "XML" or "json". default is xml.
    • warnings — "1" to return compulsory recalls, write-off and other warnings.
    • fws — "1" to return fire/water/write-off warnings.

    Cache Parameter

    cache can be:

    Note, the default cache setting can be changed in Development Connection. If cache parameter is used, it overrides the default setting. Also note, cache parameter is not applicable to personalised plates.

    Error Responses

    If there is an error an xml returned will have a top-level tag 'error'. Here is an example:

    <error>
    <code>-1</code>
    <message>Requires an API key</message>
    <class>wterror</class>
</error>

    A request that arrives while you are over the rate limit is answered with the error err-too-many-requests; see throttling for the limit and how to handle it.

    Success Responses

    For successful results, a top-level tag of 'message' is returned. The message will contain the following sub-tags:

    • idh — includes free and basic facts details
    • ioh — includes ownership information when requested
    • ppsr — includes PPSR search summary and how many financing statements are registered
    • ppsr_details — includes the details of each financing statement (up to 50)
    • money_owing — includes PPSR collateral matches and overall money owing match decision
    • motfuel — includes FuelSaver details
    • and sometimes more...

    Basic vehicle information request example

    Some values are coded. Follow the links to the translation tables. You can also add &translate=1 which will return an extra message's sub-tag 'hidh' containing the same information but in a more human-readable form.

    • Basic vehicle data: <endpoint>?key=<api-key>&plate=cbc193&basic=1 xml response
    • Basic vehicle, ownership and no PPSR: <endpoint>?key=<api-key>&plate=z0rr0&basic=1&owners=1 xml response
    • Basic vehicle, ownership and PPSR with translation: <endpoint>?key=<api-key>&plate=w2315&basic=1&owners=1&ppsr=1&ppsrh=1&translate=1 xml response

    Note:

    • All times and dates are represented as UNIX timestamp.
    • Many values are coded. See Tags and Codes in HTML or XML for definitions.
    • When translate=1 is used, human-readable versions are returned in additional tags prefixed with 'h' (e.g. hidh, hioh, hico, hirh).

    Field Reference

    Note, this is not a complete list of all fields that may be returned. Do verify the actual response for the plate you are querying to see all returned fields.

    Basic Vehicle Fields (idh) — basic=1

    The idh tag contains header, vehicle, and odometer_history sub-tags.

    Header

    Field Description Coded
    not_found Whether the vehicle was found —

    Vehicle Identification

    Field Description
    plate Registration plate number
    vin Vehicle Identification Number
    chassis Chassis number

    Vehicle Details

    Field Description Coded
    make Vehicle manufacturer —
    model Vehicle model —
    year_of_manufacture Year of manufacture —
    body_style Body style code Yes (BODY)
    vehicle_type Vehicle type code Yes (VTYP)
    cc_rating Engine capacity (cc) —
    country_of_origin Country of manufacture Yes (CTRY)
    previous_country_of_registration Previous country of registration Yes (CTRY)
    assembly_type Assembly type Yes (ASSM)
    fuel_type Primary fuel type Yes (FUEL)
    alternative_fuel_type Alternative fuel type Yes (FUEL)
    tare_weight Tare weight (kg) —
    wheelbase Wheelbase (mm) —
    gross_vehicle_mass Gross vehicle mass (kg, requires motfuel=1) —
    transmission Transmission description —
    transmission_type Transmission type code —
    class Fleet class —
    industry_class Industry classification —
    industry_model_code Industry model code —
    mvma_model_code MVMA model code —
    road_transport_code Road transport code —
    tla Territorial Local Authority code —
    postcode Postcode of registered address —
    axle_type Axle type Yes (AXLE)
    front_axle_group_rating Front axle group rating —

    Registration

    Field Description Coded
    registration_plate Current registration plate —
    registration_status Registration status Yes (REGS)
    plate_type Plate type Yes (PLTY)
    licence_type Licence type Yes (LICT)
    licence_expiry_date Licence expiry date (timestamp) —
    continuous_licence Whether on continuous licensing Yes (Y/N)
    cause_of_latest_registration Cause of latest registration Yes (COLR)
    date_of_last_registration Date of last registration (timestamp) —
    date_of_first_registration_in_nz Date of first NZ registration (timestamp) —
    date_of_issue_for_latest_licence Date latest licence was issued (timestamp) —
    vehicle_usage How the vehicle is used Yes (USGE)
    cancellation_reason_code Reason for registration cancellation Yes (CRES)
    cancellation_date_of_registration Cancellation date (timestamp) —
    registered_overseas Whether registered overseas Yes (Y/N)
    year_of_first_registration_overseas Year of first overseas registration —
    month_of_first_registration_overseas Month of first overseas registration —
    day_of_first_registration_overseas Day of first overseas registration —
    ban_reason Reason for any ban Yes (BANR)

    WOF (Warrant of Fitness)

    Field Description Coded
    subject_to_wof Whether subject to WOF Yes (Y/N)
    subject_to_wof_inspection Whether subject to WOF inspection Yes (Y/N)
    result_of_latest_wof_inspection Result of latest WOF Yes (F=Fail, P=Pass)
    date_of_latest_wof_inspection Date of latest WOF inspection (timestamp) —
    expiry_date_of_last_successful_wof WOF expiry date (timestamp) —

    COF (Certificate of Fitness)

    Field Description Coded
    subject_to_cof Whether subject to COF Yes (Y/N)
    subject_to_cof_inspection Whether subject to COF inspection Yes (Y/N)
    result_of_latest_cof_inspection Result of latest COF Yes (F=Fail, P=Pass)
    date_of_latest_cof_inspection Date of latest COF inspection (timestamp) —
    expiry_date_of_last_successful_cof COF expiry date (timestamp) —
    was_subject_to_cof Whether vehicle was previously subject to COF Yes (Y/N)

    Odometer

    Field Description Coded
    reliable_odometer Whether odometer is considered reliable Yes (Y/N)
    inconsistent_odometer Whether odometer readings are inconsistent Yes
    latest_odometer_reading_source_code Source of latest reading Yes (ODSC)
    latest_odometer_reading_unit Unit of latest reading Yes (ODOU)
    current_vehicle_odometer_unit Current odometer unit Yes (ODOU)
    date_of_odometer_reading Date of latest reading (timestamp) —

    Odometer History (array)

    Each entry in odometer_history contains:

    Field Description Coded
    odometer_reading Reading value —
    odometer_date Date of reading (timestamp) —
    odometer_source Source of reading Yes (ODSC)
    odometer_unit Unit of reading Yes (ODOU)

    RUC (Road User Charges)

    Field Description Coded
    subject_to_ruc Whether subject to RUC Yes (Y/N)
    ruc_licence_type RUC licence type Yes (RLIC)
    ruc_vehicle_type RUC vehicle type Yes (RUCT)
    ruc_licence_issue_date RUC licence issue date (timestamp) —
    ruc_outstanding Outstanding RUC amount (requires ruc_outstanding=1) —
    ruc_licence_start RUC licence start (distance or date) —
    ruc_licence_end RUC licence end (distance or date) —

    Stolen

    Field Description Coded
    reported_stolen Stolen status Yes (Y=Yes, N=No, U=Unknown)

    Other

    Field Description Coded
    imported_damaged Whether imported as damaged Yes (Y/N)

    Ownership History Fields (ioh) — owners=1

    The ioh tag contains an owners array. When basic=0, it also includes a vehicle sub-tag with basic vehicle details. Each owner entry contains:

    Field Description Coded
    gone_no_address Whether owner has no known address Yes (Y/N)
    fleet_lease_ownership Fleet/lease ownership type Yes (FLO)
    ownership_status Ownership status Yes (OWNS)
    sex_company Sex or company indicator Yes (SEXT)
    ownership_date Date of ownership (timestamp) —
    prior_odometer_date Prior odometer date (timestamp) —
    date_of_birth_of_owner Owner's date of birth (timestamp). Always empty — NZTA does not return date of birth at CarJam's access level, with or without s241. —

    Note: owners=1 does not require s241 authorisation. Without it the query is made under standard access and the personal details of individual owners are withheld — owner_name comes back as Information not available and the address fields are empty. s241 authorisation, plus a valid s241_purpose parameter, is only needed to see the name and address of individual owners.

    Current Owner Fields (ico) — owner=1

    The ico tag returns the current owner's details. When basic=0, it also includes a vehicle sub-tag with basic vehicle details. Fields are the same as the ownership history entries above, for the current registered person only.

    owner=1 does not require s241 authorisation. Without it the query is made under standard access and returns the non-personal fields (ownership date, ownership status, prior odometer, sex_company, gone_no_address, and company owner names). s241 authorisation is only needed to see the personal details of an individual current owner — their name and address. Where those are withheld, owner_name comes back as Information not available and the address fields are empty.

    RUC History Fields (irh) — rucs=1

    The irh tag contains vehicle and ruc_licence sub-tags with the full RUC licence history for the vehicle. Only returned when the vehicle is subject to RUC (or when basic=0).

    PPSR / Money Owing Fields — ppsr=1

    Tag Description
    ppsr PPSR search summary with financing statement count. When ppsrh=1, returns an array (one per plate searched).
    ppsr_details Details of each registered financing statement (up to 50). When ppsrh=1, returns an array.
    money_owing Overall money owing assessment

    Money Owing

    Field Description
    match Overall match code (Y=Yes, PY=Probable Yes, M=Maybe, PM=Probable Maybe, U=Unknown, N=No)
    match_description Human-readable match description
    search_id Array of PPSR search IDs used

    Optional Add-on Fields

    Motfuel — motfuel=1

    Returns motfuel tag with FuelSaver/Motfuel data including transmission, weight, and fuel economy information.

    Valuation — valuation=1

    Returns valuation tag with market valuation data:

    Field Description
    variants Valuation variants with pricing data
    variants.variant Array of individual variant valuations

    Warnings — warnings=1

    Returns warnings tag with compulsory recalls, write-off notices, and other warnings:

    Field Description
    warning_severity Severity level of the warning
    warning_message Warning message text
    warning_action Recommended action
    warning_details Additional warning details

    Flood/Write-off — fws=1

    Returns flood tag with fire, water, and write-off data:

    Field Description
    vin VIN from flood/write-off record
    make Make from record
    model Model from record
    damage Damage description
    notification_date Date of notification
    date Date of event

    Charges — charges=1

    Returns charges tag:

    Field Description
    cents Amount charged for this request in cents
    — 👩‍💻 API