About the OFAC API

The Story Behind This Project

The OFAC API was born from real-world experience with compliance challenges. In today's global business environment, organizations must screen customers, vendors, and counterparties against U.S. Treasury sanctions lists. This is not optional—it's a legal requirement for financial institutions, payment processors, and many other businesses.

However, accessing and integrating OFAC data has traditionally been difficult. Existing solutions are often outdated, expensive, or require complex integration work. This proof-of-concept demonstrates that modern cloud architecture can solve these problems elegantly.

The Technical Challenge

The Problem

When we started working on compliance solutions, we encountered several persistent challenges:

Data Freshness: OFAC updates its sanctions list regularly, but many systems rely on manually updated data that quickly becomes stale.
Integration Complexity: Existing OFAC data sources require complex ETL processes, custom parsing, and significant infrastructure investment.
Scalability Issues: Traditional approaches struggle with traffic spikes. A compliance check that takes 5 seconds during normal load might take 30 seconds during peak times.
Cost: Building and maintaining compliance infrastructure is expensive. Servers must run 24/7, even during periods of low usage.
Developer Experience: Poor documentation and unintuitive APIs make integration time-consuming and error-prone.

Our Solution

The OFAC API demonstrates how modern serverless architecture solves these problems:

Automatic Updates: Scheduled functions fetch the latest OFAC data from the U.S. Treasury, ensuring data is always current.
Efficient Storage: OFAC data is stored in Netlify Blobs, providing fast, reliable access without managing databases.
Intelligent Search: Powered by Fuse.js, the search engine provides fuzzy matching that handles typos and partial names.
Infinite Scalability: Netlify Functions automatically scale from zero to thousands of concurrent requests without any configuration.
Pay-Per-Use Pricing: You only pay for the compute time you actually use, not for idle servers.
Developer-Friendly: Clear documentation, interactive API explorer, and code examples in multiple languages.

Architectural Decisions

Why Serverless?

We chose serverless architecture (Netlify Functions) for several reasons:

No Infrastructure Management: Deploy code, not servers. Netlify handles scaling, security, and maintenance.
Cost Efficiency: With traditional servers, you pay for capacity. With serverless, you pay for usage. For compliance APIs with variable traffic, this is significantly cheaper.
Automatic Scaling: Traffic spikes are handled automatically. No need to provision capacity in advance or worry about overload.
Built-in Security: Netlify provides DDoS protection, SSL/TLS, and security best practices out of the box.
Fast Deployment: Changes deploy instantly. No waiting for servers to start or configuration to propagate.

Why Netlify Blobs?

We chose Netlify Blobs for data storage because:

Integrated: No need to manage separate databases. Blobs integrate seamlessly with Netlify Functions.
Fast Access: Blobs are optimized for read-heavy workloads, perfect for compliance data that changes infrequently.
Automatic Compression: Data is automatically compressed, reducing storage costs and improving performance.
Simple API: The Blobs API is straightforward and requires minimal code.

Why Fuse.js for Search?

Fuse.js provides fuzzy search capabilities that are essential for compliance screening:

Typo Tolerance: Finds matches even with misspelled names.
Partial Matching: Works with incomplete names or aliases.
Relevance Scoring: Results are ranked by relevance, so the best matches appear first.
Lightweight: Runs entirely in JavaScript with no external dependencies.
Battle-Tested: Used by thousands of projects and proven in production.

Why Static Site Generation?

Documentation is generated from markdown because:

Version Control: Documentation lives in Git alongside code, making it easy to track changes.
Easy Updates: Markdown is simple to write and edit. No need to manage HTML directly.
Consistency: All pages use the same styling and branding automatically.
Performance: Static HTML is fast and requires no server-side processing.
Accessibility: Markdown-based documentation is inherently accessible and SEO-friendly.

Key Design Principles

1. Simplicity First

Every design decision prioritizes simplicity. The API has just four endpoints, each with a clear purpose. The codebase is straightforward and easy to understand.

2. Real-World Compliance

The API is designed for real compliance use cases. It handles the specific requirements of OFAC screening, including fuzzy matching, entity types, and detailed entity information.

3. Developer Experience

We believe developers should enjoy using an API. Clear documentation, interactive examples, and helpful error messages make integration straightforward.

4. Production Ready

This is not a toy project. The API includes comprehensive error handling, rate limiting, logging, and security best practices.

5. Cost Conscious

We designed the system to be cost-effective. Serverless architecture means you only pay for what you use, not for idle capacity.

6. Open and Transparent

The entire project is open source. You can see exactly how it works, audit the code, and contribute improvements.

Technical Highlights

Automated Data Updates

A scheduled function runs daily to fetch the latest OFAC data from the U.S. Treasury. The data is parsed, indexed, and stored in Netlify Blobs. This ensures your compliance data is always current.

Daily Schedule
    ↓
Fetch OFAC Data
    ↓
Parse & Index
    ↓
Store in Blobs
    ↓
API Ready

Fuzzy Search Engine

The search engine uses Fuse.js to provide intelligent matching:

Typo Tolerance: "Maduro" finds "Nicolás Maduro"
Partial Matching: "Maduro" finds "Nicolás Maduro Moros"
Relevance Scoring: Results ranked by match quality
Fast: Searches complete in milliseconds

Entity Details

When you retrieve an entity, you get comprehensive information:

Full name and aliases
Entity type (Individual, Entity, Aircraft, Vessel)
Date and place of birth (for individuals)
Addresses and contact information
Sanctions program information
Listing date and other metadata

