API Integration Basics

Home Blog Documentation

API Integration Basics

Which fields are required for a Secretary of State lookup?

Can I integrate Cobalt’s API into my web application or platform?

How should we handle long-running SOS searches? What does “Incomplete” mean?

Can I search all 50 states at once?

Can we control which fields are returned in Cobalt’s API response?

Can we simplify reports for clients so they don’t see unnecessary details?

Can we change the names of fields returned by the API?

Can I search by a principal or owner’s name instead of the business name?

Can we use Cobalt to return Secretary of State screenshots instead of having staff capture them manually?

Can I specify the type of entity for an OFAC check (person vs. business)?

Testing & Trialing the API

How can I test the API before choosing a plan?

Do you provide a sandbox or test environment for API integration?

How long is the free trial API key valid? Can it be extended?

How many test calls are included in the trial?

Any guidance for large batch runs?

Any practical steps to boost NY batch hit rates?

How should we validate batch results when inputs are messy?

For batch work, should we track the “actual name searched” separately from the raw client input?

Can Cobalt’s API be used to check business licenses (e.g., contractors, trucking, liquor)?

Can I search by officer or address fields?

Do I get a separate API key for testing or trials?

Client Education & Enablement

How do I help my international team understand U.S. tax ID limitations?

Can internal client-facing teams outside the U.S. review the TIN checker before rollout?

Can Cobalt’s platform support non-technical users who can’t integrate an API?

Matching & Confidence

How does Cobalt determine which record is the best match?

What’s a practical NY “waterfall” we can implement on our side?

What “waterfall” name-matching strategy works well for tight state searches (e.g., NY)?

How should we handle generic names?

If we have an entity suffix (e.g., “LLC”), should we include it in the query?

How does string length affect confidence scores?

Why did I see confidenceLevel = 1.0 when the names didn’t match?

How does the API handle messy or inconsistent entity names?

Do you treat “&” the same as “and”?

Why did shortening the name to a core form help?

How should we combine confidenceLevel with address signals?

We got a low-confidence result that shared the ZIP but not the name—why?

Fields (name/score/URL)? Can we get more?

Can we see more than just the top match when several are close? How should we use the alternatives list?

Will Cobalt’s API detect entity name changes (e.g., Pizza Inc → Pizza LLC)?

How does the API handle name disambiguation (e.g., punctuation, suffix differences)?

Do you provide DBA (fictitious name) information?

Can Cobalt return multiple possible matches with confidence scores?

How does Cobalt’s confidence score affect underwriting?

What confidence thresholds should we use?

Address & ZIP Handling

Why didn’t some results include address fields we expected?

We have extra context that you don’t—can we apply it to batch disambiguation?

Can we rely on address fields to help when names are imperfect?

Why doesn’t possibleAlternatives always include addresses?

If I include a ZIP code but it doesn’t match, what happens?

Does the system fall back to ignoring the ZIP code if no match is found?

New York feels stricter—plural vs. singular differences killed some results. Why?

Our client names often include location text. Should we clean that before searching?

Can we pass city/ZIP/street or “search by address” to improve matches? Will the API adjust its waterfall?

Why are responses slower when filtering by ZIP?

How does ZIP matching work?

DBAs / Fictitious or Assumed Names

Why did a fictitious name return ahead of the actual entity?

General Secretary of State (SOS) Behavior & Access

What is the Secretary of State API used for?

Does the API support all entity types?

What’s the difference between an entity name and a DBA?

How does the API handle fictitious/assumed business names?

Does the API work in states that require paid access, like Texas?

Do all states provide real-time digital access to business registration data?

Do you provide registered agent information?

Does the API support international entities?

Do you pull data directly from Secretary of State websites, or do you rely on third-party databases?

Are contractor license portals unified nationwide?

Do contractor license number formats differ by state?

How does contractor job verification compare to SOS business verification?

Are there states that charge extra to access business status information?

Screenshots & Audit Artifacts

Are screenshots included with every lookup?

