Cached Data During Long-Running Live SOS Searches: An Integration Guide for Lenders

Executive Summary: Cached data during long-running live SOS searches gives a lender business information before a slow state lookup finishes, but it does not make verification finish early. Cobalt can now include an optional cachedData array with an incomplete live-search response, while the same request remains open through retryId or callback delivery. The safe integration treats that array as a dated interim observation, limits it to lender-approved reversible work, and lets the completed live result close the verification state.

What Changed in a Long-Running Live SOS Search?

What did an incomplete response mean before this feature?

Cobalt's public Secretary of State API reference documents retryId for requests that take longer to complete and callbackUrl for asynchronous delivery.^[1] Its Help Center describes 202 + Incomplete as a processing state, not a failed lookup, and gives polling and webhook delivery as the two completion paths.^[2] The status guide makes the same distinction: Incomplete means the search is still in progress, while complete, no-results, fallback, and failed responses carry different meanings.^[3]

That behavior matches the HTTP standard. RFC 9110 defines 202 Accepted as a request accepted for processing whose work has not finished.^[4] The response can describe current status, but it is not a promise that processing will ultimately succeed.

What does `cachedData` add?

The new Cobalt response can include an available cached match beside retryId. The live state search continues in the background, and the completed live result remains final. A representative response has this shape:

{
  "status": "Incomplete",
  "statusCode": 202,
  "retryId": "72f06828-f593-40f1-9b4d-65a248e78869",
  "cachedData": [
    {
      "title": "FF PIZZA LLC",
      "status": "Active",
      "normalizedStatus": "Active",
      "stateOfSosRegistration": "CA",
      "updatedAt": 1788994658510
    }
  ]
}

The example is a field illustration, not a promise that every incomplete response will contain cachedData or that every cached match will contain every shown field. The integration still needs a cache-absent branch, schema validation, and the existing terminal-result path.

Treat the response as one open live request with an optional interim observation, not as one completed cached verification plus a second live verification.

How Should an Integration Parse the New Response?

Why should state be parsed before business fields?

A parser that branches on field presence will eventually misclassify the response. title and status can look like final verification data even when the top-level status remains incomplete. The correct order is top-level state, request identity, optional interim data, then terminal transition.

The minimum parser should make these distinctions:

• Incomplete with cached data. Preserve retryId, store the cached observation and updatedAt, keep live pending, and apply only approved interim rules.

• Incomplete without cached data. Preserve retryId, keep live pending, and do not create a business no-match.

• Complete with a live result. Close the pending state, store the final observation, and compare it with any interim record.

• Complete with no live match. Record the terminal no-match separately from an earlier cache miss.

• Failed or invalid retry. Route by the documented error meaning rather than reusing the last visible cached record as a substitute.^[3]

This separation also prevents a UI or rules service from interpreting normalizedStatus: Active as a completed verification flag. The field describes the cached record. The top-level state describes the request.

What should be stored from the first response?

Store enough to reconnect every later event to the same logical request. A customer-owned persistence model can include the application or verification ID, request inputs, retryId, response receipt time, cached payload, updatedAt, current state, and any reversible action taken. Do not overwrite the cached observation when live data arrives. A final record cannot explain what a reviewer saw earlier if the earlier bytes disappear.

Microsoft's asynchronous request-reply pattern uses the same underlying discipline: the accepted request receives an identifier, exposes a pending status, and later reaches a terminal resource.^[5] The exact Cobalt fields differ, but the integration principle is stable.

How Can a Lender Use the Interim Result Safely?

Which actions are reasonable candidates for interim use?

The answer depends on the lender's policy, not on the presence of the array. A useful first division is reversible preparation versus decision-bearing action. Reversible work can be refreshed or undone after live data arrives. Decision-bearing work closes a control or changes the applicant's outcome.

Possible lender-owned interim actions include:

• Prefill a review screen. Display legal name, state, and cached status with a visible cached label, record age, and live-pending banner.

• Prepare a comparison. Compare the submitted business name with the cached title without declaring a final match.

• Create an exception shell. Open a case record that will receive the final live observation or a mismatch review.

• Route nonfinal tasks. Start document organization or assign a reviewer while keeping the SOS verification task open.

• Suppress duplicate entry. Reuse the cached fields for temporary display rather than asking staff to type the same information, provided the screen does not imply final verification.

These are proposed patterns, not observed Cobalt customer workflows. A lender can permit fewer of them or ignore the cached record entirely.

Which actions should remain behind the live-result gate?

The approved feature evidence does not support using cachedData by itself to mark SOS verification complete, approve or decline a file, fund a transaction, or make an adverse inference. Cached records may not reflect the latest state information, and Cobalt says cache age should be judged from record timestamps rather than assumed from availability. Its Help Center says cached records do not auto-expire and gives createdAt and updatedAt so the consumer can evaluate recency for its own use case.^[6]

This design complements, rather than replaces, Cobalt's existing verification waterfall guidance. The waterfall chooses which lookup mode to run. The new response behavior answers a different question: what can the workflow do when it already requested live data and useful cached information arrives before completion?

How Should `updatedAt` Control Interim Use?

Why is record age different from an acceptable-age rule?

updatedAt supplies an observation about the cached record. It does not supply the lender's policy. Cobalt's public cache documentation says most states are refreshed monthly while some states update less frequently, and it directs users back to the timestamp on the actual response.^[7] That makes a universal monthly rule unsafe: a general cadence does not prove the age of the record in hand.

A lender-owned age gate should ask:

• What action is proposed? Temporary display carries different consequences from final verification.

• Can the action be reversed? If live data changes the record, can the workflow correct the earlier step without harming the applicant?

