How Lender Platforms Should Filter and Store Secretary of State API Responses

Executive Summary: A lender platform can ingest an SOS response successfully and still build a poor audit trail if it drops source context, stores temporary links as permanent evidence, or mixes raw data with a credit disposition. The practical question for CTO; Head of Engineering is which SOS response fields belong in durable storage, reviewer views, analytics, and short-lived evidence handling. A defensible workflow keeps the submitted identity, source record, normalized fields, and lender decision separate.

Why Does This SOS Decision Fail in Production?

What gets collapsed too early?

Teams often overwrite the application with the first plausible registry result, convert varied state terms into one status, and save only the fields visible to the reviewer. That makes the file fast to scan but hard to reproduce. Cobalt's automation guide shows how one API route can standardize state lookups, while the state source remains the underlying authority.^[2]

What idea should govern the design?

Store the raw response and source context immutably, promote only decision-relevant normalized fields into the loan system, archive permitted temporary evidence promptly, and keep customer interpretation in a separate record. The system should be able to show what the applicant submitted, what the state returned, how the platform normalized it, and which customer rule produced the disposition.

The source record answers a state-registry question. The lender still owns the identity join, policy, exception, and credit action.

What Does the Secretary of State Source Actually Support?

Which product fields are relevant?

The current response can include requestId, legal title, filing date, state of formation, status, entity type, agent and officer data where published, addresses, state source URL, optional screenshot URL, confidence, and alternatives. Cobalt's current field reference explains that state availability varies and that the same normalized schema may be populated differently across jurisdictions.^[3]

Which conclusions stay outside the source?

States publish different fields. Screenshot URLs are temporary, officer availability varies, response times vary, and a normalized field does not replace the raw jurisdiction value or customer policy. Delaware, for example, says its free entity search returns formation date and agent information but does not itself provide entity status; status is a separate service.^[10] A workflow must not assume every state's search exposes the same legal meaning.

Which Storage Layers Should Hold an SOS Response?

What belongs in the immutable source record?

Retain the exact request parameters, request identifier, response status, retrieval time, raw result, possible alternatives, state source URL, and product or schema version available to the customer. Confirm the live contract in Cobalt's API documentation.^[1] Restrict sensitive fields and set retention under the lender's policy. This record supports replay and investigation when a normalized value changes later.

What belongs in the loan or onboarding record?

Promote the selected entity ID, legal title, raw and normalized status, filing date, formation jurisdiction, entity type, addresses, and the current decision-relevant agent or officer fields. Attach the source-record key rather than copying every nested field into analyst screens. Cobalt's field reference explains why availability and shape vary by state.^[3]

How Should Temporary Screenshots and Source Links Be Handled?

Why is a screenshot URL not an archive?

Cobalt's current product authority says optional screenshot links are temporary and should be downloaded by the customer within the available period. Store the permitted image in the customer's controlled evidence location, record its retrieval time and digest, and keep the originating request ID. Do not promise a permanent vendor URL.

What should the reviewer see?

Show the submitted business, selected legal entity, match confidence, alternatives, source and check time, state value and normalized value, material fields, and customer disposition. Hide fields that are not needed for the review, but leave a controlled path to the raw evidence. A reviewer should be able to tell what Cobalt returned and what the lender concluded.

{
  "source_record_id": "internal immutable key",
  "selected_entity_id": "state identifier",
  "raw_status": "value returned by jurisdiction",
  "normalized_status": "customer display value",
  "disposition": "separate lender-owned result"
}

This is a customer storage model, not a claim about undocumented Cobalt webhook or endpoint fields.

What Step-by-Step Workflow Should the Lender Use?

Which actions happen before a decision?

• Retain the raw response under restricted access. Record the source, owner, and disposition required at this step.

• Persist request and source identifiers. Record the source, owner, and disposition required at this step.

• Store the exact query and jurisdiction. Record the source, owner, and disposition required at this step.

• Promote stable normalized fields into the account model. Record the source, owner, and disposition required at this step.