Do regulators accept screenshots in place of official filings?

Can clients customize screenshots to include specific tabs?

Are screenshots and official documents both available?

Can I lock in screenshot availability under my contract?

Data Caching & Freshness

How long is cached data stored or considered valid?

When is cached data refreshed or updated?

Does Cobalt provide real-time Secretary of State data or is it cached?

Are results live or from a cache by default?

How current is cached data and how much coverage does it have?

What happens if a cached lookup doesn’t find a record?

How can I tell whether a response was live or cached?

Can I choose cache-only or live-only?

Can I choose faster responses over absolute freshness?

Are results truly real-time to our app flow?

As we expand usage, do larger batch runs still return live data?

How often is cached data updated for different states?

Performance, Batch & Rate Limits

What happens if we accidentally send a very large burst of requests?

Does the 429 come from the app or the endpoint?

Can Cobalt retrieve live data from all 50 states + DC?

What’s the typical batch processing time for ~100 businesses?

Why do some states take longer or fail more often?

Why are some Secretary of State requests slow or inconsistent, and how long do results take?

What happens if a lookup takes too long to return a response? How do retryId and callbackUrl work?

If I provide entity name, state, and registration number in a batch upload, will the API only check those exact entities?

Can we toggle between “full verification” and “state-specific” audits?

Can I get a list of similar names returned by the API?

What happens if I never pull results for a retryId? Will I still be billed?

Do we get billed if the state site is down or the request fails?

How can we identify if a failure is due to the state vs. Cobalt?

Are unsuccessful lookups free, or are they billed?

Should I query cached results first or always use live data?

Are we billed for every API call, even if there’s no match?

Why did we get billed for Incomplete responses?

What is a typical usage pattern Cobalt can support?

Why are Oregon contractor license lookups more difficult than other states?

Datasets & State Field Coverage

What court and UCC data is currently available?

Which states don’t support UCC data or the screenshot feature?

Will UCC coverage expand?

What API services does Cobalt offer and what’s their coverage?

Does Cobalt provide any guidance on which states return which fields?

Does Cobalt offer additional checks beyond SOS and TIN/EIN?

What should I do if I find a record on a Secretary of State site that Cobalt doesn’t return?

Does Cobalt return UCC lien or court judgment data like Experian/Lexis?

Can contractor licenses be searched by name instead of license number?

Does Cobalt support contractor license verification in Oregon?

How does Cobalt decide which states to support first for contractor license coverage?

Can Cobalt provide contractor job-level data?

Does Cobalt support “notice of commencement” filings?

Where does Cobalt get OFAC data from?

Does the OFAC check cover Canada or other countries?

Field Behavior & Data Interpretation

What does the filingDate field represent?

Will the payload distinguish what exactly matched ?

Can filingDate be used to calculate company tenure?

Will there be multiple filing dates per business?

What does the confidenceLevel field represent?

How is confidenceLevel calculated?

Does the confidence score look at the whole result set or just one record?

What is aiConfidenceLevel and should we use it?

What threshold should we use to accept a match?

What’s the difference between agent and officers?

What does sosId represent?

What do “Document 1, 2, 3 …” represent in the response?

Which document fields matter for change history?

What values appear in documents[].title?

Are document URLs time-limited?

Why is entityType sometimes missing?

Does the API identify foreign corporations?

How do I retrieve a company’s date of incorporation/formation?

Does the API return the most recent filing date?

Why does Colorado show a “Periodic Report Due” in the documents array?

Why do entity types sometimes appear differently?

What happens if there is no OFAC match?

Can OFAC return multiple results for the same input?

What does an “empty” or “no match” response look like?

Will TIN or SSN checks return partial results or errors?

Verification Logic & Use Cases

What can I validate and what comes back from an SOS search?

Can I use Cobalt data to auto-correct application inputs?

Can Cobalt data flag a mismatch between legal address and state of registration?

What does a typical KYB workflow look like?

Can Cobalt be used in manual review workflows?

Does Cobalt support MCA/underwriting platforms?

