PDF417 Classifier - Integration

Integrate the Credence PDF417 Classifier REST API: exchange credentials for an access token, decode the barcode, authenticate it, and parse AAMVA credential data.

Generate license key β†’Latest SDK: v0.0.18

01Overview

The Credence PDF417 Classifier enables web applications to authenticate driver's licenses and ID cards by analysing the PDF417 barcode printed on the back of the card. The service classifies the barcode as REAL, FAKE, or SUSPICIOUS, returns a confidence score, and extracts the full set of AAMVA data fields (name, date of birth, license number, address, and more).

The integration is a plain REST API flow β€” no SDK installation is required. There are exactly two API calls:

  1. Your application calls POST /v1/setup with your licenseKey and profileId and receives an access token.
  2. Your application calls POST /v1/pdf417/authenticate with the raw barcode string and the access token, and receives the classification result and parsed data fields.

How you capture the barcode is up to you. The classifier does not capture or decode images. For web applications we recommend the open-source ZXing library to decode the PDF417 barcode from the camera or an uploaded image β€” but this is only a recommendation. Your application may obtain the decoded PDF417 raw string by any means: any other barcode scanning library, a mobile scanning SDK, a hardware barcode scanner, or an existing capture pipeline you already have. Whatever the source, the only thing the API needs is the complete, unmodified raw barcode text passed as rawBarcode.

Backend configuration. Your licenseKey and profileId are issued by Credence ID at account provisioning and control which verification features are enabled for your account. Contact Credence ID to set up or modify these settings.


02Sequence Diagram

The diagram below shows the complete flow from your web application to the Credence backend β€” setup, barcode capture, authentication, and result handling.

sequenceDiagram
  participant User as End User
  participant App as Your Web App
  participant API as PDF417 Classifier API

  App->>API: POST /v1/setup { licenseKey, profileId }
  API->>API: Validate credentials
  API-->>App: 200 OK { accessToken }

  User->>App: Presents back of ID card
  App->>App: Decode PDF417 barcode by any means<br/>(any library / SDK / hardware scanner)<br/>-> rawBarcode string
  Note over App: Capture method is outside the API scope.<br/>Only the decoded raw text string is ever sent β€” no card image.

  App->>API: POST /v1/pdf417/authenticate<br/>{ rawBarcode }<br/>Authorization: Bearer accessToken
  API->>API: Classify barcode<br/>REAL / FAKE / SUSPICIOUS<br/>+ parse AAMVA data fields
  API-->>App: 200 OK { classification, confidence,<br/>isAuthenticated, state, verificationMethod, mdlFields, ... }

  App->>App: Handle result<br/>REAL -> proceed Β· FAKE -> reject<br/>SUSPICIOUS -> manual review
  App->>User: Display verification result

  Note over App,API: If /v1/pdf417/authenticate returns 401 (token expired):<br/>re-run /v1/setup for a fresh accessToken and retry once.

The diagram covers four phases:

  1. Setup β€” POST /v1/setup with licenseKey + profileId β†’ backend validates the credentials and returns an accessToken.
  2. Capture β€” your application decodes the PDF417 barcode on the back of the ID card and obtains the raw barcode string (ZXing recommended for web applications; any library or hardware device works β€” outside the scope of this API).
  3. Authenticate β€” POST /v1/pdf417/authenticate with { rawBarcode } and Authorization: Bearer <accessToken> β†’ backend analyses the barcode structure and content.
  4. Result β€” the response contains the classification (REAL / FAKE / SUSPICIOUS), a confidence score, authentication details, and the parsed AAMVA fields in mdlFields.

If /v1/pdf417/authenticate returns 401 (token expired), re-run /v1/setup for a fresh accessToken and retry once.


03Quick Start

This is a complete, self-contained example showing the full lifecycle. Read this first; the sections below explain each step in detail.

import axios from "axios";

