Batch Processing Guide

1. Getting Started

What You Need

• A CSV file with personal information (First Name, Last Name, Date of Birth)
• An API key from Offenders.io (or use "DEMO" for testing)
• A modern web browser (Chrome, Firefox, Safari, Edge)

Accessing the Application

Navigate to https://batch.offenders.io in your browser.

2. Preparing Your CSV File

Required Format

Your CSV file must be formatted as follows:

First Name,Last Name,DOB
Demo,PersonA,1234-01-01
Sample,PersonB,1234-02-02
Test,PersonC,1234-03-03

Important Requirements

• Header Row: First row must contain column names
• Comma Separated: All values must be separated by commas
• Supported Formats: .csv or .txt files
• Date Formats: Various formats accepted (MM/DD/YYYY, YYYY-MM-DD, etc.)

Column Requirements

• First Name: Required — person's first name
• Last Name: Required — person's last name
• DOB: Optional — date of birth (improves match accuracy)

File Size Considerations

• Small Files (under 1,000 records): Process quickly with no special considerations
• Large Files (1,000+ records): Will show warnings and time estimates
• Very Large Files (10,000+ records): Consider processing in smaller batches

3. Uploading and Processing

Step 1: Upload Your File

1. Click the "Choose File" button under "Upload CSV File"
2. Select your prepared CSV file from your computer
3. The form will show supported formats: .csv, .txt

Step 2: Enter API Key

1. In the "API Key" field, enter your Offenders.io API key
2. Use "DEMO" if you don't have an API key (limited results)
3. Check "Store API key locally" to save it for future use

Billing: Each row in your file counts as 1 API call, billed at your plan rate.

Step 3: Configure Options

"Store API key locally" checkbox saves your key in the browser for next time.

Step 4: Submit for Processing

Click the "Upload and Process" button. The page will change to show column mapping options.

Step 5: Map Your Columns

Use the dropdown menus to map your CSV columns:

1. First Name: Select which column contains first names (Required)
2. Last Name: Select which column contains last names (Required)
3. Date of Birth: Select DOB column (Optional but recommended)

You cannot proceed without mapping First Name and Last Name. For files over 1,000 records, you'll see a warning with estimated processing time.

Click "Start Processing" when mapping is complete.

Step 6: Monitor Processing

The results screen shows real-time progress:

Summary Panel (Left Side):

• Total: Total number of records
• Processing: Shows "completed/total" (e.g., "25/100")
• Matches: Records with offender matches
• No Matches: Records with no matches found
• Errors: Failed processing attempts

Progress Panel (Right Side):

• Download Results button (enabled when complete)
• Download Failed Records button (appears if there are failures)
• Progress Bar: Animated stripes showing completion percentage
• New Search button (appears when complete)

For files over 100 records, results are paginated with Previous/Next buttons and numbered pages. Click any column header to sort (shows ↕ ↑ ↓ indicators).

Status Indicators

The Status column shows real-time updates for each record:

• "Pending ..." — Record waiting to be processed
• "Processing..." — API request in progress
• ✓ [MATCH] — Match found with "View Results" button
• ✗ [NO MATCH] — No matches found
• ✗ [ERROR] — Processing failed

4. Understanding Results

Processing Speed

Records process in batches with 2-3 seconds per batch and no delays between batches.

Match Types

When viewing detailed results, you'll see different match types:

• Strict DOB Match: Exact date of birth match
• Null DOB Match: Name matched but offender has no DOB on file

Viewing Match Details

Click "View Results" next to any [MATCH] status. A scrollable popup shows:

• Person's Name: The name you searched for
• Offender Photo: Profile image (if available) with fallback sources
• View Source Image: Button to see full-size photo
• View Official Profile: Button to visit official state agency page
• Detailed Information: Name, DOB, address, city, state, zip, physical description, crime details

Multiple Matches

If one person matches multiple offender records, each match is shown as a separate card in the details window.

Table Navigation

• Sorting: Click any column header to sort (First Name, Last Name, DOB, Status)
• Pagination: Use Previous/Next or numbered page buttons for large result sets
• Page Size: 100 records per page for optimal performance

5. Downloading Results

Download Successful Matches

After processing completes and matches are found:

1. Click "Download Results" button
2. File named processed_results.csv will download
3. Contains all successful matches with detailed offender information

Downloaded file includes: Original person data (First Name, Last Name, DOB in ISO format), matched DOB from offender database, offender URLs and image links, address information. Multiple rows if person matches multiple offenders.

Download Failed Records

If some records failed processing:

1. Click "Download Failed Records" button
2. File named input_not_processed.csv will download
3. Contains original data for records that failed — same format as input, so you can upload directly as a new batch for reprocessing

Starting a New Search

Click "New Search" under the progress bar. The page reloads to the initial upload form where you can upload a new file or retry failed records.

6. Large File Processing

File Size Warnings

For files over 1,000 records, you'll see a prominent warning during column mapping showing:

• Total number of records detected
• Estimated completion time for regular and extensive modes
• Recommendation to consider smaller batches

Processing Time Examples

Large File Best Practices

1. Process in Batches: Split very large files into 5,000-10,000 record chunks
2. Stable Connection: Ensure reliable internet during processing
3. Keep Browser Open: Don't close the tab during processing
4. Use Failed Records: Download and retry any failures

Pagination Features

• 100 records per page — prevents browser slowdown
• Previous/Next with numbered page navigation
• Status updates work across all pages
• Table remains responsive regardless of file size

7. Troubleshooting

Common Error Messages

• "Invalid API key" Modal: API key is incorrect or expired. Verify your key or use "DEMO" for testing.
• "Rate limit exceeded" Modal: Too many requests sent too quickly. Wait a few minutes and try again, or use regular mode instead of extensive mode.
• "CORS/Network error" Modal: Network connectivity or browser security issues. Check internet connection, try a different browser, or contact support.
• "Failed after 3 retry attempts" Modal: Persistent network or server issues. Download failed records and try again later.

File Upload Issues

• Upload button does nothing: Check file format (.csv or .txt only). Ensure file has proper header row. Try with a smaller file first.
• Column mapping shows wrong data: Verify CSV uses comma separators (not semicolons or tabs). Check for extra commas in data fields.
• Large file warnings: Consider processing in smaller batches (1,000-2,000 records). Use regular mode for faster processing.

Processing Issues

• All records show [ERROR]: Verify API key is correct. Check internet connection. Try with "DEMO" key to test.
• Processing stuck: Wait for current batch to complete (up to 10 seconds per batch). Refresh page if stuck for more than 5 minutes.
• Pagination not working: Refresh the page. Try with a smaller file first.

Results Issues

• No "View Results" buttons: No matches were found. Try with different search criteria or verify names are accurate.
• Download buttons don't work: Ensure processing bar is 100% complete (solid green). Try right-clicking and "Save Link As".
• Table sorting not working: Click directly on column headers. Look for sort indicators. Refresh page if sorting appears broken.

8. FAQ

General Questions

Technical Questions

Data Questions

File Format Questions

Support

If you encounter issues not covered here:

1. Read any popup error messages carefully
2. Use "DEMO" as API key to test basic functionality
3. Download failed records and retry problematic entries
4. Break large files into smaller chunks
5. Contact support with specific error messages and file details