openapi: 3.1.0
info:
  title: Harbor Compliance Compliance Filings Registered Agents 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: Registered Agents
  description: Registered agent appointment and management for business entities.
paths:
  /registered-agents:
    get:
      operationId: listRegisteredAgents
      summary: Harbor Compliance List registered agent appointments
      description: Returns a paginated list of registered agent appointments for entities managed under the partner account. Includes appointment status and jurisdiction details.
      tags:
      - Registered Agents
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/perPageParam'
      - name: entity_id
        in: query
        description: Filter by entity identifier.
        schema:
          type: string
      - name: state
        in: query
        description: Filter by state jurisdiction.
        schema:
          type: string
          pattern: ^[A-Z]{2}$
      responses:
        '200':
          description: A paginated list of registered agent appointments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RegisteredAgent'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createRegisteredAgentAppointment
      summary: Harbor Compliance Appoint a registered agent
      description: Creates a new registered agent appointment for a business entity in a specified state. Harbor Compliance will file the necessary paperwork with the state to formalize the appointment.
      tags:
      - Registered Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisteredAgentCreate'
      responses:
        '201':
          description: The newly created registered agent appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredAgent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /registered-agents/{agentId}:
    get:
      operationId: getRegisteredAgent
      summary: Harbor Compliance Get a registered agent appointment
      description: Retrieves details about a specific registered agent appointment including the agent's address, appointment status, and associated entity.
      tags:
      - Registered Agents
      parameters:
      - $ref: '#/components/parameters/agentIdParam'
      responses:
        '200':
          description: Registered agent appointment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisteredAgent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RegisteredAgent:
      type: object
      title: RegisteredAgent
      description: A registered agent appointment for a business entity in a state.
      required:
      - id
      - entity_id
      - state
      - status
      properties:
        id:
          type: string
          description: Unique identifier for the registered agent appointment.
        entity_id:
          type: string
          description: Identifier of the entity for which the agent is appointed.
        state:
          type: string
          description: Two-letter state code where the agent is appointed.
          pattern: ^[A-Z]{2}$
        status:
          type: string
          description: Current status of the registered agent appointment.
          enum:
          - active
          - pending
          - resigned
          - revoked
        agent_name:
          type: string
          description: Name of the registered agent.
        agent_address:
          $ref: '#/components/schemas/Address'
        appointment_date:
          type: string
          format: date
          description: Date the registered agent was officially appointed.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the appointment record was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
    RegisteredAgentCreate:
      type: object
      title: RegisteredAgentCreate
      description: Fields required to create a registered agent appointment.
      required:
      - entity_id
      - state
      properties:
        entity_id:
          type: string
          description: Identifier of the entity requiring a registered agent.
        state:
          type: string
          description: Two-letter state code where the agent should be appointed.
          pattern: ^[A-Z]{2}$
        notes:
          type: string
          description: Optional notes for the registered agent appointment request.
    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
    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.
    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.
  responses:
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    agentIdParam:
      name: agentId
      in: path
      required: true
      description: Unique identifier for the registered agent appointment.
      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
  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/