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.
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:
- Your application calls
POST /v1/setupwith yourlicenseKeyandprofileIdand receives an access token. - Your application calls
POST /v1/pdf417/authenticatewith 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
licenseKeyandprofileIdare 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:
- Setup β
POST /v1/setupwithlicenseKey+profileIdβ backend validates the credentials and returns anaccessToken. - 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).
- Authenticate β
POST /v1/pdf417/authenticatewith{ rawBarcode }andAuthorization: Bearer <accessToken>β backend analyses the barcode structure and content. - Result β the response contains the classification (
REAL/FAKE/SUSPICIOUS), a confidence score, authentication details, and the parsed AAMVA fields inmdlFields.
If
/v1/pdf417/authenticatereturns401(token expired), re-run/v1/setupfor a freshaccessTokenand 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
| Requirement | Minimum | Notes |
|---|---|---|
| Browser | Chrome 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).
| Credential | Description | Reference |
|---|---|---|
| Base URL | HTTPS endpoint of the Credence PDF417 Classifier backend | For a baseUrl, contact Credence ID |
| License Key | Authentication key bound to your verification account | Generate Cloud SDK Key β |
| Profile ID | UUID identifying the verification policy for your account | Generate 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
| Field | Type | Required | Description |
|---|---|---|---|
licenseKey | string | Yes | License key associated with your verification account |
profileId | string | Yes | Profile 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
| Field | Type | Description |
|---|---|---|
accessToken | string | Bearer token to pass in the Authorization header of subsequent calls |
Errors
| HTTP | Cause | Recommended action |
|---|---|---|
| 401 | The licenseKey or profileId is invalid or expired | Verify both values against your provisioning email or contact Credence ID |
| β | Network error β the backend is unreachable | Retry with exponential backoff |
Token lifetime. The access token is short-lived. If a subsequent call returns
401, call/v1/setupagain to obtain a fresh token and retry the request once. For a simple integration, calling/v1/setupimmediately before each/v1/pdf417/authenticatecall (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
| Field | Type | Required | Description |
|---|---|---|---|
rawBarcode | string | Yes | The complete, unmodified decoded PDF417 barcode text from the back of the ID card |
Auth: Authorization: Bearer {accessToken}
Response 200 OK
| Field | Type | Description |
|---|---|---|
classification | string | REAL, FAKE, or SUSPICIOUS. Treat any unexpected value as SUSPICIOUS. |
confidence | number | Confidence score of the classification. Returned as a fraction (0.97) or a percentage (97) β handle both (see note below). |
isAuthenticated | boolean | true when the barcode passed authentication |
state | string | Issuing jurisdiction detected from the barcode (e.g. CA, NY) |
verificationMethod | string | The method used to authenticate the barcode |
verificationComment | string | Human-readable detail supporting the verification outcome |
authentication | object | Optional per-jurisdiction verification flags β see below |
mdlFields | object | Parsed AAMVA data fields as key/value string pairs β see Field Reference |
birthDate | string | Date of birth, ISO 8601 (YYYY-MM-DD). Normalised equivalent of mdlFields.dateOfBirth. |
issueDate | string | Document issue date, ISO 8601. Normalised equivalent of mdlFields.issueDate. |
expiryDate | string | Document expiry date, ISO 8601. Normalised equivalent of mdlFields.expiryDate. |
authentication object
| Field | Type | Description |
|---|---|---|
cadmvVerified | boolean | Present for California documents β true if verified against CA DMV |
nydmvVerified | boolean | Present for New York documents β true if verified against NY DMV |
Confidence value format. The
confidencefield 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
| Classification | Meaning | Recommended action |
|---|---|---|
REAL | The barcode structure and content are consistent with a genuine document | Proceed with the parsed data |
FAKE | The barcode has been flagged as fraudulent | Reject and surface a clear failure state |
SUSPICIOUS | The result is inconclusive | Route to manual review; allow the user to retry |
Default to caution. Treat any classification value other than
REALorFAKEβ 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
| Key | Description |
|---|---|
fullName | Full name |
familyName | Last or family name |
givenName | First or given name(s) |
middleName | Middle name(s) |
dateOfBirth | Date of birth β AAMVA format MMDDYYYY (prefer the ISO birthDate top-level field) |
birthYear | Year of birth |
ageInYears | Computed age |
birthPlace | Place of birth |
sex | ANSI D-20 code: 1 = male, 2 = female, 9 = not specified |
Document
| Key | Description |
|---|---|
licenseNumber | Driver's license / ID number |
issueDate | Issue date β AAMVA format MMDDYYYY (prefer the ISO issueDate top-level field) |
expiryDate | Expiry date β AAMVA format MMDDYYYY (prefer the ISO expiryDate top-level field) |
cardRevisionDate | Card revision date β AAMVA format MMDDYYYY |
documentDiscriminator | Administrative / document discriminator number |
inventoryControlNumber | Inventory control number |
complianceType | REAL ID compliance indicator |
issuingAuthority | Authority that issued the document |
issuingJurisdiction | Issuing jurisdiction |
Address
| Key | Description |
|---|---|
streetAddress | Street address |
streetAddressLine2 | Street address, second line |
city | City or municipality |
state | State or province |
postalCode | ZIP or postal code |
issuingCountry | Country |
Physical
| Key | Description |
|---|---|
height | Subject height |
weightLbs | Weight in pounds |
weightKg | Weight in kilograms |
eyeColor | Eye color |
hairColor | Hair color |
race | Race / ethnicity code |
Driving
| Key | Description |
|---|---|
jurisdictionVehicleClass | Jurisdiction-specific vehicle class |
jurisdictionRestrictions | Jurisdiction-specific restrictions |
jurisdictionEndorsements | Jurisdiction-specific endorsements |
standardVehicleClass | Standard vehicle class |
Flags
| Key | Description |
|---|---|
organDonor | 1 = yes, 0 = no |
dhsTemporaryLawfulStatus | 1 = 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);
}
| Scenario | Cause | Recommended action |
|---|---|---|
| Setup failure (401) | Invalid or expired licenseKey / profileId | Verify both credential values. Contact Credence ID if the problem persists. |
| Setup failure (network) | Backend unreachable | Check connectivity. Retry with exponential backoff. |
| Authenticate failure (401) | Access token expired | Call /v1/setup again for a fresh token and retry once. |
| Authenticate failure (4xx) | rawBarcode missing, empty, or not a valid PDF417 payload | Confirm the complete, unmodified decoded string is being sent. Re-capture if necessary. |
classification: "FAKE" | Document flagged as fraudulent | This is a successful API call, not an error. Surface a rejection state to the user. |
classification: "SUSPICIOUS" | Inconclusive result | Route to manual review; offer the user a retry. |
| Barcode won't decode | Poor image quality, glare, damage | This occurs in your capture layer, before the API is called. Prompt the user to re-capture with better lighting and framing. |
10API Reference Summary
| Endpoint | Method | Auth | Description | Returns |
|---|---|---|---|---|
/v1/setup | POST | Credentials in body | Exchange licenseKey + profileId for an access token | { accessToken } |
/v1/pdf417/authenticate | POST | Authorization: Bearer <accessToken> | Classify a raw PDF417 barcode string and parse its data fields | Classification 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/setupcalled andaccessTokenobtained before/v1/pdf417/authenticate -
accessTokensent asAuthorization: Bearer <token>on the authenticate call -
401on authenticate handled by re-running/v1/setupand retrying once
Result handling
- All three classifications handled:
REAL(proceed),FAKE(reject),SUSPICIOUS(manual review) - Unexpected classification values treated as
SUSPICIOUSβ never auto-proceed -
confidencenormalised for both fraction and percentage formats - ISO date fields (
birthDate,issueDate,expiryDate) preferred over raw AAMVA dates inmdlFields -
mdlFieldskeys 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