API Integration Guide: Adding OFAC Screening to Your Application

Why Use the API?

If you are building an application that needs to screen names against OFAC sanctions lists, our REST API lets you integrate screening directly into your workflow. Instead of switching to a separate tool, your application can check names automatically as part of your onboarding, transaction processing, or any other business process. The API answers synchronously in a single request, so it fits inline in a signup or checkout flow rather than needing a queue.

Getting Started

To use the OFACScreen API, you need:

1. An OFACScreen account. The REST API is on every plan, including the 14-day trial, so you can integrate before you pay.
2. Your API key, which you can find in your account settings at ofacscreen.com.

All API requests are made over HTTPS. We do not accept unencrypted HTTP requests. The base URL for the API is:

https://ofacscreen.com/api/v1/

Authentication

Authenticate your API requests by including your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep your API key secure. Do not embed it in client-side code or commit it to version control. Use environment variables or a secrets manager.

Screening a Name

To screen a single name, send a POST request to the screening endpoint:

Endpoint: POST /api/v1/screen/

Request body:

{
  "name": "John Smith",
  "type": "individual",
  "threshold": 0.3
}

The type field is optional and can be "individual", "entity", "vessel", or "aircraft". The threshold field is the minimum trigram similarity score for a returned match, a number between 0.0 and 1.0. It defaults to 0.3, which is deliberately loose so that weak matches surface and you decide rather than the tool deciding silently. Higher values mean stricter matching.

Example: Python

import requests

response = requests.post(
    "https://ofacscreen.com/api/v1/screen/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "John Smith",
        "type": "individual",
        "threshold": 0.3
    }
)

results = response.json()
for match in results["matches"]:
    print(f"{match['name']} - Score: {match['score_pct']}%")

Example: JavaScript (Node.js)

const response = await fetch("https://ofacscreen.com/api/v1/screen/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "John Smith",
    type: "individual",
    threshold: 0.3
  })
});

const results = await response.json();
results.matches.forEach(match => {
  console.log(`${match.name} - Score: ${match.score_pct}%`);
});

Example: cURL

curl -X POST https://ofacscreen.com/api/v1/screen/   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"name": "John Smith", "type": "individual", "threshold": 0.3}'

Screening Several Names in One Request

To screen up to 100 names in a single call, POST an array to /api/v1/screen/batch/ with a names field instead of name. Each name in the array counts against your monthly search allowance, and the request is refused with a 429 if the allowance cannot cover the whole array.

Response Format

The API returns a JSON response with the following structure:

{
  "query": "John Smith",
  "matches": [
    {
      "id": 12345,
      "name": "John Michael SMITH",
      "entry_type": "individual",
      "list_code": "OFAC_SDN",
      "list_name": "OFAC Specially Designated Nationals (SDN)",
      "program": "SDGT",
      "remarks": "DOB 15 Mar 1970; POB London, UK",
      "score": 0.923,
      "score_pct": 92,
      "match_level": "high",
      "matched_alias": null,
      "aliases": ["John M. SMITH"],
      "addresses": [{"city": "London", "country": "United Kingdom"}],
      "identifications": [{"type": "Passport", "number": "123456789"}]
    }
  ],
  "total_matches": 1,
  "screened_at": "2026-01-15T10:30:00+00:00"
}

score is the raw trigram similarity between 0.0 and 1.0; score_pct is the same number rounded to a percentage, and match_level is "high" at 0.8 and above, "medium" from 0.5, "low" below that. matched_alias is filled in when the hit came from a recorded alias rather than the primary name.

If there are no matches, the matches array will be empty and total_matches will be 0. A clean result does not mean you should skip documentation. Log the result regardless.

Error Handling

The API uses standard HTTP status codes:

• 200: Success. Results are in the response body.
• 400: Bad request. Check your request body for missing or invalid fields.
• 401: Unauthorized. Your API key is missing or invalid.
• 429: Rate limit exceeded. Slow down your requests and try again.
• 500: Server error. Contact support if this persists.

Always check the status code before processing the response. Implement retry logic with exponential backoff for 429 and 500 errors.

Rate Limits

API access is on every plan, and API calls draw on the same monthly search allowance as searches run in the dashboard: 25 on the 14-day trial, 1,000 on Starter, 2,000 on Professional, 10,000 on Business. Enterprise is negotiated. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining headers so you can see what is left without asking.

Best Practices

• Log every screening. Store the request, response, and timestamp for your compliance records.
• Handle errors gracefully. If the API is unavailable, queue the screening for retry rather than skipping it.
• Record the threshold you used. The default of 0.3 is loose on purpose. If you raise it, write down the number and the reason, because an examiner will ask how sensitive your search was.
• Screen before, not after. Integrate screening before you process a transaction or onboard a customer, not as an afterthought.

Full API documentation is available at ofacscreen.com/docs. If you have questions about integration, contact our support team.