• Which jurisdiction is involved? State access, field availability, and refresh patterns vary.

• Is updatedAt present and parseable? Missing or invalid age evidence should enter the wait-for-live path.

• What happens when the rule fails? The default should be live pending or review, not a silent pass.

RFC 9111 is useful context because it separates the age of a stored response from its freshness lifetime.^[8] The lender's policy supplies the business equivalent of that lifetime for each permitted action.

How should source and age appear to a reviewer?

Cobalt's Help Center says clients can use messages and timestamps to distinguish live from cached information.^[9] A reviewer screen should not force the operator to inspect raw JSON to discover that distinction. Show source type, calculated age, live-pending state, and the expected next event together.

The interface may use compact language such as Cached SOS record, Updated 12 days ago, and Live search pending. Those labels are examples, not Cobalt product screens or legally required disclosures.

What Happens When No Cached Match Is Available?

Why is cache absence not a business no-match?

The new field is conditional. When a cached match is unavailable, the integration should continue through the existing retry or callback path. Cobalt's cache-miss guidance is explicit that a miss means the entity was not found in cache, not that it does not exist at the state.^[10]

That distinction prevents a temporary data-availability condition from becoming a false negative. The screen can say Live search pending, no interim cached match, while the rules engine preserves the same open request.

What failure modes should remain separate?

No cached match, invalid retryId, terminal no live match, state-source error, and completed result with alternatives are different states. The public status guide provides distinct meanings for incomplete, no-results, fallback, failed, and invalid-retry responses.^[3] Combining them under one no data flag removes the information the integration needs to choose the next action.

For resilience planning beyond this feature, Cobalt's state-portal outage guide explains why state timing and availability must be handled per source rather than as one global service condition.

What If Cached and Live Matches Differ?

Why can two search paths return different businesses?

Cobalt's feature brief identifies different search and ranking behavior as one cause. Cached matching runs against Cobalt's stored dataset, while each state portal implements its own search logic. A different top match does not, by itself, prove that either result is wrong.

Current Cobalt guidance also treats confidence as a review signal rather than an absolute identity verdict. Its Help Center gives practical bands in which higher scores may qualify for automated handling and middle scores route to review, while other signals can still matter.^[11] The matched-field page adds that legal name, assumed names, and the input that triggered the match can be distinct pieces of context.^[12]

What belongs in a neutral review queue?

Preserve the original query, state, cached title and status, updatedAt, final live result, stable identifiers where returned, and reviewer disposition. Use neutral labels such as match variance or identity review. Do not convert different ranking into a fraud flag.

If the interim record affected a screen or reversible task, retain that history after live completion. Cobalt's existing article on automated audit trails makes the broader point that source, time, request identity, result, and handling belong together in a defensible operational record.

How Should Polling and Webhooks Handle the Interim State?

How can both transports update one request safely?

Polling and callbacks should update the same logical request. Cobalt's Help Center recommends callbacks for batch or high-volume flows and supports retryId polling when an inbound endpoint is unavailable.^[2] Its batch guidance also recommends backoff and idempotency because state timing varies.^[13]

AWS describes the same retry constraint in general terms: operations used with backoff should be idempotent, or repeated calls can create partial or duplicated effects.^[14] For webhook consumers, the Standard Webhooks specification recommends unique event identifiers and idempotency handling to prevent a repeated delivery from being processed twice.^[15]

A lender-owned state machine can use these states:

• Accepted. Request context and lender request key exist.

• Live pending. The state lookup is open.

• Interim data available. Cached fields are stored and optionally displayed under policy.

• Live complete. The final response is stored and the pending gate closes.

• Review required. Final and interim matches differ materially or another exception needs a person.

The names are implementation recommendations, not a Cobalt webhook contract. The approved sources do not promise ordered or exactly-once delivery.

What should the integration log?

OWASP recommends that application logs preserve the when, where, who, and what of an event, including result status, reason, HTTP status, and the response or action taken.^[16] NIST frames log management as the process for generating, transmitting, storing, accessing, and disposing of event records for operational and investigative use.^[17]

For this feature, that means logging the lender request key, submitted query, state, top-level response status, retryId or callback request identity, cached payload and updatedAt, receipt time, final live payload, comparison outcome, and any workflow disposition. Retention and access rules remain with the lender.

How Does Cobalt Fit Without Owning the Lending Decision?

What alternatives should a lender compare?

A lender can ask staff to use state portals directly, buy a stored business dataset, use a broad KYB workflow platform, or integrate a primary-source SOS API. Those approaches differ in manual effort, source timing, and how evidence reaches the underwriting system. The relevant integration question is not which category sounds most advanced. It is which path exposes source, age, process state, and a recoverable final result in the lender's own workflow.

Cobalt's public API already supports live and cached modes, retryId, callback delivery, optional screenshots, and timestamp fields.^[1] Cobalt's screenshot guidance treats screenshots as a distinct source artifact rather than a property of every cached record.^[18] The new cachedData behavior connects those capabilities during a slow live request. It does not change Cobalt's role into a credit-decision engine.

What is the smallest safe first release?

Ship the state distinction before elaborate automation. Parse incomplete versus complete, preserve one request identity, store the interim record without overwriting it, calculate age, show pending status, and keep one final transition. Add permitted interim actions only after policy owners name them.

If your team is evaluating how Cobalt's SOS API can fit a lender-owned verification workflow, schedule a demo to review the live, cached, retry, and callback paths with your integration team.

This feature is valuable because it creates optionality during a slow state search. The control that makes the optionality useful is equally simple: cached information can arrive early, but finality still arrives with the completed live result.