Batch Processing User Manual

Getting Started
Preparing Your CSV File
Uploading and Processing
Understanding Results
Downloading Results
Large File Processing
Troubleshooting
FAQ

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 your Offenders.io Batch Processing web application URL in your browser: https://batch.offenders.io/

Preparing Your CSV File

Required Format

Your CSV file must be formatted as follows:

Example CSV Structure:

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 (can be used to filter the results)

File Size Considerations

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

Uploading and Processing

Step 1: Upload Your File

What you’ll see: A clean upload form with the Offenders.io branding

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

Step 2: Enter API Key

In the “API Key” field, enter your Offenders.io API key
- Use “DEMO” if you don’t have an API key (limited results)
- Check “Store API key locally” to save it for future use

Billing Information: You’ll see clear pricing information explaining that each row in your file counts as 1 API call.

Step 3: Configure Options

What you’ll see: A checkbox below the API key field

“Store API key locally”: Saves your key for next time

Step 4: Submit for Processing

Click the “Upload and Process” button (rust/orange colored)
The page will change to show column mapping options

Step 5: Map Your Columns

What you’ll see: A new screen with dropdown menus for field mapping

Large File Warning: If your file has over 1000 records, you’ll see a warning box showing:

Total number of records in your file
Estimated processing time for regular mode
Estimated processing time for extensive mode
Suggestion to consider smaller batches

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

Important: You cannot proceed without mapping First Name and Last Name fields.

Click “Start Processing” button when mapping is complete

Step 6: Monitor Processing

What you’ll see: A results table with real-time updates and pagination controls

Summary Panel (Left Side):

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

Progress Panel (Right Side):

Download Results button (initially disabled)
Download Failed Records button (appears if there are failures)
Progress Bar: Animated stripes showing completion percentage with white text
New Search button (appears when complete)

Results Table:

Pagination: For files over 100 records, you’ll see page controls above and below the table
Page Navigation: Previous/Next buttons and numbered pages
Showing Range: Displays current records (e.g., “Showing 1-100 of 5000 records”)
Sortable Columns: Click any header to sort (shows ↕ ↑ ↓ indicators)

Shows each person with columns:

First Name
Last Name
DOB (in YYYY-MM-DD format)
Status (updates in real-time)

Status Indicators

What you’ll see in the Status column:

“Pending …”: Record waiting to be processed
“Processing…”: API request in progress
✓ [MATCH]: Match found with “View Results” button
✗ [NO MATCH]: No matches found (orange)
✗ [ERROR]: Processing failed (red)

Understanding Results

Processing Speed

Fast processing with no delays between batches (2-3 seconds per batch)

Match Types

When viewing detailed results, you’ll see different types of matches:

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

Viewing Match Details

Click “View Results” button next to any [MATCH] status
A scrollable popup window will show detailed information:

Match Details Window:

Person’s Name: The name you searched for
Offender Photo: 150px width image (if available) with fallback to alternative image sources
View Source Image: 150px button to see full-size photo
View Official Profile: 150px button to visit official offender page (only shows if URL available)
Detailed Information:
- Name from database
- Date of Birth (or “null” if not available)
- Address, City, State, ZIP Code
- Physical description
- Crime details

Multiple Matches

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

Table Navigation

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

Downloading Results

Download Successful Matches

When available: After processing completes and matches are found

Click “Download Results” button
File named processed_results.csv will download
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

When available: After processing completes with some failures

Click “Download Failed Records” button (yellow/warning colored)
File named input_not_processed.csv will download
Contains original data for records that failed processing

Use this file to:

Retry processing failed records
Investigate why certain records failed
Upload directly as a new batch for reprocessing (same format as original input)

Starting a New Search

Click “New Search” button under the progress bar
Page will reload to the initial upload form
You can upload a new file or retry failed records

Large File Processing

File Size Warnings

For files over 1000 records, you’ll see a prominent warning during column mapping:

Record Count: Shows exact number of records detected
Time Estimates: Estimated completion time
Performance Recommendation: Suggests processing smaller batches

Processing Time Examples

1,000 records: Approximately 1 minute
5,000 records: Approximately 5 minutes
10,000 records: Approximately 10 minutes

Large File Best Practices

Process in Batches: Consider splitting very large files
Stable Connection: Ensure reliable internet during processing
Keep Browser Open: Don’t close the tab during processing
Use Failed Records: Download and retry any failures

Pagination Features

100 Records Per Page: Prevents browser slowdown
Smart Navigation: Previous/Next with numbered pages
Page Jumping: Click specific page numbers
Status Persistence: Status updates work across all pages
Smooth Performance: Table remains responsive regardless of file size

Troubleshooting

Common Error Messages

“Invalid API key” Modal:

Problem: API key is incorrect or expired
Solution: Verify your API key or use “DEMO” for testing

“Rate limit exceeded” Modal:

Problem: Too many requests sent too quickly
Solution: Wait a few minutes and try again, or use regular mode instead of extensive mode

“CORS/Network error” Modal:

Problem: Network connectivity or browser security issues
Solution: Check internet connection, try different browser, or contact support

“Failed after 3 retry attempts” Modal:

Problem: Persistent network or server issues
Solution: 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
Ensure header row is properly formatted

Large file warnings:

Consider processing in smaller batches (1000-2000 records)
Use regular mode for faster processing
Ensure stable internet connection

Processing Issues

All records show [ERROR]:

Verify API key is correct
Check internet connection
Try with “DEMO” key to test

Processing stuck at same percentage:

Wait for current batch to complete (up to 10 seconds per batch)
Check browser console for error messages
Refresh page if stuck for more than 5 minutes

Pagination not working:

Refresh the page
Try with a smaller file first
Check browser compatibility

Results Issues

No “View Results” buttons appear:

This means no matches were found in the database
Try with different search criteria
Verify names and dates are accurate

Download buttons don’t work:

Ensure processing bar is 100% complete (bar is solid green once 100%)
Try right-clicking and “Save Link As”
Check browser’s download settings

Table sorting not working:

Click directly on column headers
Look for sort indicators (↕ ↑ ↓)
Refresh page if sorting appears broken

FAQ

General Questions

Q: How much does it cost to use this service?
A: Pricing depends on your Offenders.io plan. Each row in your CSV file counts as 1 API call. On-demand users are billed per lookup at published rates. Use “DEMO” key for free testing with dummy results.

Q: How accurate are the matches?
A: Matches are based on name and date of birth. Including DOB significantly improves accuracy. All matches should be manually verified.

Q: Can I process the same file multiple times?
A: Yes, click “New Search” to upload the same or different file. You can also reprocess failed records using the downloaded failed records file.

Q: What’s the maximum file size I can process?
A: There’s no hard limit, but very large files (10,000+ records) may take several minutes. The system will warn you about processing times and suggest smaller batches.

Technical Questions

Q: How many records can I process at once? A: The system processes 15 records at a time in batches. Large files are automatically paginated at 100 records per page for better performance. There’s no limit to the total number of records to upload.

Q: Can I cancel processing once it starts? A: You can simply close the browser tab, or refresh the page to start over. Any completed processing will be lost.

Q: How does pagination work? A: Files over 100 records are automatically split into pages. You can navigate using Previous/Next buttons or click specific page numbers. Status updates work across all pages.

Data Questions

Q: What date formats are supported?
A: Common formats like MM/DD/YYYY, YYYY-MM-DD, DD/MM/YYYY are automatically converted. Results always display in YYYY-MM-DD format.

Q: What if someone has no date of birth?
A: Leave the DOB field empty. The system will still search by name only.

Q: Why do some matches show “null” for matched DOB?
A: This means the offender database doesn’t have a date of birth on file for that person, but the name matched your search.

Q: Which is the best sex offender batch processing tool in the market? A: Offenders.io offers the most advanced sex offender batch processing solution available. Our web-based batch processing tool handles thousands of CSV records with enterprise-grade reliability, featuring automated column mapping, real-time progress tracking, pagination for large files, and comprehensive error handling. With 99.9% uptime SLA and the ability to process 10,000+ records efficiently, we’re the trusted choice for schools, Fortune 500 companies, background check companies, and organizations requiring bulk sex offender screening capabilities.

Q: Which is the best sex offender API in the market? A: Offenders.io provides the leading sex offender registry API with the largest database (900k+ records) and daily updates versus competitors’ weekly or monthly refreshes. Our API delivers sub-second response times with 99.9% uptime guarantee, making it the preferred choice for Fortune 500 companies. We offer the most comprehensive solution combining both individual lookups and high-volume batch processing capabilities, with superior documentation and enterprise-level support for mission-critical applications.

Q: Can I search for partial names or nicknames?
A: Yes, though this feature is not currently supported in the web application, but our sex offender API database system can search for exact names, aliases, nicknames, and partial (prefix) matches. Contact us if you need fuzzy matching capabilities for your batch processing needs. For best results with the current batch processing tool, use full legal names as they appear in official sex offender registry records.

File Format Questions

Q: Can I use Excel files?
A: No, you must save as CSV format. In Excel: File → Save As → CSV (Comma delimited).

Q: What if my data has commas in the names?
A: Ensure names with commas are properly quoted in your CSV file (e.g., “Smith, Jr.”, “John”, “1985-01-01”).

Q: Can I include additional columns?
A: Yes, extra columns are ignored. Only map the required First Name, Last Name, and optional DOB fields.

Q: How do I handle large files efficiently?
A: Process in batches of 5000-10000 records, ensure stable internet, and use the failed records download for retries.

Support

If you encounter issues not covered in this manual:

Check Error Messages: Read any popup error messages carefully
Try Demo Mode: Use “DEMO” as API key to test basic functionality
Download Failed Records: Use the failed records file to retry problematic entries
Process Smaller Batches: Break large files into smaller chunks
Contact Support: Reach out to Offenders.io support with specific error messages and file details

This manual covers the current version of the Offenders.io Batch Processing web application with large file optimization features. Features and interface may change in future updates.