Can I monitor my vendor base for changes?

Does the API tell me if a business name is available?

How should we interpret “no results found”?

Can registered-agent info help confirm relationships when names differ?

How should we treat officer/ownership info from SOS?

Can SOS data replace the need for a good standing certificate?

Can Cobalt check whether an entity is in good standing during onboarding?

Can Cobalt help automate SOS verification we currently do manually?

At what stage of underwriting is SOS data most valuable?

Why is contractor licensing verification important?

Can contractor licensing checks be integrated into the same workflow as SOS verification?

How should contractor license data be collected before sending to the API?

How should we submit contractor license information to Cobalt?

Why does Cobalt weigh state usage volume when adding new datasets?

What type of contractor-related data are clients requesting beyond license checks?

Why would a client want to see all jobs a contractor is working on?

TIN/EIN Verification & Behavior

Can we search by EIN, or only verify it?

Why do multiple business names show a match for the same EIN?

Does the TIN Match response include the date it was cached or verified?

Does Cobalt modify or enrich the business name or TIN before sending to the IRS?

Do legal endings matter for name matching in TIN verification?

Can I preview the TIN checker or share a demonstration with internal stakeholders?

Can Cobalt help detect fraud signals during vendor onboarding?

What does the number represent from the irsCode field returned?

Where can I find the API documentation?

Can we retrieve EINs from state records via the SOS API?

Is the IRS TIN/EIN check one-to-one on business name?

Can I search SOS records using Business Name + TIN?

Can I use EIN to narrow SOS searches?

Does Cobalt provide full tax return data or just EIN match results?

What does Cobalt’s TIN verification do?

Can I search SOS records by TIN or EIN?

Does Cobalt support Social Security Number (SSN) checks as part of TIN verification?

How many credits does a TIN verification cost?

Volume & Pricing Flexibility

Do unused credits roll over if we don’t use our full monthly plan?

Can pricing be adjusted if our volume increases?

Can we use Cobalt’s data for marketing purposes?

What does Cobalt’s pricing structure look like?

Is there a trial or pilot option before committing to a plan?

Can we explore pricing tiers for high-volume onboarding?

Can Cobalt’s pricing scale with our usage over time?

Can we lock in pricing to avoid changes later?

If new features are released, are they included in our plan?

Can we scale usage to higher volumes over time?

Are volume discounts available as usage increases?

If we commit to a longer contract, do we get price stability?

Will new features and improvements be included as we grow?

How should we think about using Cobalt across multiple product lines or channels?

Can my plan handle very high lookup volumes, including OFAC?

Can my plan scale as we add services like TIN or contractor license checks?

Billing, Usage & Credits

How can I confirm our next billing date?

Is the request count in the portal accurate and up to date?

Does the usage count reset every month?

What happens if we exceed our base plan usage?

What if we’re on a yearly plan and go over the monthly ceiling?

Are there cost implications for using retries versus callbacks?

What happens when I exceed my trial usage limit?

Can we move from trial to pay-as-you-go invoicing?

How do I update the credit card on file?

Where can I find my API key?

Are we charged for errors or clearly incorrect results?

How are overages handled if we exceed our plan?

Do credits pool across multiple API keys for our team?

How are credits applied across different products?

Are we billed for every API call, even if there’s no match?

Do annual contracts auto-renew?

Can we upgrade plans mid-term if usage is higher than expected?

How are OFAC checks billed?

How are credits used across SOS, TIN, and other services?

Client Procurement & Invoicing

Can I pay for the pilot or subscription via credit card?

Can Cobalt provide a signed pricing quote for internal review?

Do you support an MSA or custom contract, or is it click-through Terms only?

How do we indicate our selected pricing tier in the agreement?

Can we change tiers mid-contract?

How does Cobalt handle contracts and invoicing?

Security & Data Residency

Does Cobalt operate fully within the U.S.?

Integrations & Connectors

Is Salesforce integration supported?

Will our existing integrations automatically benefit from future platform improvements?

Home