Rate Limiting

The API implements intelligent rate limiting:

Search: 100 requests per minute per IP
Entity Details: 100 requests per minute per IP
Metadata: 1000 requests per minute per IP

Rate limits are generous enough for real-world use while preventing abuse.

Error Handling

Comprehensive error handling ensures reliability:

Validation: Invalid requests are rejected with clear error messages
Not Found: Missing entities return 404 with helpful information
Rate Limits: Rate limit responses include retry-after headers
Server Errors: Rare errors are logged and monitored

Lessons Learned

1. Serverless is Production-Ready

We initially had concerns about serverless for compliance APIs. In practice, Netlify Functions proved to be reliable, scalable, and cost-effective. The automatic scaling handles traffic spikes effortlessly.

2. Fuzzy Search is Essential

Early versions used exact matching. We quickly learned that compliance screening requires fuzzy matching. Users search for "Maduro" (typo), "Maduro" (partial), and "N. Maduro" (abbreviated). Fuzzy search handles all these cases.

3. Documentation Matters

The difference between a well-documented API and a poorly-documented one is enormous. Clear examples, interactive documentation, and helpful error messages dramatically improve developer experience.

4. Caching is Crucial

OFAC data changes infrequently (typically daily). Implementing caching on the client side dramatically reduces API calls and improves performance.

5. Monitoring is Essential

Even with serverless, monitoring is critical. We track API response times, error rates, and usage patterns to ensure the system performs well.

About devs.miami

devs.miami is a software engineering company founded by Robert Melrose, focused on building innovative solutions that solve real-world problems.

Our Approach

We believe in:

Clean Code: Code should be readable, maintainable, and well-tested.
Best Practices: We follow industry standards and proven architectural patterns.
User Focus: Every decision is made with the end user in mind.
Continuous Learning: Technology evolves rapidly. We stay current with the latest tools and techniques.
Open Source: We contribute to the community and believe in sharing knowledge.

Our Expertise

Cloud Architecture: Designing scalable, serverless systems on modern cloud platforms
API Development: Building robust, well-documented, production-ready APIs
Full-Stack Development: From backend to frontend, we deliver complete systems
Proof of Concepts: Demonstrating technical feasibility and best practices
Compliance & Security: Building systems that meet regulatory requirements

About Robert Melrose

Robert Melrose is a software engineer and founder with extensive experience in cloud architecture, API design, and full-stack development. His work demonstrates a commitment to clean code, best practices, and solving complex technical challenges with elegant solutions.

Background

Robert has spent over a decade building software systems that scale. He's worked on everything from real-time data processing to compliance systems to consumer applications. This diverse experience informs his approach to architecture and design.

Expertise

Serverless Architecture: AWS Lambda, Netlify Functions, and cloud-native design patterns
API Design: RESTful APIs, GraphQL, and API security
Full-Stack JavaScript/TypeScript: Node.js, React, and modern web development
Cloud Infrastructure: AWS, Netlify, and DevOps practices
Real-Time Data Processing: Handling high-volume data streams and complex transformations

Philosophy

Robert believes that great software is built on a foundation of:

Clear Requirements: Understanding the problem before building the solution
Thoughtful Design: Taking time to design systems that are maintainable and scalable
Quality Code: Writing code that is readable, tested, and follows best practices
User Focus: Always considering the end user's experience
Continuous Improvement: Learning from each project and applying those lessons to the next

Technology Stack

Backend

Runtime: Node.js
Hosting: Netlify Functions
Data Storage: Netlify Blobs
Search: Fuse.js
Data Source: U.S. Treasury OFAC API

Frontend

Static Site Generation: Markdown to HTML
API Documentation: Swagger UI / ReDoc
Styling: CSS with responsive design
Hosting: Netlify Static Hosting

Development

Language: TypeScript
Testing: Vitest
Version Control: Git/GitHub
CI/CD: Netlify Deploy Previews

Why Open Source?

We believe in transparency and community. The OFAC API is open source because:

Trust: You can audit the code and verify it does what we claim.
Community: Others can contribute improvements and learn from the implementation.
Sustainability: Open source projects benefit from community contributions and feedback.
Knowledge Sharing: We want to help others build better compliance systems.

The Future

This proof-of-concept demonstrates what's possible with modern cloud architecture. We're excited about the potential for:

Enhanced Search: Machine learning-based entity matching
Webhooks: Real-time notifications when entities are added or removed
Batch Processing: Screening large lists of entities efficiently
Multi-Jurisdiction: Supporting sanctions lists from other countries
Advanced Analytics: Insights into compliance screening patterns

Get Involved

Explore the Code

The entire project is open source on GitHub. You can:

Review the implementation
Understand the architecture
Contribute improvements
Fork and adapt for your needs

Use the API

Try the OFAC API in your application:

Read the Usage Guide for code examples
Explore the interactive API documentation
Integrate into your compliance workflow

Contact Us

Interested in consulting, custom development, or discussing your compliance challenges?

Website: devs.miami
Email: contact@devs.miami
GitHub: devs-miami

Related Resources

License

This project is provided as a proof-of-concept demonstration. See the repository for license details.

Acknowledgments

This project builds on the work of many talented developers and open source projects:

Netlify: For providing an excellent serverless platform
Fuse.js: For powerful fuzzy search capabilities
U.S. Treasury: For providing OFAC data
The Open Source Community: For countless tools and libraries that make this possible

Built with ❤️ by devs.miami