SOS Lookup API: Complete curl Examples for Every Use Case

If you are building a compliance workflow, onboarding pipeline, or KYB verification system in the United States, you already know that Secretary of State (SOS) business entity data is the foundation of everything. Before you approve a vendor, extend credit, open a business bank account, or process a large wire transfer, you need to confirm that the company you are dealing with actually exists, is in good standing, and has a verifiable registered agent on file. Doing this manually — navigating fifty different state portals with inconsistent interfaces — is not scalable. A single, well-designed SOS lookup API curl request solves the problem in milliseconds.

This guide delivers exactly what developers, compliance engineers, and fintech architects need: working curl examples for every realistic use case, grounded in the regulatory context that makes this data legally significant. All examples use the OpenSOSData API, which covers all 50 US states plus Washington D.C., Puerto Rico, and the U.S. Virgin Islands — more than 23 million business entities in a single endpoint.

Why SOS Entity Data Is Legally Critical in the United States

Three regulatory frameworks make business entity verification non-negotiable for US financial institutions, fintechs, and regulated businesses.

FinCEN Beneficial Ownership (BOI) and the Corporate Transparency Act

The Corporate Transparency Act, enforced by FinCEN, requires most US companies to report their beneficial owners. Verifying that a business entity is properly registered with its state of formation is a prerequisite for BOI analysis. If a company claims to be a Delaware LLC but has no active filing on record, the entire ownership chain is suspect.

Bank Secrecy Act (BSA) and KYB Due Diligence

Under BSA rules, financial institutions must apply Customer Due Diligence (CDD) and Know Your Business (KYB) procedures to commercial customers. The OCC and FFIEC examination guidelines explicitly expect examiners to see documentary evidence that a business is legitimately formed and in good standing. An automated SOS lookup creates a durable, timestamped record of that verification.

OFAC Sanctions and Entity Name Matching

OFAC screening is more effective when you have the canonical, state-registered entity name rather than a trade name or customer-provided string. SOS data gives you the legal name exactly as it appears on the state record, making fuzzy matching against the SDN list far more reliable.

OpenSOSData API at a Glance

The OpenSOSData API exposes a single POST endpoint: https://api.opensosdata.com/v1/lookup. Every response returns entity name, entity type, entity ID, status, formation date, registered agent name, and registered agent address. Pricing is pay-as-you-go with no monthly minimums — live lookups start at $0.10 each and drop to as low as $0.0314 at volume; cached lookups start at $0.01 and drop to as low as $0.00314 at volume. Full API specifications are available at opensosdata.com/openapi.yaml.

Authentication: Getting Your API Key

Sign up at app.opensosdata.com to receive your API key. Pass it as a Bearer token in every request header. The examples below all assume you have exported your key to an environment variable for security:

# Set your API key as an environment variable — never hard-code secrets in scripts
export SOSDATA_API_KEY="your_api_key_here"

Complete curl Examples for Every Use Case

Use Case 1: Basic Entity Lookup by Name and State

The most common request pattern: you have a business name and a state, and you need to confirm the entity exists and is active.

curl -X POST https://api.opensosdata.com/v1/lookup \
  -H "Authorization: Bearer $SOSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Financial Services LLC",
    "state": "DE"
  }'
# Returns: entity name, type (LLC/Corp/etc.), status, formation date,
# registered agent name, and registered agent address

Use Case 2: Live Lookup to Force a Fresh State Pull

For high-stakes onboarding decisions — opening a business deposit account, approving a large ACH batch — you want real-time data directly from the state registry, not a cached result. Add the live flag:

curl -X POST https://api.opensosdata.com/v1/lookup \
  -H "Authorization: Bearer $SOSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Apex Capital Group Inc",
    "state": "CA",
    "live": true
  }'
# live: true forces a real-time pull from the California SOS
# Billed at the live rate ($0.10 standard, volume discounts available)

Use Case 3: Cached Lookup for High-Volume Batch Screening

When you are screening hundreds or thousands of vendor records for periodic re-verification, cached results keep costs low while still delivering structured state data. Omit the live flag or set it to false:

curl -X POST https://api.opensosdata.com/v1/lookup \
  -H "Authorization: Bearer $SOSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Riverstone Logistics Corp",
    "state": "TX",
    "live": false
  }'
# Cached lookup — as low as $0.00314 per call at high volume
# Ideal for batch vendor re-verification and BSA periodic review

