> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataspike.io/llms.txt
> Use this file to discover all available pages before exploring further.
# US Company Registry Check
> Verify that a company is registered with a US state's Secretary of State office.
Verify that a company is registered with a US state's Secretary of State office. The check returns registration details including company name, type, registration date, registered agent, and (depending on the state) officer information.
## Step 1: Create an applicant
Create an applicant to associate the verification with.
```bash theme={null}
export API_KEY=
curl -H "ds-api-token: $API_KEY" \
-H "Content-Type: application/json" \
-X POST "https://api.dataspike.io/api/v3/applicants" \
--data '{"external_id": "company-456"}'
```
Response:
```json theme={null}
{
"id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11"
}
```
```python theme={null}
import requests
API_KEY = ""
BASE = "https://api.dataspike.io"
HEADERS = {"ds-api-token": API_KEY, "Content-Type": "application/json"}
resp = requests.post(f"{BASE}/api/v3/applicants", headers=HEADERS, json={"external_id": "company-456"})
applicant_id = resp.json()["id"]
```
## Step 2: Submit registry check request
Provide the company name and state. You can also search by SOS ID (Secretary of State filing number) if you have it.
```bash theme={null}
APPLICANT_ID="01827ed4-c928-7a3c-9a30-7ab7cc169d11"
curl -H "ds-api-token: $API_KEY" \
-H "Content-Type: application/json" \
-X POST "https://api.dataspike.io/api/v4/kyb/$APPLICANT_ID/us-registry-check" \
--data '{
"company_name": "Acme Holdings Inc.",
"state": "delaware"
}'
```
Response (HTTP 202):
```json theme={null}
{
"request_id": "019c9e79-4d64-73e1-9f30-5374f0f57975",
"status": "initial"
}
```
```python theme={null}
resp = requests.post(
f"{BASE}/api/v4/kyb/{applicant_id}/us-registry-check",
headers=HEADERS,
json={"company_name": "Acme Holdings Inc.", "state": "delaware"},
)
request_id = resp.json()["request_id"]
```
### Request body
| Field | Type | Required | Description |
| -------------- | ------ | ----------- | ----------------------------------------------------------------------------- |
| `company_name` | string | Conditional | Company name to search for. Required if `sos_id` is not provided. |
| `state` | string | Yes | US state name (e.g. `delaware`, `california`, `new york`) |
| `sos_id` | string | Conditional | Secretary of State filing number. Required if `company_name` is not provided. |
## Step 3: Poll for the result
The registry check typically takes 10-20 seconds. Poll the result endpoint until the status changes from `initial`.
```bash theme={null}
REQUEST_ID="019c9e79-4d64-73e1-9f30-5374f0f57975"
curl -H "ds-api-token: $API_KEY" \
"https://api.dataspike.io/api/v4/kyb/result/$REQUEST_ID"
```
Example response (verified). The result mirrors the **full field set** the state registry provides;
fields a given state does not return are omitted.
```json theme={null}
{
"request_id": "019c9e79-4d64-73e1-9f30-5374f0f57975",
"status": "verified",
"verification_type": "us_company_registry_check",
"response_data": {
"results": [
{
"base_info": {
"company_name": "ACME HOLDINGS INC.",
"registration_number": "7654321",
"status": "Good Standing",
"company_type": "Corporation",
"registration_date": "3/15/2022",
"jurisdiction": "DE",
"registered_address": {
"street": "850 NEW BURTON ROAD SUITE 201",
"city": "DOVER",
"state_or_province": "DE",
"postal_code": "19904",
"country": "US"
},
"associated_persons": [
{
"name": "Jane Smith",
"role": "CEO",
"address": { "street": "1 Main St", "city": "Dover", "state_or_province": "DE", "postal_code": "19901", "country": "US" },
"phone": "+1-302-555-0100",
"email": "jane@acme.example",
"current": "true"
}
]
},
"sos_id": "7654321",
"state_of_formation": "DE",
"mailing_address": { "street": "PO Box 5", "city": "Dover", "state_or_province": "DE", "postal_code": "19903", "country": "US" },
"registered_agent": {
"name": "CORPORATION SERVICE COMPANY",
"address": { "street": "251 LITTLE FALLS DRIVE", "city": "WILMINGTON", "state_or_province": "DE", "postal_code": "19808", "country": "US" }
},
"normalized_status": "active",
"normalized_filing_date": "2022-03-15T00:00:00.000Z",
"entity_sub_type": "Domestic",
"phone_number": "+1-302-555-0148",
"email": "contact@acme.example",
"industry": "Holding companies",
"url": "https://icis.corp.delaware.gov/Ecorp/EntitySearch/...",
"confidence_level": 100,
"ai_confidence_level": 98.5,
"ein": "36-2382580",
"ar_standing": "Current",
"next_report_due_date": "2027-03-01",
"agent_is_commercial": true,
"agent_resigned": false,
"address_match": true,
"assumed_business_names": [
{ "title": "ACME CAPITAL", "status": "Active", "type": "DBA", "effective_date": "2023-01-10", "sos_id": "DBA-99", "joint_venture": false }
],
"documents": [
{ "name": "Certificate of Incorporation", "url": "https://.../doc/123", "date": "3/15/2022" }
],
"ucc_data": [
{
"file_number": "2023-1234567",
"type": "Original",
"filing_date": "2023-06-01",
"status": "Active",
"lapse_date": "2028-06-01",
"image_url": "https://.../ucc/123",
"debtors": [ { "name": "ACME HOLDINGS INC.", "street": "1 Main St", "city": "Dover", "state": "DE", "zip": "19904" } ],
"secured_parties": [ { "name": "BIG BANK NA", "street": "100 Bank St", "city": "New York", "state": "NY", "zip": "10001" } ]
}
],
"history": [
{
"name": "Amendment",
"date": "2024-02-01",
"changes": [
{ "name": "Registered Agent", "action": "Modified", "changed_from": "OLD AGENT LLC", "changed_to": "CORPORATION SERVICE COMPANY" }
]
}
],
"full_data_count": { "officers_count": 1, "documents_count": 1, "ucc_data_count": 1, "assumed_business_names_count": 1, "history_count": 1 }
}
]
},
"created_at": "2026-02-27T09:41:15.822681Z",
"completed_at": "2026-02-27T09:41:30.583502Z"
}
```
```python theme={null}
import time
while True:
resp = requests.get(f"{BASE}/api/v4/kyb/result/{request_id}", headers=HEADERS)
result = resp.json()
if result["status"] != "initial":
break
time.sleep(5)
print(result)
```
## Response data
When the check returns `verified`, `response_data.results` is an array of matching company records.
Each record exposes the **complete set of fields** the state registry makes available — any field a
given state does not return is omitted. The full schema is in the
[API reference](/api-reference#tag/KYB-Verification/operation/kyb-get-result); the tables below group
the fields by purpose.
### Core company info (`base_info`)
| Field | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| `base_info.company_name` | Registered company name |
| `base_info.registration_number` | State filing number |
| `base_info.status` | Status as reported by the state (free text, e.g. `Good Standing`) |
| `base_info.company_type` | Entity type (Corporation, LLC, …) |
| `base_info.registration_date` | Date of formation/registration |
| `base_info.jurisdiction` | State of registration (2-letter code) |
| `base_info.registered_address` | Physical address (object: `street`, `city`, `state_or_province`, `postal_code`, `country`) |
| `base_info.associated_persons` | Officers/directors/members (array; see below). Availability varies by state |
### Identifiers & classification
| Field | Description |
| ----------------------------------- | --------------------------------------------------------------- |
| `sos_id` | Secretary of State filing number |
| `state_of_formation` | State where the company was originally formed |
| `ein` | Employer Identification Number (federal tax ID), when available |
| `entity_sub_type` | Domestic / Foreign / Nonprofit |
| `industry` | Industry classification |
| `url` | Link to the source record on the state website |
| `tax_payer_number` | State taxpayer number (Texas) |
| `ubi_number` | Unified Business Identifier (Washington) |
| `tax_amount_due` | Tax amount due (Delaware) |
| `registrant_name`, `registrant_url` | Registrant name / link (Colorado) |
### Status & dates
| Field | Description |
| ------------------------ | ------------------------------------------------------------------- |
| `status_reason` | Reason for the status, when the state provides one |
| `normalized_status` | Standardized status (`active` / `inactive`) across states |
| `normalized_filing_date` | Filing date in ISO 8601 |
| `good_standing` | Good-standing indicator (Maryland) |
| `ar_standing` | Annual-report filing standing |
| `next_report_due_date` | Date the next annual report is due |
| `inactive_date` | Date the entity became inactive (may be a date or e.g. `Perpetual`) |
### Addresses & agents
| Field | Description |
| --------------------------------------- | ------------------------------------------------------------ |
| `mailing_address` | Mailing address (address object) |
| `state_address` | In-state physical address (address object) |
| `registered_agent` | Registered agent (`name` + `address`) |
| `service_of_process_agent` | Service-of-process agent (`name` + `address`; e.g. New York) |
| `agent_is_commercial` | Whether the registered agent is a commercial service |
| `agent_resigned`, `agent_resigned_date` | Whether/when the agent resigned |
### Match metadata
| Field | Description |
| ---------------------------------------- | ---------------------------------------------------------------------------- |
| `confidence_level` | Levenshtein-based match confidence (query vs found name) |
| `ai_confidence_level` | AI-based match-confidence score (beta) |
| `person_name_match` | Person name from the query that matched an officer or agent |
| `address_match` | Whether the address matched the one provided in the query |
| `search_result_title` | Name on the search results when it differs from the legal name (e.g. a DBA) |
| `messages` | Array of provider notes about anything unexpected |
| `screenshot_url`, `screenshot_succeeded` | Source-record screenshot URL / capture flag (when a screenshot is requested) |
| `ucc_succeeded` | Whether UCC data was retrieved (when UCC data is requested) |
### Collections
| Field | Item shape |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `associated_persons[]` | `name`, `role`, `address`, `phone`, `email`, `current` |
| `assumed_business_names[]` | DBAs: `title`, `status`, `type`, `effective_date`, `expiration_date`, `sos_id`, `joint_venture` |
| `documents[]` | On-file documents: `name`, `url`, `date`, `comment` |
| `ucc_data[]` | UCC filings: `file_number`, `type`, `filing_date`, `status`, `lapse_date`, `image_url`, `debtors[]`, `secured_parties[]` (each party: `name`, `street`, `city`, `state`, `zip`) |
| `history[]` | Amendment events: `name`, `date`, `changes[]` (each change: `name`, `action`, `changed_from`, `changed_to`, `title`) |
| `full_data_count` | Counts: `officers_count`, `documents_count`, `ucc_data_count`, `assumed_business_names_count`, `history_count` |
The available data varies by state — some states return detailed officers, documents, and history,
while others return only basic registration details. `ucc_data` and `screenshot_url` are returned
only when UCC data / a screenshot are requested for the check.
## Result statuses
| Status | Meaning |
| -------------- | ----------------------------------- |
| `verified` | Company found in the state registry |
| `not_verified` | No matching company found |
| `failed` | An error occurred during the check |