openapi: 3.0.3
info:
  title: VerifySOS API
  version: "0.8-beta"
  description: |
    One call returns the merged business-verification record across:
    state Secretary of State, USDOT/FMCSA carrier registration, OFAC SDN
    sanctions screen, UCC central-filing index, and state contractor /
    professional-license boards. Drop-in REST contract — point your client
    at our base URL and pick up USDOT + OFAC + UCC + contractor licenses
    in the same response.

    **Pricing:** $0.05 per successful 200 lookup. 404 (no entity match) is
    free. No subscription required.

    **Auth:** `x-api-key: vfs_<your_key>` header. Get a key at
    https://verifysos.com/account/api-key
  contact:
    name: VerifySOS Support
    email: admin@verifysos.com
    url: https://verifysos.com/api/docs
  license:
    name: Proprietary
servers:
  - url: https://verifysos.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/lookup:
    post:
      summary: Verify a business by name + state
      description: |
        Bundled SOS + USDOT/FMCSA + OFAC SDN + UCC + contractor-license
        verification record. Returns the auto-selected best match.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupRequest'
      responses:
        '200':
          description: Verification record returned ($0.05 billed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupResponse'
        '404':
          description: No SOS entity match (no charge)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/states:
    get:
      summary: Supported states + automation status
      description: Returns every state code, its automation status, and the public state-landing URL.
      security: []
      responses:
        '200':
          description: State list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatesResponse'
  /api/v1/health:
    get:
      summary: Service health
      security: []
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                  commit:
                    type: string
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    LookupRequest:
      type: object
      required: [entity_name, state]
      properties:
        entity_name:
          type: string
          minLength: 2
          maxLength: 200
          description: Business legal name. Include entity suffix (LLC/Inc/Corp) for cleaner disambiguation.
          example: "JNG Trucking LLC"
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: 2-letter US state code.
          example: "CA"
        include_safer:
          type: boolean
          default: true
          description: Set false to skip the USDOT/FMCSA lookup for non-trucking verifications.
    LookupResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/EntityRecord'
        cost:
          type: number
          format: float
          example: 0.05
        scraped_at:
          type: string
          format: date-time
    EntityRecord:
      type: object
      properties:
        state:
          type: string
        entityName:
          type: string
        entityId:
          type: string
        status:
          type: string
        entityType:
          type: string
        formationDate:
          type: string
          format: date
        yearsInBusiness:
          type: number
        registeredAgent:
          type: object
          properties:
            name:
              type: string
            address:
              type: string
        principalAddress:
          type: string
        officers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              title:
                type: string
        sosUrl:
          type: string
          format: uri
        usdot:
          type: object
          nullable: true
          properties:
            dotNumber:
              type: string
            mcNumber:
              type: string
            status:
              type: string
            legalName:
              type: string
            physicalAddress:
              type: string
            fleetSize:
              type: integer
              nullable: true
            drivers:
              type: integer
              nullable: true
        ofac:
          type: object
          properties:
            clear:
              type: boolean
            hits:
              type: array
              items:
                type: object
        ucc:
          type: object
          nullable: true
          description: UCC-1 secured-creditor filings against this debtor in the state.
          properties:
            state:
              type: string
            source:
              type: string
            searchUrl:
              type: string
              format: uri
            activeCount:
              type: integer
            totalCount:
              type: integer
            filings:
              type: array
              items:
                type: object
                properties:
                  filingNumber:
                    type: string
                  debtorName:
                    type: string
                  securedParties:
                    type: array
                    items:
                      type: string
                  fileDate:
                    type: string
                  filingType:
                    type: string
                  status:
                    type: string
                  detailUrl:
                    type: string
                    format: uri
        licenses:
          type: object
          nullable: true
          description: State contractor / professional-license registry hits.
          properties:
            state:
              type: string
            board:
              type: string
            searchUrl:
              type: string
              format: uri
            count:
              type: integer
            licenses:
              type: array
              items:
                type: object
                properties:
                  licenseNumber:
                    type: string
                  classification:
                    type: string
                  status:
                    type: string
                  expiry:
                    type: string
                  businessName:
                    type: string
                  detailUrl:
                    type: string
                    format: uri
    StatesResponse:
      type: object
      properties:
        success:
          type: boolean
        count:
          type: integer
        states:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              name:
                type: string
              status:
                type: string
                enum: [active, manual_lookup, unsupported]
              landingUrl:
                type: string
                format: uri
    NotFoundResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          example: not_found
        message:
          type: string
        ofac:
          type: object
          properties:
            clear:
              type: boolean
            hits:
              type: array
              items:
                type: object
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
        message:
          type: string