• Keep raw state values beside normalized values. Record the source, owner, and disposition required at this step.

• Download permitted screenshots before temporary URLs expire. Record the source, owner, and disposition required at this step.

• Separate source result from reviewer disposition. Record the source, owner, and disposition required at this step.

This sequence should run under a versioned policy. The API can retrieve and normalize data, but only the customer system knows the application, account, exposure, product requirements, and authorized exception.

When should the route stop for review?

Stop when the jurisdiction is unknown, the record cannot be uniquely resolved, a required field is unavailable, the raw state value conflicts with the normalized result, the source is unavailable, or the evidence does not connect the record to the proposed borrower. A no-result search can justify another query or stronger evidence; it cannot justify inventing the missing join.

How Should Engineering Separate Source and Decision Data?

What records should remain distinct?

Use one immutable source-response record, one selected-entity link, one normalized current-state view, and one customer disposition. Keep the request ID and source URL so an analyst can trace the displayed field back to the retrieval. Preserve alternatives when they affected the selection.

The current Cobalt buying checklist recommends testing ordinary and edge cases across representative states before vendor selection.^[4] Include long-running states, no results, multiple candidates, paid-state behavior, fields absent by jurisdiction, and any temporary evidence link.

How should freshness be represented?

Store the check timestamp and whether the request used live or cached data. Cobalt's freshness guide distinguishes real-time source retrieval from cached registry data.^[5] A cached result can support screening, but a final decision should follow the lender's documented freshness requirement. Do not label cached data current without the check mode and date.

submitted data
  -> source query and raw response
  -> selected entity and normalized view
  -> customer rule and exception evidence
  -> lender-owned disposition

How Should State Differences Be Handled?

Why does a national schema still need jurisdiction context?

California defines registration date, jurisdiction, status, agent, and addresses on its search page and cautions about foreign-entity status.^[8] Florida exposes different search routes and detail fields.^[9] A consistent API schema reduces engineering work, but it should not erase the source field, jurisdiction, or unavailable value.

Cobalt's state-coverage checklist recommends evaluating the fields a buyer needs in each state rather than relying only on a coverage count.^[6] That is the right procurement test for this workflow.

What should happen when a field is missing?

Represent it as unavailable from the source, not empty evidence of a negative fact. Route any field that is mandatory for the lender's decision to a documented fallback or exception. Do not infer an officer, formation date, status, or address from a different source without recording the new source.

Which Controls Should Operations Measure?

What reveals a broken process?

Track unresolved candidates, no-result rate by state and input channel, reviewer overrides, source-unavailable events, missing required fields, stale cached decisions, temporary evidence not archived, and dispositions without source IDs. Segment the results by jurisdiction and rule version.

What should not be claimed from these measures?

Operational counts can show where identity resolution or evidence handling fails. They do not prove fraud detection, default reduction, approval lift, legal compliance, or customer ROI without separate evidence. Keep those outcome claims out of the article and out of the decision rule.

How Does Cobalt Fit Without Owning the Decision?

Which alternatives should buyers compare?

Teams can use state portals manually, build state-specific connectors, or buy a commercial KYB source. Compare them on live and cached modes, source traceability, field availability, alternative handling, response behavior, temporary evidence, and how much state-specific maintenance remains with the customer.

Cobalt provides a normalized SOS retrieval path across all 50 states and D.C. under the current product authority. The lender provides the application context, entity selection, exception policy, storage controls, and decision. That division is the honest answer to which SOS response fields belong in durable storage, reviewer views, analytics, and short-lived evidence handling.

What is the next useful test?

Test one clean entity and at least four exception cases tied to this topic. Confirm that the system preserves the submitted value, raw response, selected record, source context, rule version, and human disposition. Then test that a later source or mapping change does not rewrite the historical evidence.

To test the current API behavior with your own field and exception requirements, schedule a Cobalt Intelligence demo. Bring representative states, clean cases, and the exceptions your team sees today.