// ── 1. Credentials from environment variables ───────────────────────────────
// Vite: VITE_ prefix, import.meta.env  (see Configuration section)
// Next.js: NEXT_PUBLIC_ prefix, process.env
// CRA: REACT_APP_ prefix, process.env
const BASE_URL    = import.meta.env.VITE_PDF417_CLASSIFIER_BASE_URL as string;
const LICENSE_KEY = import.meta.env.VITE_PDF417_LICENSE_KEY         as string;
const PROFILE_ID  = import.meta.env.VITE_PDF417_PROFILE_ID          as string;

// ── 2. Authenticate a raw PDF417 barcode string ─────────────────────────────
export async function pdf417Authenticate(rawBarcode: string) {
  // Step 1 β€” Setup: exchange credentials for an access token
  const setupResponse = await axios.post(
    `${BASE_URL}/v1/setup`,
    { licenseKey: LICENSE_KEY, profileId: PROFILE_ID },
    { withCredentials: true }
  );
  const accessToken: string = setupResponse.data.accessToken;

  // Step 2 β€” Authenticate: pass the raw barcode string
  const response = await axios.post(
    `${BASE_URL}/v1/pdf417/authenticate`,
    { rawBarcode },
    {
      withCredentials: true,
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );
  return response.data;
}

// ── 3. Handle the result ─────────────────────────────────────────────────────
async function handleBarcode(rawBarcode: string) {
  try {
    const result = await pdf417Authenticate(rawBarcode);

    switch (result.classification) {
      case "REAL":
        // Barcode authenticated β€” proceed
        console.log("Name:", result.mdlFields?.fullName);
        console.log("DOB:",  result.birthDate);
        break;
      case "FAKE":
        // Flagged as fraudulent β€” reject
        break;
      default:
        // "SUSPICIOUS" or any unexpected value β€” manual review
        break;
    }
  } catch (err: any) {
    const message =
      err?.response?.data?.error?.errorMessage ??
      err?.message ??
      "An unexpected error occurred.";
    showError(message); // your UI
  }
}

04Prerequisites

Runtime requirements

RequirementMinimumNotes
BrowserChrome 67+, Firefox 60+, Safari 12+, Edge 79+Requires async/await, Promises, fetch (or an HTTP client such as axios)
Barcode inputβ€”Your application must supply the decoded PDF417 raw string. ZXing is recommended for web applications; any capture method is acceptable.

Required credentials

All three values are issued by Credence ID at account provisioning. Separate credentials are required for each environment (development, staging, production).

CredentialDescriptionReference
Base URLHTTPS endpoint of the Credence PDF417 Classifier backendFor a baseUrl, contact Credence ID
License KeyAuthentication key bound to your verification accountGenerate Cloud SDK Key β†’
Profile IDUUID identifying the verification policy for your accountGenerate Cloud SDK Key β†’

05Configuration

Injecting credentials via environment variables

Never hardcode credentials in source code. Always inject them through your build system's environment variable mechanism and exclude credential files from version control (add .env to .gitignore).

Vite

# .env
VITE_PDF417_CLASSIFIER_BASE_URL=PDF417_CLASSIFIER_BASE_URL
VITE_PDF417_LICENSE_KEY=CS_xxxx
VITE_PDF417_PROFILE_ID=xxxx-xxxx-xxxx-xxxx
// Access in browser code:
const baseUrl    = import.meta.env.VITE_PDF417_CLASSIFIER_BASE_URL;
const licenseKey = import.meta.env.VITE_PDF417_LICENSE_KEY;
const profileId  = import.meta.env.VITE_PDF417_PROFILE_ID;

Next.js

# .env.local
NEXT_PUBLIC_BASE_URL=PDF417_CLASSIFIER_BASE_URL
NEXT_PUBLIC_PDF417_LICENSE_KEY=CS_xxxx
NEXT_PUBLIC_PDF417_PROFILE_ID=xxxx-xxxx-xxxx-xxxx
const baseUrl    = process.env.NEXT_PUBLIC_BASE_URL;
const licenseKey = process.env.NEXT_PUBLIC_PDF417_LICENSE_KEY;
const profileId  = process.env.NEXT_PUBLIC_PDF417_PROFILE_ID;

Create React App

# .env
REACT_APP_BASE_URL=PDF417_CLASSIFIER_BASE_URL
REACT_APP_PDF417_LICENSE_KEY=CS_xxxx
REACT_APP_PDF417_PROFILE_ID=xxxx-xxxx-xxxx-xxxx
const baseUrl    = process.env.REACT_APP_BASE_URL;
const licenseKey = process.env.REACT_APP_PDF417_LICENSE_KEY;
const profileId  = process.env.REACT_APP_PDF417_PROFILE_ID;

06Obtaining the Raw Barcode

The PDF417 barcode on the back of a driver's license encodes an AAMVA-standard data payload. The classifier requires this payload exactly as decoded β€” the complete raw text, including the leading @ compliance character and all control characters (record separators, line feeds).

Recommended capture library: ZXing. For web applications, we recommend the open-source ZXing ("Zebra Crossing") library. It decodes PDF417 barcodes directly in the browser from a live camera stream and its raw text output can be passed to the API as-is.

This is a recommendation, not a requirement. Any capture approach that produces the complete decoded PDF417 string is fully supported:

  • Any barcode scanning library in your web application (ZXing or otherwise)
  • Any native mobile scanning SDK (iOS / Android)
  • Any hardware barcode scanner (USB, Bluetooth, or integrated kiosk scanner)
  • Any existing capture pipeline or backend decoding service you already operate

Requirements for the rawBarcode value:

  • Pass the complete, unmodified decoded string. Do not trim, re-encode, strip control characters, or normalise line endings.
  • The barcode must be a PDF417 symbology read from the back of the ID card. Other symbologies (QR, Code 128) on the card are not accepted.

The classifier never sees the card image. Only the decoded text string is transmitted. This keeps the payload small (a single HTTPS POST with a text body) and leaves image capture entirely under your control.


07API Reference

POST /v1/setup7.1.

Purpose: authenticates your application against the backend and returns a short-lived access token. Must be called before POST /v1/pdf417/authenticate.

Request body

FieldTypeRequiredDescription
licenseKeystringYesLicense key associated with your verification account
profileIdstringYesProfile ID defining the verification policy

Example

const setupResponse = await axios.post(
  `${BASE_URL}/v1/setup`,
  { licenseKey: LICENSE_KEY, profileId: PROFILE_ID },
  { withCredentials: true }
);
const accessToken: string = setupResponse.data.accessToken;

Response 200 OK

FieldTypeDescription
accessTokenstringBearer token to pass in the Authorization header of subsequent calls

Errors

HTTPCauseRecommended action
401The licenseKey or profileId is invalid or expiredVerify both values against your provisioning email or contact Credence ID
β€”Network error β€” the backend is unreachableRetry with exponential backoff

Token lifetime. The access token is short-lived. If a subsequent call returns 401, call /v1/setup again to obtain a fresh token and retry the request once. For a simple integration, calling /v1/setup immediately before each /v1/pdf417/authenticate call (as in the Quick Start) is a valid pattern.


POST /v1/pdf417/authenticate7.2.

Purpose: analyses the raw PDF417 barcode string, classifies it as REAL, FAKE, or SUSPICIOUS, and returns the parsed AAMVA data fields.

Request body

FieldTypeRequiredDescription
rawBarcodestringYesThe complete, unmodified decoded PDF417 barcode text from the back of the ID card

Auth: Authorization: Bearer {accessToken}

Response 200 OK

FieldTypeDescription
classificationstringREAL, FAKE, or SUSPICIOUS. Treat any unexpected value as SUSPICIOUS.
confidencenumberConfidence score of the classification. Returned as a fraction (0.97) or a percentage (97) β€” handle both (see note below).
isAuthenticatedbooleantrue when the barcode passed authentication
statestringIssuing jurisdiction detected from the barcode (e.g. CA, NY)
verificationMethodstringThe method used to authenticate the barcode
verificationCommentstringHuman-readable detail supporting the verification outcome
authenticationobjectOptional per-jurisdiction verification flags β€” see below
mdlFieldsobjectParsed AAMVA data fields as key/value string pairs β€” see Field Reference
birthDatestringDate of birth, ISO 8601 (YYYY-MM-DD). Normalised equivalent of mdlFields.dateOfBirth.
issueDatestringDocument issue date, ISO 8601. Normalised equivalent of mdlFields.issueDate.
expiryDatestringDocument expiry date, ISO 8601. Normalised equivalent of mdlFields.expiryDate.

authentication object

FieldTypeDescription
cadmvVerifiedbooleanPresent for California documents β€” true if verified against CA DMV
nydmvVerifiedbooleanPresent for New York documents β€” true if verified against NY DMV

Confidence value format. The confidence field may arrive as a fraction between 0 and 1 or as a percentage. Normalise before display:

const confidencePct =
  Number(result.confidence) > 1
    ? Number(result.confidence)                    // already a percentage
    : Math.round(Number(result.confidence) * 100); // fraction β†’ percentage

Classification handling

ClassificationMeaningRecommended action
REALThe barcode structure and content are consistent with a genuine documentProceed with the parsed data
FAKEThe barcode has been flagged as fraudulentReject and surface a clear failure state
SUSPICIOUSThe result is inconclusiveRoute to manual review; allow the user to retry

Default to caution. Treat any classification value other than REAL or FAKE β€” including unexpected values β€” as requiring manual review. Never proceed automatically on an unrecognized classification.

Example response

{
  "classification": "REAL",
  "confidence": 0.98,
  "isAuthenticated": true,
  "state": "CA",
  "verificationMethod": "BARCODE_STRUCTURE_ANALYSIS",
  "verificationComment": "Barcode structure consistent with issuing jurisdiction",
  "authentication": { "cadmvVerified": true },
  "birthDate": "1990-01-15",
  "issueDate": "2022-03-01",
  "expiryDate": "2027-01-15",
  "mdlFields": {
    "fullName": "JANE DOE",
    "familyName": "DOE",
    "givenName": "JANE",
    "dateOfBirth": "01151990",
    "licenseNumber": "D1234567",
    "streetAddress": "123 MAIN ST",
    "city": "SACRAMENTO",
    "state": "CA",
    "postalCode": "95814",
    "sex": "2",
    "eyeColor": "BRN",
    "height": "065 in"
  }
}

08Field Reference

mdlFields contains the parsed AAMVA data elements as string key/value pairs. Field availability depends on the issuing jurisdiction β€” always validate presence before use.

Identity

KeyDescription
fullNameFull name
familyNameLast or family name
givenNameFirst or given name(s)
middleNameMiddle name(s)
dateOfBirthDate of birth β€” AAMVA format MMDDYYYY (prefer the ISO birthDate top-level field)
birthYearYear of birth
ageInYearsComputed age
birthPlacePlace of birth
sexANSI D-20 code: 1 = male, 2 = female, 9 = not specified

Document

KeyDescription
licenseNumberDriver's license / ID number
issueDateIssue date β€” AAMVA format MMDDYYYY (prefer the ISO issueDate top-level field)
expiryDateExpiry date β€” AAMVA format MMDDYYYY (prefer the ISO expiryDate top-level field)
cardRevisionDateCard revision date β€” AAMVA format MMDDYYYY
documentDiscriminatorAdministrative / document discriminator number
inventoryControlNumberInventory control number
complianceTypeREAL ID compliance indicator
issuingAuthorityAuthority that issued the document
issuingJurisdictionIssuing jurisdiction

Address

KeyDescription
streetAddressStreet address
streetAddressLine2Street address, second line
cityCity or municipality
stateState or province
postalCodeZIP or postal code
issuingCountryCountry

Physical

KeyDescription
heightSubject height
weightLbsWeight in pounds
weightKgWeight in kilograms
eyeColorEye color
hairColorHair color
raceRace / ethnicity code

Driving

KeyDescription
jurisdictionVehicleClassJurisdiction-specific vehicle class
jurisdictionRestrictionsJurisdiction-specific restrictions
jurisdictionEndorsementsJurisdiction-specific endorsements
standardVehicleClassStandard vehicle class

Flags

KeyDescription
organDonor1 = yes, 0 = no
dhsTemporaryLawfulStatus1 = yes, 0 = no

Handling AAMVA dates

Date values inside mdlFields use the AAMVA MMDDYYYY format. The top-level birthDate, issueDate, and expiryDate response fields carry the same values already normalised to ISO 8601 β€” prefer those. If you must parse an AAMVA date yourself:

function formatAamvaDate(raw: string): string {
  if (!/^\d{8}$/.test(raw)) return raw;
  const mm = raw.slice(0, 2);
  const dd = raw.slice(2, 4);
  const yyyy = raw.slice(4, 8);
  return `${yyyy}-${mm}-${dd}`; // ISO 8601
}

09Error Handling

Error responses carry a structured body. Extract the message defensively:

try {
  const result = await pdf417Authenticate(rawBarcode);
} catch (err: any) {
  const message =
    err?.response?.data?.error?.errorMessage ??
    err?.message ??
    "An unexpected error occurred.";
  showError(message);
}
ScenarioCauseRecommended action
Setup failure (401)Invalid or expired licenseKey / profileIdVerify both credential values. Contact Credence ID if the problem persists.
Setup failure (network)Backend unreachableCheck connectivity. Retry with exponential backoff.
Authenticate failure (401)Access token expiredCall /v1/setup again for a fresh token and retry once.
Authenticate failure (4xx)rawBarcode missing, empty, or not a valid PDF417 payloadConfirm the complete, unmodified decoded string is being sent. Re-capture if necessary.
classification: "FAKE"Document flagged as fraudulentThis is a successful API call, not an error. Surface a rejection state to the user.
classification: "SUSPICIOUS"Inconclusive resultRoute to manual review; offer the user a retry.
Barcode won't decodePoor image quality, glare, damageThis occurs in your capture layer, before the API is called. Prompt the user to re-capture with better lighting and framing.

10API Reference Summary

EndpointMethodAuthDescriptionReturns
/v1/setupPOSTCredentials in bodyExchange licenseKey + profileId for an access token{ accessToken }
/v1/pdf417/authenticatePOSTAuthorization: Bearer <accessToken>Classify a raw PDF417 barcode string and parse its data fieldsClassification result + mdlFields

11Integration Checklist

Use this as a pre-launch review against your integration. Every item should be verifiable in your code.

Setup

  • All three credentials (Base URL, License Key, Profile ID) sourced from environment variables β€” not hardcoded in source
  • .env (or equivalent credential file) added to .gitignore
  • Framework-correct env var prefix used (VITE_, NEXT_PUBLIC_, REACT_APP_)

Barcode capture

  • Capture method chosen β€” ZXing (recommended for web applications), another library, or a hardware scanner
  • The complete, unmodified decoded PDF417 string is passed as rawBarcode β€” no trimming, re-encoding, or control-character stripping
  • Capture-layer failures (barcode not detected) handled in your UI before any API call is made

API calls

  • /v1/setup called and accessToken obtained before /v1/pdf417/authenticate
  • accessToken sent as Authorization: Bearer <token> on the authenticate call
  • 401 on authenticate handled by re-running /v1/setup and retrying once

Result handling

  • All three classifications handled: REAL (proceed), FAKE (reject), SUSPICIOUS (manual review)
  • Unexpected classification values treated as SUSPICIOUS β€” never auto-proceed
  • confidence normalised for both fraction and percentage formats
  • ISO date fields (birthDate, issueDate, expiryDate) preferred over raw AAMVA dates in mdlFields
  • mdlFields keys validated for presence before use β€” availability varies by jurisdiction

Error states

  • Error messages extracted defensively: err?.response?.data?.error?.errorMessage ?? err?.message
  • Setup and authenticate failures surface actionable, user-facing messages
  • Users can retry after a failed or inconclusive verification