Decode State ID Card PDF417 Barcodes with Java

Read the barcode on the back of US state and Canadian provincial ID cards from Java, branch on document_kind, and reject unreadable barcodes without AI guessing.

ID Cards Use the Same Barcode, but Not the Same Fields

People who do not drive carry a state or provincial identification card instead of a driver license. The back of most of these cards carries the same AAMVA PDF417 barcode as a license, so a check-in, age-verification, or onboarding flow will receive both. The difference is inside the record: an ID card has no license class, restrictions, or endorsements, and treating it as a license with missing fields leads to confusing validation errors.

One Java Request for Licenses and ID Cards

Send the card back to the PDF417 API. StructOCR decodes the barcode, parses the record defined by the AAMVA DL/ID standard, and returns document_kind as id_card or driver_license. Test a sample first in the free PDF417 scanner.

Where ID Card Barcodes Show Up

  • Age and identity checks: Accept non-drivers at alcohol, cannabis, and venue check-in without a separate ID card flow.
  • Account onboarding: Pre-fill name, date of birth, and address from either card type and label the document correctly in your records.
  • License-only workflows: Use document_kind to stop rental or fleet sign-ups that require a driver license when an ID card is presented.
Need more testing? Create a free account to get 200 free credits (equals 100 Passport scans).

Implementation: Java REST Request

Base64 encode the card-back image, send it with the x-api-key header, branch on document_kind, and treat HTTP 422 as a request for a clearer image.

Prerequisite: Java 17+ and Jackson Databind

JAVA EXAMPLE
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.util.Base64;
import java.util.Map;

ObjectMapper mapper = new ObjectMapper();
String image = Base64.getEncoder().encodeToString(
    Files.readAllBytes(Path.of("id-card-back.jpg"))
);
String body = mapper.writeValueAsString(Map.of("img", image));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.structocr.com/v1/driver-license-pdf417"))
    .timeout(Duration.ofSeconds(30))
    .header("Content-Type", "application/json")
    .header("x-api-key", System.getenv("STRUCTOCR_API_KEY"))
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
JsonNode result = mapper.readTree(response.body());

if (response.statusCode() == 422) {
    System.out.println("Retake image: " + result.path("error").asText());
} else if (response.statusCode() != 200) {
    throw new RuntimeException(response.body());
} else {
    JsonNode data = result.path("data");
    boolean idCard = "id_card".equals(data.path("document_kind").asText());
    System.out.println((idCard ? "State/provincial ID: " : "Driver license: ")
        + data.path("document_number").asText());
    System.out.println("Region: " + data.path("region").asText());
    System.out.println("DOB: " + data.path("date_of_birth").asText());
}

Technical Specs

  • •Endpoint: POST https://api.structocr.com/v1/driver-license-pdf417 (same endpoint for driver licenses and ID cards)
  • •Authentication: x-api-key request header
  • •Inputs: JPG, PNG, or WebP; Base64 JSON or multipart upload
  • •Maximum file size: 4.5MB
  • •Price: 2 credits for a successful decode; processing failures are refunded
  • •Document kind: `document_kind` is `id_card` for identification-card records and `driver_license` for licenses
  • •Output: Structured AAMVA JSON; raw barcode payload is not returned

Key Features

  • •One integration for both cards: Licenses and non-driver ID cards share the AAMVA PDF417 layout, so the same request handles both.
  • •Explicit document kind: Branch on `document_kind` instead of guessing from missing license class fields.
  • •No AI guessing: Identity fields come from a decoded PDF417 payload and AAMVA parser, never from a generative model.
  • •Retake-safe errors: PDF417_NOT_DECODED returns HTTP 422 with an optional `capture_issue` hint such as `out_of_focus` or `image_too_small`.

Sample ID Card JSON Output

The example uses fictional values. License-only elements such as vehicle_class are null for ID cards; type stays drivers_license for compatibility.

