{ "openapi": "3.1.0", "info": { "title": "Clerkfield API", "version": "1.0.0", "summary": "Business verification and UCC lien search from official U.S. state records.", "description": "Verify a U.S. business against its state's official registry (Pass, Review or Fail with reasons) and search UCC lien filings by business or by lender. Every result names its official source and the date of the data. Business records only: Clerkfield is not a consumer reporting agency. Docs: https://clerkfield.com/docs", "contact": { "name": "Clerkfield", "url": "https://clerkfield.com/contact" }, "termsOfService": "https://clerkfield.com/terms" }, "servers": [ { "url": "https://clerkfield.com" } ], "externalDocs": { "url": "https://clerkfield.com/docs" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Business verification" }, { "name": "UCC liens" }, { "name": "Coverage" }, { "name": "Account" } ], "paths": { "/v1/business-check": { "get": { "operationId": "verifyBusiness", "tags": [ "Business verification" ], "summary": "Verify a business against its state registry", "description": "Finds the business in the registry of the state it was formed in and returns a pass, review or fail verdict with flags explaining why, plus the state's record.", "parameters": [ { "name": "name", "in": "query", "required": true, "description": "Business name, as the applicant gave it.", "schema": { "type": "string", "minLength": 1 } }, { "name": "state", "in": "query", "required": true, "description": "Two-letter state code.", "schema": { "type": "string", "enum": [ "AL", "AR", "CO", "CT", "FL", "ID", "KY", "MN", "ND", "NJ", "NM", "NY", "OR", "PA", "TX" ] } }, { "name": "owner", "in": "query", "required": false, "description": "Applicant's name, checked against the officers the state lists.", "schema": { "type": "string" } }, { "name": "min_months", "in": "query", "required": false, "description": "Minimum months in business. Default 6.", "schema": { "type": "integer", "minimum": 0, "default": 6 } } ], "responses": { "200": { "description": "Verdict and record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } } } }, "/v1/liens": { "get": { "operationId": "searchLiens", "tags": [ "UCC liens" ], "summary": "Search UCC lien filings by business or by lender", "description": "Returns a summary and every UCC filing that matches, newest first, with its later amendments. Search by lender works in CT, FL, NE, NM, RI.", "parameters": [ { "name": "state", "in": "query", "required": true, "description": "Two-letter state code.", "schema": { "type": "string", "enum": [ "AL", "AR", "CT", "FL", "ID", "KY", "NE", "NJ", "NM", "RI" ] } }, { "name": "debtor", "in": "query", "required": false, "description": "Business name. Give debtor or secured_party.", "schema": { "type": "string" } }, { "name": "secured_party", "in": "query", "required": false, "description": "Lender name (CT, FL, NE, NM, RI).", "schema": { "type": "string" } }, { "name": "include_inactive", "in": "query", "required": false, "description": "false returns active filings only.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Summary and filings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LienSearchResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } } } }, "/v1/coverage": { "get": { "operationId": "getCoverage", "tags": [ "Coverage" ], "summary": "Which states each check covers", "security": [], "responses": { "200": { "description": "One entry per state and DC.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } } } }, "/v1/account/me": { "get": { "operationId": "getAccount", "tags": [ "Account" ], "summary": "Check an API key and see which account it belongs to", "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from your Clerkfield profile (Authorization: Bearer )." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "supported": { "type": "array", "items": { "type": "string" } } } } } } } }, "schemas": { "Source": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "asOf": { "type": "string", "description": "Date of the data, YYYY-MM-DD." } } }, "Person": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "address": { "type": "string" } } }, "Flag": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "INACTIVE", "NAME_VARIANT", "NAME_MISMATCH", "AMBIGUOUS", "STATUS_UNCONFIRMED", "YOUNG_BUSINESS", "FORMATION_DATE_MISSING", "OWNER_CONFIRMED", "OWNER_UNVERIFIED", "OWNER_NOT_LISTED" ] }, "severity": { "type": "string", "enum": [ "fail", "review", "info" ] }, "message": { "type": "string" } } }, "BusinessRecord": { "type": "object", "properties": { "state": { "type": "string" }, "entityId": { "type": "string" }, "legalName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "unknown" ] }, "statusDetail": { "type": "string" }, "entityType": { "type": "string" }, "formedOn": { "type": "string" }, "monthsInBusiness": { "type": "integer" }, "principalAddress": { "type": "string" }, "serviceAddress": { "type": "string" }, "registeredAgent": { "type": "string" }, "officers": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "officersAvailable": { "type": "boolean" }, "details": { "type": "object", "additionalProperties": { "type": "string" } }, "source": { "$ref": "#/components/schemas/Source" }, "score": { "type": "number" } } }, "CheckResult": { "type": "object", "properties": { "query": { "type": "object", "properties": { "name": { "type": "string" }, "state": { "type": "string" }, "owner": { "type": "string" } } }, "verdict": { "type": "string", "enum": [ "pass", "review", "fail" ] }, "matchQuality": { "type": "string", "enum": [ "exact", "strong", "possible", "none" ] }, "match": { "$ref": "#/components/schemas/BusinessRecord" }, "alternatives": { "type": "array", "items": { "type": "object", "properties": { "legalName": { "type": "string" }, "entityId": { "type": "string" }, "score": { "type": "number" } } } }, "flags": { "type": "array", "items": { "$ref": "#/components/schemas/Flag" } }, "checkedAt": { "type": "string", "format": "date-time" } } }, "LienParty": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "former": { "type": "boolean" } } }, "LienFiling": { "type": "object", "properties": { "state": { "type": "string" }, "fileNumber": { "type": "string" }, "filedOn": { "type": "string" }, "lapseOn": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "lapsed", "terminated", "unknown" ] }, "debtors": { "type": "array", "items": { "$ref": "#/components/schemas/LienParty" } }, "securedParties": { "type": "array", "items": { "$ref": "#/components/schemas/LienParty" } }, "events": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "continuation", "amendment", "assignment", "termination", "other" ] }, "fileNumber": { "type": "string" }, "filedOn": { "type": "string" }, "detail": { "type": "string" } } } }, "collateral": { "type": "string" }, "unavailable": { "type": "array", "items": { "type": "string" } }, "source": { "$ref": "#/components/schemas/Source" } } }, "LienSearchResult": { "type": "object", "properties": { "query": { "type": "object" }, "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "active": { "type": "integer" }, "lapsed": { "type": "integer" }, "terminated": { "type": "integer" }, "activeSecuredParties": { "type": "array", "items": { "type": "string" } }, "notPublished": { "type": "array", "items": { "type": "string" } } } }, "filings": { "type": "array", "items": { "$ref": "#/components/schemas/LienFiling" } }, "searchedAt": { "type": "string", "format": "date-time" } } }, "Account": { "type": "object", "properties": { "org": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "via": { "type": "string", "enum": [ "session", "key", "admin" ] }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" } } } } } } } }