Use Case 4: Multi-State Lookup in a Shell Loop

Some businesses are registered in multiple states. This shell script iterates over an array of states and checks each one — useful for identifying foreign qualifications in a KYB investigation:

#!/bin/bash
# Check entity registration across multiple states
# Useful for KYB investigations where a company may have foreign qualifications

ENTITY_NAME="Summit Holdings LLC"
STATES=("DE" "NY" "CA" "TX" "FL")

for STATE in "${STATES[@]}"; do
  echo "--- Checking state: $STATE ---"
  curl -s -X POST https://api.opensosdata.com/v1/lookup \
    -H "Authorization: Bearer $SOSDATA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"business_name\": \"$ENTITY_NAME\",
      \"state\": \"$STATE\"
    }" | python3 -m json.tool
  echo ""
done

Use Case 5: Parsing the Response with jq for Downstream Automation

Integrating SOS data into a CI/CD pipeline, a SIEM alert, or a case management system? Use jq to extract only the fields you need:

curl -s -X POST https://api.opensosdata.com/v1/lookup \
  -H "Authorization: Bearer $SOSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Northgate Trading LLC",
    "state": "IL"
  }' | jq '{
    name: .entity_name,
    status: .status,
    formed: .formation_date,
    agent: .registered_agent_name
  }'
# Output is a clean JSON object ready for ingestion by your case management tool

Use Case 6: Error Handling in a Production Script

Production scripts must handle API errors gracefully. This pattern checks the HTTP status code and logs failures for compliance audit trails:

#!/bin/bash
# Production-grade SOS lookup with error handling and audit logging

RESPONSE=$(curl -s -w "\n%{http_code}" -X POST https://api.opensosdata.com/v1/lookup \
  -H "Authorization: Bearer $SOSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Clearwater Ventures Inc",
    "state": "FL"
  }')

HTTP_STATUS=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$HTTP_STATUS" -eq 200 ]; then
  echo "SUCCESS: $(echo $BODY | jq -r '.status')"
  # Write to compliance audit log
  echo "$(date -u),Clearwater Ventures Inc,FL,$(echo $BODY | jq -r '.status')" >> sos_audit.csv
else
  # Log failure for remediation — required for BSA audit trail integrity
  echo "ERROR: HTTP $HTTP_STATUS — $(echo $BODY | jq -r '.message')"
  echo "$(date -u),Clearwater Ventures Inc,FL,LOOKUP_FAILED,$HTTP_STATUS" >> sos_audit_errors.csv
fi

Use Case 7: Webhook-Ready Output for Real-Time Onboarding Pipelines

If your onboarding system triggers SOS checks via webhook events, you can wrap the curl call inside a function that posts results to your internal endpoint:

#!/bin/bash
# Retrieve SOS data and forward structured result to internal onboarding webhook

SOS_DATA=$(curl -s -X POST https://api.opensosdata.com/v1/lookup \
  -H "Authorization: Bearer $SOSDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Pacific Rim Exports LLC",
    "state": "WA",
    "live": true
  }')

# Forward the SOS result to your internal onboarding orchestration endpoint
curl -s -X POST https://internal.yourcompany.com/kyb/sos-result \
  -H "Content-Type: application/json" \
  -d "$SOS_DATA"

echo "SOS result forwarded to onboarding pipeline."

Lookup Type Comparison: Live vs. Cached

Integrating SOS Lookups Into Your KYB Workflow

A typical automated KYB pipeline for a US fintech or bank might look like this: collect business information at onboarding → fire a live SOS lookup to confirm legal existence and good standing → extract the registered agent address for cross-reference → run the canonical entity name through OFAC/SDN screening → collect beneficial ownership data per FinCEN CDD rules → store all results with timestamps in your case management system. The SOS lookup is step two, and every downstream step depends on getting it right. The OpenSOSData OpenAPI specification makes it straightforward to generate client SDKs in any language so curl commands can be promoted to production service calls with minimal effort.

Frequently Asked Questions

Conclusion

SOS lookup API curl examples are not just developer conveniences — they are the building blocks of defensible, auditable KYB compliance programs. Whether you are confirming a single Delaware LLC before wiring funds, running a nightly batch re-verification of your entire vendor database, or building a real-time onboarding pipeline that satisfies BSA and FinCEN examiners, the patterns in this guide give you a production-ready starting point. Sign up at app.opensosdata.com, grab your API key, and run your first lookup in under five minutes.