{
  "success": true,
  "data": {
    "type": "drivers_license",
    "document_kind": "id_card",
    "source": "pdf417",
    "country_code": "USA",
    "region": "NY",
    "document_number": "SAMPLEID123",
    "surname": "SAMPLE",
    "given_names": "ALEX MORGAN",
    "first_name": "ALEX",
    "middle_name": "MORGAN",
    "name_suffix": null,
    "sex": "F",
    "date_of_birth": "1990-01-15",
    "date_of_issue": "2025-01-15",
    "date_of_expiry": "2033-01-15",
    "address": "100 EXAMPLE AVE",
    "city": "SAMPLE CITY",
    "postal_code": "10001",
    "vehicle_class": null,
    "restrictions": null,
    "endorsements": null,
    "height": null,
    "eye_color": null,
    "document_discriminator": "SAMPLE-DISCRIMINATOR",
    "issuer_identification_number": "636000",
    "aamva_version": 10,
    "jurisdiction_version": 0
  }
}

Frequently Asked Questions

How does Java tell a state ID card from a driver license?

Read data.document_kind. It is id_card when the barcode carries an AAMVA identification-card record and driver_license otherwise. Do not infer it from an empty vehicle_class, because some jurisdictions fill that element on ID cards too.

Do I need a different endpoint for ID cards?

No. Use the same /v1/driver-license-pdf417 endpoint and request format. The type field remains drivers_license so existing integrations keep working.

Does a decoded ID card barcode prove the person’s identity?

No. It proves a usable barcode payload was decoded and parsed. Authenticity, identity, and eligibility decisions need separate controls such as document inspection or a face match.

You May Also Like

Related tutorials, platform guides, and comparisons

Tutorial

Java Driver License OCR API

Upload an image for a free test! High-accuracy Java Driver's License OCR API. Get structured JSON output from images via a simple HTTP request. Eliminate manual entry & Tesseract errors.

Java · Driver License
Tutorial

Java US Driver License PDF417 API Tutorial

Decode US driver license PDF417 barcodes with Java. Send a license-back image, parse AAMVA fields, and handle unreadable barcode errors safely.

Java · Driver License
Tutorial

Flask PDF417 Driver License API

Build a compact Python service that decodes US driver license PDF417 barcodes and returns normalized AAMVA JSON with safe retake handling.

Driver License
Tutorial

Node.js State ID Card PDF417 API Tutorial

Decode US state and Canadian provincial ID card PDF417 barcodes with Node.js. Parse AAMVA fields and tell ID cards from driver licenses.

Node.js · Driver License
Country Tutorial

Missouri Driver License OCR: Extract Fields with Python

Extract visible fields from Missouri driver license images into JSON. Map identifiers, names and dates, with a review workflow for incomplete results.

Python · Driver License
Country Tutorial

Mexico Driver License OCR: Extract Fields with Python

Extract visible fields from Mexico driver license images into JSON. Map identifiers, names and dates, with a review workflow for incomplete results.

Python · Driver License
Country Tutorial

Brazil Driver License OCR with Python SDK

Extract structured fields from a Brazil Carteira Nacional de Habilitação (CNH) with the StructOCR Python SDK and FastAPI.

Python · Driver License
Country Tutorial

Australia Driver License OCR with Node.js SDK

Extract structured fields from a Australia state or territory driver licence with the StructOCR Node.js SDK and TypeScript + Express.

Node.js · Driver License
Country Tutorial

Australia Driver License OCR with Python SDK

Extract structured fields from a Australia state or territory driver licence with the StructOCR Python SDK and FastAPI.

Python · Driver License
Country Tutorial

Brazil Driver License OCR with Node.js SDK

Extract structured fields from a Brazil Carteira Nacional de Habilitação (CNH) with the StructOCR Node.js SDK and TypeScript + Express.

Node.js · Driver License

Technical Comparisons & Integrations

Explore platform integrations and competitive analysis

From tutorial to production in 5 minutes.

You've seen the code. Now get your API key, grab your 200 free credits, and see it work with your own images. No credit card required.

Instant Access Cancel Anytime No Credit Card