openapi: 3.1.0
info:
  title: Harbor Compliance Compliance Filings Entities API
  description: The Harbor Compliance API enables partners to integrate compliance management capabilities into their platforms. The API provides programmatic access to business licensing, registered agent services, compliance tracking, and entity management workflows. Partners can automate compliance tasks, monitor filing deadlines, manage registered agent appointments, and track licensing requirements across jurisdictions.
  version: '1.0'
  contact:
    name: Harbor Compliance Support
    url: https://www.harborcompliance.com/contact
  termsOfService: https://www.harborcompliance.com/terms-of-service
servers:
- url: https://api.harborcompliance.com/v1
  description: Production Server
security:
- apiKey: []
tags:
- name: Entities
  description: Business entity management including corporations, LLCs, and other legal entities.
paths:
  /entities:
    get:
      operationId: listEntities
      summary: Harbor Compliance List business entities
      description: Returns a paginated list of business entities managed under the partner account. Results can be filtered by entity type, state, and status.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam'
      - name: state
        in: query
        description: Filter entities by state of formation (two-letter state code).
        schema:
          type: string
          pattern: ^[A-Z]{2}$
      - name: entity_type
        in: query
        description: Filter by entity type.
        schema:
          type: string
          enum:
          - corporation
          - llc
          - lp
          - llp
          - nonprofit
          - sole_proprietorship
      - name: status
        in: query
        description: Filter by entity status.
        schema:
          type: string
          enum:
          - active
          - inactive
          - dissolved
          - pending
      responses:
        '200':
          description: A paginated list of business entities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Entity'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEntity
      summary: Harbor Compliance Create a business entity
      description: Creates a new business entity record in Harbor Compliance. This registers the entity for compliance tracking and monitoring across applicable jurisdictions.
      tags:
      - Entities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreate'
      responses:
        '201':
          description: The newly created business entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /entities/{entityId}:
    get:
      operationId: getEntity
      summary: Harbor Compliance Get a business entity
      description: Retrieves detailed information about a specific business entity including its formation details, registered agent, compliance status, and active licenses.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/entityIdParam'
      responses:
        '200':
          description: Business entity details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateEntity
      summary: Harbor Compliance Update a business entity
      description: Updates mutable fields on a business entity record such as the contact information, principal address, and officer details.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/entityIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdate'
      responses:
        '200':
          description: The updated business entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entity'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /entities/{entityId}/compliance:
    get:
      operationId: getEntityCompliance
      summary: Harbor Compliance Get compliance status for an entity
      description: Returns the full compliance status for a business entity including upcoming filing deadlines, overdue items, and a summary of active compliance requirements across all jurisdictions where the entity operates.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/entityIdParam'
      responses:
        '200':
          description: Entity compliance status summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ComplianceDeadline:
      type: object
      title: ComplianceDeadline
      description: A single upcoming or overdue compliance deadline.
      required:
      - type
      - state
      - due_date
      - status
      properties:
        type:
          type: string
          description: Type of compliance requirement.
          enum:
          - annual_report
          - biennial_report
          - license_renewal
          - registered_agent
          - franchise_tax
          - other
        state:
          type: string
          description: Two-letter state code for the jurisdiction.
          pattern: ^[A-Z]{2}$
        due_date:
          type: string
          format: date
          description: Date the compliance item is due.
        status:
          type: string
          description: Current status of the compliance item.
          enum:
          - pending
          - in_progress
          - overdue
        description:
          type: string
          description: Human-readable description of the compliance requirement.
        filing_id:
          type: string
          description: Reference to the associated filing record, if applicable.
        license_id:
          type: string
          description: Reference to the associated license record, if applicable.
    Officer:
      type: object
      title: Officer
      description: An officer, director, or member of a business entity.
      required:
      - name
      - title
      properties:
        name:
          type: string
          description: Full legal name of the officer.
        title:
          type: string
          description: Title or role of the officer (e.g., President, Secretary, Manager).
        address:
          $ref: '#/components/schemas/Address'
    Address:
      type: object
      title: Address
      description: A postal address.
      required:
      - street1
      - city
      - state
      - zip
      properties:
        street1:
          type: string
          description: Primary street address line.
        street2:
          type: string
          description: Secondary street address line (suite, unit, etc.).
        city:
          type: string
          description: City name.
        state:
          type: string
          description: Two-letter state code.
          pattern: ^[A-Z]{2}$
        zip:
          type: string
          description: ZIP or postal code.
          pattern: ^\d{5}(-\d{4})?$
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          default: US
    EntityCreate:
      type: object
      title: EntityCreate
      description: Fields required to create a new business entity record.
      required:
      - name
      - entity_type
      - state
      properties:
        name:
          type: string
          description: Legal name of the business entity.
        entity_type:
          type: string
          description: The legal structure of the entity.
          enum:
          - corporation
          - llc
          - lp
          - llp
          - nonprofit
          - sole_proprietorship
        state:
          type: string
          description: Two-letter state code where the entity was formed.
          pattern: ^[A-Z]{2}$
        ein:
          type: string
          description: Employer Identification Number (EIN).
          pattern: ^\d{2}-\d{7}$
        formation_date:
          type: string
          format: date
          description: Date the entity was formed or incorporated.
        principal_address:
          $ref: '#/components/schemas/Address'
        officers:
          type: array
          description: Officers and directors associated with the entity.
          items:
            $ref: '#/components/schemas/Officer'
    PaginationMeta:
      type: object
      title: PaginationMeta
      description: Pagination metadata included with list responses.
      properties:
        total:
          type: integer
          description: Total number of records matching the query.
        page:
          type: integer
          description: Current page number.
        per_page:
          type: integer
          description: Number of records per page.
        total_pages:
          type: integer
          description: Total number of pages available.
    EntityUpdate:
      type: object
      title: EntityUpdate
      description: Fields that can be updated on an existing business entity.
      properties:
        name:
          type: string
          description: Updated legal name of the entity.
        principal_address:
          $ref: '#/components/schemas/Address'
        mailing_address:
          $ref: '#/components/schemas/Address'
        officers:
          type: array
          description: Updated list of officers and directors.
          items:
            $ref: '#/components/schemas/Officer'
    Entity:
      type: object
      title: Entity
      description: A business entity managed by Harbor Compliance.
      required:
      - id
      - name
      - entity_type
      - state
      - status
      properties:
        id:
          type: string
          description: Unique identifier for the business entity.
        name:
          type: string
          description: Legal name of the business entity.
        entity_type:
          type: string
          description: The legal structure of the entity.
          enum:
          - corporation
          - llc
          - lp
          - llp
          - nonprofit
          - sole_proprietorship
        state:
          type: string
          description: Two-letter state code where the entity was formed.
          pattern: ^[A-Z]{2}$
        status:
          type: string
          description: Current standing status of the entity.
          enum:
          - active
          - inactive
          - dissolved
          - pending
        ein:
          type: string
          description: Employer Identification Number (EIN) assigned by the IRS.
          pattern: ^\d{2}-\d{7}$
        formation_date:
          type: string
          format: date
          description: Date the entity was formed or incorporated.
        registered_agent_id:
          type: string
          description: Identifier of the registered agent appointment for this entity.
        principal_address:
          $ref: '#/components/schemas/Address'
        mailing_address:
          $ref: '#/components/schemas/Address'
        officers:
          type: array
          description: List of officers and directors associated with the entity.
          items:
            $ref: '#/components/schemas/Officer'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the entity record was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update to the entity record.
    Error:
      type: object
      title: Error
      description: Error response returned when a request fails.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable description of the error.
        details:
          type: array
          description: Additional details about specific validation errors.
          items:
            type: object
            properties:
              field:
                type: string
                description: The field that caused the error.
              message:
                type: string
                description: Description of the field-level error.
    ComplianceStatus:
      type: object
      title: ComplianceStatus
      description: A summary of the compliance status for a business entity.
      required:
      - entity_id
      - overall_status
      properties:
        entity_id:
          type: string
          description: Identifier of the entity this status applies to.
        overall_status:
          type: string
          description: Overall compliance health status for the entity.
          enum:
          - compliant
          - attention_required
          - non_compliant
        upcoming_deadlines:
          type: array
          description: Compliance items due within the next 90 days.
          items:
            $ref: '#/components/schemas/ComplianceDeadline'
        overdue_items:
          type: array
          description: Compliance items that are past their due date.
          items:
            $ref: '#/components/schemas/ComplianceDeadline'
        active_licenses_count:
          type: integer
          description: Total number of active business licenses.
          minimum: 0
        expiring_licenses_count:
          type: integer
          description: Number of licenses expiring within the next 90 days.
          minimum: 0
        registered_agent_states:
          type: array
          description: List of states where the entity has an active registered agent.
          items:
            type: string
            pattern: ^[A-Z]{2}$
        generated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when this status was generated.
  parameters:
    entityIdParam:
      name: entityId
      in: path
      required: true
      description: Unique identifier for the business entity.
      schema:
        type: string
    pageParam:
      name: page
      in: query
      description: Page number for paginated results (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
    perPageParam:
      name: per_page
      in: query
      description: Number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authenticating partner requests. Obtain your API key from the Harbor Compliance developer portal.
externalDocs:
  description: Harbor Compliance Developer Documentation
  url: https://developers.harborcompliance.com/