Secretary of State Search API

This document highlights the Secretary of State Search API details.

API Description

Objective

The Secretary of State Search API retrieves business registration details from U.S. state secretary of state databases using Legal Name and State as input parameters.

Input	Output
The Business Legal Name and State	The Business registration details. A complete list of details returned by the API is provided under the Success Response Details section.

API URL

https://usa.thomas.hyperverge.co/v1/secretaryOfStateSearch

API Endpoint

secretaryOfStateSearch

Overview

The Secretary of State Search API is RESTful and uses standard HTTP verbs and status codes. The requests are in form-data format and responses are in JSON format.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table lists the parameter required for the Secretary of State Search API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
businessLegalName	Mandatory	The registered legal name of the business	Not Applicable	Not Applicable
state	Mandatory	The corresponding state where the business is incorporated	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Secretary of State Search API:

curl --location --request POST 'https://usa.thomas.hyperverge.co/v1/secretaryOfStateSearch' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "businessLegalName": "<Enter_the_legal_name>",
    "state": "<Enter_the_state_name>"
}'

Success Response

The following code snippet demonstrates a success response from the Secretary of State Search API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "businessName": "<BusinessName>",
        "activeStatus": "<ActiveStatus>",
        "latestFilingDate": "<MM/DD/YYYY>",
        "filingDate": "<YYYY-MM-DDTHH:mm:ss.sssZ>",
        "state": "<State>",
        "confidenceLevel": <confidencelevel>,
        "url": "<URL>",
        "physicalAddressStreet": "<Street>",
        "physicalAddressCity": "<City>",
        "physicalAddressState": "<State>",
        "physicalAddressZip": "<ZipCode>",
        "mailingAddressStreet": "<Street>",
        "mailingAddressCity": "<City>",
        "mailingAddressState": "<State>",
        "mailingAddressZip": "<ZipCode>",
        "stateAddressStreet": "<Street>",
        "stateAddressCity": "<City>",
        "stateAddressState": "<State>",
        "stateAddressZip": "<ZipCode>",
        "entityType": "<EntityType>",
        "EIN": "<EIN>"
    },
    "metadata": {
        "requestId": "<RequestID>",
        "transactionId": "<TransactionID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code for the request
result	object	The object containing the result details
result.businessName	string	The legal name of the business entity
result.activeStatus	string	The current status of the business entity
result.latestFilingDate	string	The most recent filing date in MM/DD/YYYY format
result.filingDate	string	The filing date in ISO format
result.state	string	The state where the business is registered
result.confidenceLevel	integer	The confidence level of the search result
result.url	string	The URL to the Secretary of State record
result.physicalAddressStreet	string	The street address of the business physical location
result.physicalAddressCity	string	The city of the business physical address
result.physicalAddressState	string	The state of the business physical address
result.physicalAddressZip	string	The ZIP code of the business physical address
result.mailingAddressStreet	string	The street address for the business mailing address
result.mailingAddressCity	string	The city of the business mailing address
result.mailingAddressState	string	The state of the business mailing address
result.mailingAddressZip	string	The ZIP code of the business mailing address
result.stateAddressStreet	string	The street address registered with the Secretary of State
result.stateAddressCity	string	The city registered with the Secretary of State
result.stateAddressState	string	The state registered with the Secretary of State
result.stateAddressZip	string	The ZIP code registered with the Secretary of State
result.entityType	string	The type of business entity
result.EIN	string	The Employer Identification Number (EIN) assigned by the IRS
metadata	object	The object containing metadata information
metadata.requestId	string	A unique identifier for the request
metadata.transactionId	string	A unique identifier for the transaction

Error Responses

The following are the error responses for the Secretary of State Search API:

Input Validation Error- Missing businessLegalName

{
    "status": "failure",
    "statusCode": 400,
    "error": "businessLegalName is required"
}

Input Validation Error- Missing state

{
    "status": "failure",
    "statusCode": 400,
    "error": "state is required"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

State Not Available

{
    "status": "failure",
    "statusCode": 404,
    "error": "State currently not available for Search"
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error"
}

External Vendor Downtime

{
    "status": "failure",
    "statusCode": 503,
    "error": "External vendor downtime"
}

Error Response Details

A failure or error response from the API contains a failure status with a relevant status code and error message.The following table lists all the error responses:

Status Code	Error Message	Error Description
400	businessLegalName is required	The business legal name is missing from the request body
400	state is required	The state parameter is missing from the request body
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
404	State currently not available for Search	The requested state is not currently supported for Secretary of State searches
500	Internal Server Error	An internal server error occurred. Please contact the HyperVerge team for resolution
503	External vendor downtime	The external vendor service is temporarily unavailable