medianfi-com Companies API

openapi: 3.2.0
info:
  title: Median Companies API
  version: 0.1.0
  description: Production-grade Node.js + Express API starter template
  license:
    name: Proprietary
servers:
- url: /api/v1
security: []
tags:
- name: Companies
paths:
  /companies/{companyId}/tax-plans:
    get:
      operationId: listPrivateTaxPlans
      summary: List private tax plans granted to the current user
      description: Requires a usual Median login and company membership. Only active named grants to available releases appear; company membership alone returns an empty list. API-key, OAuth and service-principal credentials are refused.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/companyId'
      responses:
        '200':
          description: Granted private plans
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - title
                      properties:
                        id:
                          type: string
                          format: uuid
                        title:
                          type: string
        '401':
          $ref: '#/components/responses/UnauthorizedJson'
        '403':
          $ref: '#/components/responses/ForbiddenJson'
        '404':
          $ref: '#/components/responses/NotFoundJson'
        '503':
          description: The restricted private-plan request boundary is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Companies
  /companies/{companyId}/tax-plans/availability:
    get:
      operationId: getPrivateTaxPlanAvailability
      summary: Check private tax plan availability for the current user
      description: Payload-free discovery hint for a usual Median login with company membership. Returns only whether this user and company have an active, unrevoked, unexpired named grant to an unwithdrawn release. Returns false when none exists. No model identifier, title or private payload is returned or decrypted. API-key, OAuth and service-principal credentials are refused. List and load independently recheck access; this hint does not authorize a later read.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/companyId'
      responses:
        '200':
          description: Current-user/company availability without private plan contents
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    additionalProperties: false
                    required:
                    - available
                    properties:
                      available:
                        type: boolean
        '401':
          $ref: '#/components/responses/UnauthorizedJson'
        '403':
          $ref: '#/components/responses/ForbiddenJson'
        '404':
          $ref: '#/components/responses/NotFoundJson'
        '503':
          description: The restricted private-plan request boundary is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Companies
  /companies/{companyId}/tax-plans/{modelId}:
    get:
      operationId: getPrivateTaxPlan
      summary: Load a granted private tax plan and the current user's scenario
      description: Requires a usual Median login, company membership and an active named model grant. A missing, withdrawn or inaccessible model, including a malformed model identifier, returns the hidden-resource 404 contract. The immutable release hash and engine fingerprint are verified before its payload is returned. reviewer identity is not included in the response.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/companyId'
      - name: modelId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Verified release and current scenario, or the released starting scenario
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateTaxPlanResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedJson'
        '403':
          $ref: '#/components/responses/ForbiddenJson'
        '404':
          $ref: '#/components/responses/NotFoundJson'
        '409':
          description: The released engine fingerprint or immutable payload hash cannot be verified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: The current scenario exceeds the released calculation domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: The restricted private-plan request boundary is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Companies
  /companies/{companyId}/tax-plans/{modelId}/scenario:
    put:
      operationId: savePrivateTaxPlanScenario
      summary: Save the current user's private scenario with revision checks
      description: Requires a usual Median login, company membership and an active named model grant. Validates supported inputs and recomputes the result on the server. Saves only the current user's scenario. The reviewed release is immutable. A stale release hash or scenario revision is rejected without a save.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/companyId'
      - name: modelId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavePrivateTaxPlanScenarioInput'
      responses:
        '200':
          description: Saved scenario revision and server calculation
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateTaxPlanScenarioResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedJson'
        '403':
          $ref: '#/components/responses/ForbiddenJson'
        '404':
          $ref: '#/components/responses/NotFoundJson'
        '409':
          description: Release verification failed, or the release hash or scenario revision is stale
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Invalid request fields or inputs outside the released calculation domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: The restricted private-plan request boundary is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      tags:
      - Companies
  /companies/{companyId}:
    parameters:
    - $ref: '#/components/parameters/companyId'
    get:
      operationId: getCompany
      summary: Get a company by ID
      tags:
      - Companies
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Company details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Company not found
    patch:
      operationId: updateCompany
      summary: Update a company's profile
      description: 'Partial edit of the company profile: only the keys sent are written, and an empty string is treated as "not sent". Text fields are plain text; HTML markup is rejected with 422. `fiscalYearEnd` is the one field an explicit `null` clears (back to "not confirmed", #2736); a February year end has one stored spelling, so `02-29` is stored and returned as `02-28`, meaning the last day of February; setting it to a date withdraws the open deferred onboarding fiscal-year question. Every change is recorded in the audit log with its previous and new value. Accountant-only state (`clientStatus`, `metricsEnabled`, view-only access confirmation) is ignored here and has its own accountant routes. API-key credentials are refused with 403.'
      tags:
      - Companies
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCompanyInput'
      responses:
        '200':
          description: The updated company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Company not found
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  responses:
    UnauthorizedJson:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
    Forbidden:
      description: Insufficient permissions or not a company member
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Authentication required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    ForbiddenJson:
      description: Insufficient permissions or not a company member
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
    NotFoundJson:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
    ValidationError:
      description: Request failed validation
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
  schemas:
    ApiErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          enum:
          - false
        error:
          $ref: '#/components/schemas/ProblemDetail'
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
          description: 'For application errors, a stable UPPER_SNAKE machine code (for example `NOT_FOUND`, `FORECAST_NOT_FOUND`, `VALIDATION_ERROR`). Clients branch on this, never on `detail` wording. A few transport level responses use a short human title instead.

            '
        status:
          type: integer
        detail:
          type: string
          description: 'Human-readable explanation; correlate a failure with `traceId`. A NOT_FOUND-family 404 names the resource type (for example "Company not found"), not its id. Some legacy messages still include an id (tracked in #2666).

            '
        instance:
          type: string
        traceId:
          type: string
        retryAfter:
          type: integer
          minimum: 0
          description: Whole seconds until retry is allowed for a 429 response
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        extensions:
          type: object
          additionalProperties: true
    PrivateTaxPlanResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - release
          - revision
          - state
          - result
          properties:
            release:
              type: object
              additionalProperties: false
              required:
              - id
              - companyId
              - householdId
              - releaseHash
              - engineHash
              - sourceHash
              - approvedAt
              - payload
              properties:
                id:
                  type: string
                  format: uuid
                companyId:
                  type: string
                  format: uuid
                householdId:
                  type: string
                  format: uuid
                releaseHash:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                engineHash:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                sourceHash:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                approvedAt:
                  type: string
                  format: date-time
                payload:
                  type: object
                  description: 'Immutable reviewed model payload verified by releaseHash. Includes scenario calculation graphs, input-field definitions, payment calendars, withholding tables, source cutoff, assumptions and opportunities. Its contents are specific to the named release.

                    '
                  additionalProperties: true
            revision:
              type: integer
              minimum: 0
            state:
              $ref: '#/components/schemas/PrivateTaxPlanScenario'
            result:
              $ref: '#/components/schemas/PrivateTaxPlanCalculation'
    SavePrivateTaxPlanScenarioInput:
      type: object
      additionalProperties: false
      required:
      - releaseHash
      - expectedRevision
      - state
      properties:
        releaseHash:
          type: string
          pattern: ^[a-f0-9]{64}$
        expectedRevision:
          type: integer
          minimum: 0
          maximum: 2147483646
        state:
          $ref: '#/components/schemas/PrivateTaxPlanScenario'
    PrivateTaxPlanScenario:
      type: object
      additionalProperties: false
      required:
      - scenarioId
      - inputs
      - payments
      - withholding
      properties:
        scenarioId:
          type: string
          minLength: 1
          maxLength: 150
        inputs:
          type: object
          propertyNames:
            maxLength: 100
          additionalProperties:
            type: number
            minimum: -1000000000
            maximum: 1000000000
        health:
          type: object
          additionalProperties: false
          required:
          - year
          - householdSize
          - otherMagi
          - months
          properties:
            year:
              type: integer
              minimum: 2026
              maximum: 2027
            householdSize:
              type: integer
              minimum: 1
              maximum: 12
            otherMagi:
              type: number
              minimum: 0
              maximum: 1000000000
            months:
              type: array
              minItems: 12
              maxItems: 12
              items:
                type: object
                additionalProperties: false
                required:
                - premium
                - benchmark
                - advance
                - eligible
                - deductible
                properties:
                  premium:
                    type: number
                    minimum: 0
                    maximum: 1000000
                  benchmark:
                    type: number
                    minimum: 0
                    maximum: 1000000
                  advance:
                    type: number
                    minimum: 0
                    maximum: 1000000
                  eligible:
                    type: boolean
                  deductible:
                    type: boolean
        debt:
          type: object
          additionalProperties: false
          required:
          - year
          - discharged
          - gross
          - liabilities
          - assets
          properties:
            year:
              type: integer
              minimum: 2020
              maximum: 2100
            discharged:
              type: boolean
            gross:
              type: number
              minimum: 0
              maximum: 1000000000
            liabilities:
              type: number
              minimum: 0
              maximum: 1000000000
            assets:
              type: number
              minimum: 0
              maximum: 1000000000
        funding:
          type: array
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required:
            - year
            - paidDate
            - type
            - amount
            properties:
              year:
                type: integer
                minimum: 2020
                maximum: 2100
              paidDate:
                type: string
                format: date
                pattern: ^\d{4}-\d{2}-\d{2}$
              type:
                type: string
                enum:
                - employee
                - employer
                - rollover
                - unclassified
              amount:
                type: number
                minimum: 0
                maximum: 1000000000
        payments:
          type: array
          maxItems: 100
          items:
            type: object
            additionalProperties: false
            required:
            - agency
            - year
            - date
            - amountCents
            - status
            properties:
              agency:
                type: string
                enum:
                - federal-personal
                - state-personal
                - nyc-ubt
                - nyc-gct
                - nys-ptet
                - nyc-ptet
              year:
                type: integer
                minimum: 2020
                maximum: 2100
              date:
                type: string
                format: date
                pattern: ^\d{4}-\d{2}-\d{2}$
              amountCents:
                type: integer
                minimum: 0
                maximum: 100000000000
              status:
                type: string
                enum:
                - paid
                - planned
        withholding:
          type: object
          propertyNames:
            pattern: ^20\d{2}$
          additionalProperties:
            type: object
            additionalProperties: false
            required:
            - mode
            - federalCents
            - stateCents
            - wagesPaidCents
            - federalPaidCents
            properties:
              mode:
                type: string
                enum:
                - salary-estimate
                - entered-total
                - actual-and-remaining
              federalCents:
                type: integer
                minimum: 0
                maximum: 100000000000
              stateCents:
                type: integer
                minimum: 0
                maximum: 100000000000
              wagesPaidCents:
                type: integer
                minimum: 0
                maximum: 100000000000
              federalPaidCents:
                type: integer
                minimum: 0
                maximum: 100000000000
    PrivateTaxPlanScenarioResponse:
      type: object
      required:
      - success
      - data
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          required:
          - revision
          - state
          - result
          properties:
            revision:
              type: integer
              minimum: 1
            state:
              $ref: '#/components/schemas/PrivateTaxPlanScenario'
            result:
              $ref: '#/components/schemas/PrivateTaxPlanCalculation'
    Company:
      type: object
      properties:
        fiscalYearEnd:
          type:
          - string
          - 'null'
          description: Fiscal year end as MM-DD (companies.fiscal_year_end). Null means not confirmed; it is never defaulted to 12-31. Writes must be a real MM-DD date (422 otherwise). A value other than 12-31 flags month-end close and statements for review, because non-calendar fiscal years are not supported yet (#2019).
        clientStatus:
          type: string
          enum:
          - test
          - active
          - inactive
          description: Lifecycle marker (migration 089). Used by the accountant app to hide internal test tenants in production and filter customer lists by lifecycle stage. 'active' is the default on creation; 'test' is for internal QA / demo companies; 'inactive' is for customers no longer serviced.
    UpdateCompanyInput:
      type: object
      description: Partial company profile edit. Every key is optional; an empty string is treated as "not sent". Text fields must not contain HTML markup.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Company name. Trimmed; cannot be empty and cannot contain control characters.
        entityType:
          type: string
          maxLength: 50
        industry:
          type: string
          maxLength: 100
        ein:
          type: string
          maxLength: 20
        yearFounded:
          type: integer
          minimum: 1800
          maximum: 2100
        monthFounded:
          type: integer
          minimum: 1
          maximum: 12
        state:
          type: string
          maxLength: 50
        website:
          type: string
          maxLength: 500
          description: An http(s) URL or a bare domain.
        description:
          type: string
          maxLength: 2000
        annualRevenue:
          type: string
          maxLength: 50
        monthlyExpenses:
          type: string
          maxLength: 50
        accountingMethod:
          type: string
          maxLength: 50
        fiscalYearEnd:
          type:
          - string
          - 'null'
          pattern: ^\d{2}-\d{2}$
          description: Fiscal year end as MM-DD; must be a real date (422 otherwise). An explicit null clears a stored value back to "not confirmed" (#2736); it is never defaulted to 12-31.
        currentAccountingSoftware:
          type: string
          maxLength: 100
        revenueStreams:
          type: array
          items:
            type: string
            maxLength: 255
        paymentProcessors:
          type: array
          items:
            type: string
            maxLength: 255
        bankAccountCount:
          type: string
          maxLength: 10
        creditCardCount:
          type: string
          maxLength: 10
        hasCorporateCards:
          type: boolean
        hasMercury:
          type: boolean
        hasBrex:
          type: boolean
        hasRamp:
          type: boolean
        hasRho:
          type: boolean
        payrollProvider:
          type: string
          maxLength: 100
        painPoint:
          type: string
          maxLength: 2000
        chartOfAccountsNotes:
          type: string
          maxLength: 5000
        migrationSource:
          type: string
          maxLength: 50
        migrationComplete:
          type: boolean
        chartOfAccountsReviewed:
          type: boolean
    CompanyResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Company'
    PrivateTaxPlanCalculation:
      type: object
      required:
      - values
      - year
      - payments
      - withholdingMethod
      - debtExcluded
      - funding
      - fundingRemaining
      - remainingOwnerWages
      properties:
        values:
          type: object
          additionalProperties:
            type:
            - number
            - 'null'
        year:
          type: integer
        payments:
          type: array
          items:
            type: object
            required:
            - agency
            - year
            - liabilityCents
            - withholdingCents
            - appliedCents
            - catchUpCents
            - additionalCents
            - balanceCents
            - rows
            properties:
              agency:
                type: string
              year:
                type: integer
              liabilityCents:
                type: integer
                minimum: 0
              withholdingCents:
                type: integer
                minimum: 0
              appliedCents:
                type: integer
                minimum: 0
              catchUpCents:
                type: integer
                minimum: 0
              additionalCents:
                type: integer
                minimum: 0
              balanceCents:
                type: integer
              rows:
                type: array
                minItems: 4
                maxItems: 4
                items:
                  type: object
                  required:
                  - date
                  - amountCents
                  properties:
                    date:
                      type: string
                      format: date
                    amountCents:
                      type: integer
                      minimum: 0
        withholdingMethod:
          type: string
          enum:
          - salary-estimate
          - entered-total
          - actual-and-remaining
        debtExcluded:
          type: number
          minimum: 0
        health:
          type: object
          required:
          - credit
          - repayment
          - deduction
          properties:
            credit:
              type: number
              minimum: 0
            repayment:
              type: number
              minimum: 0
            deduction:
              type: number
              minimum: 0
        funding:
          type: object
          required:
          - employee
          - employer
          - unclassified
          - priorYearCash
          - rollover
          properties:
            employee:
              type: number
              minimum: 0
            employer:
              type: number
              minimum: 0
            unclassified:
              type: number
              minimum: 0
            priorYearCash:
              type: number
              minimum: 0
            rollover:
              type: number
              minimum: 0
        fundingRemaining:
          type: object
          required:
          - employee
          - employer
          properties:
            employee:
              type: number
              minimum: 0
            employer:
              type: number
              minimum: 0
        remainingOwnerWages:
          type: number
          minimum: 0
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    serviceApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Persistent credential for the configured cloud-bookkeeping service principal. The key must carry accountant:* and is accepted only on accountant operations that explicitly list this scheme. Ordinary API keys, and service keys presented to bearer-only operations, are denied.

        '
    refreshSessionCookie:
      type: apiKey
      in: cookie
      name: __Secure-median_refresh
      description: 'Exact production HttpOnly refresh-session cookie. Local non-secure development uses median_refresh.

        '
    passkeyEnrollmentGrantCookie:
      type: apiKey
      in: cookie
      name: __Secure-median_passkey_enrollment
      description: 'Exact production HttpOnly passkey-enrollment grant cookie. Local non-secure development uses median_passkey_enrollment.

        '
    webAuthnCeremonyCookie:
      type: apiKey
      in: cookie
      name: __Secure-median_webauthn
      description: 'Exact production HttpOnly WebAuthn ceremony cookie. Local non-secure development uses median_webauthn.

        '
x-median-quarantined-authorities:
  decision: ADR-0001-model-a
  runtimeStatus: unmounted
  description: 'Migrations 267-272 modeled legal entities as separate company tenants. These paths are not runtime API authority while their preserved accounting math is re-keyed to legal entities inside one company workspace.

    '
  paths:
  - /companies/{companyId}/consolidation-groups
  - /companies/{companyId}/consolidation-groups/{groupId}/versions/{groupVersionId}/report-rollups
  - /companies/{companyId}/consolidation-groups/{groupId}/versions/{groupVersionId}/report-rollups/{rollupId}
  - /companies/{companyId}/consolidation-groups/{groupId}/versions/{groupVersionId}/translation-adjustments
  - /companies/{companyId}/consolidation-groups/{groupId}/versions/{groupVersionId}/translation-adjustments/{adjustmentId}
x-median-demo-parity-customer-surface:
  runtimeStatus: mounted-lifecycle-only
  description: 'v2 customer-app capabilities available to JWT-authenticated members of any active or test company — the v2 app is the product, not a rollout cohort, so no allowlist applies to the markerless path. Production customer calls omit X-Median-App-Surface. Test-company calls may carry X-Median-App-Surface: qa to select the QA bundle; that marker branch alone still requires membership in CUSTOMER_APP_DEMO_PARITY_COMPANY_IDS. An API key, unknown marker, malformed company id, inactive company, missing gate dependency, or failed company lookup receives the standard hidden-resource 404 contract. The held surfaces riding these prefixes (AR/AP, Forecast, Insights) carry their own additional allowlist gate — see x-median-forecast-hold and x-median-ar-ap-hold.

    '
  headerContract: '#/components/parameters/demoParityCustomerAppSurface'
  routePrefixes:
  - /companies/{companyId}/ar
  - /companies/{companyId}/ap
  - /companies/{companyId}/customers
  - /companies/{companyId}/vendors
  - /companies/{companyId}/contracts
  - /companies/{companyId}/receivables
  - /companies/{companyId}/entities
  - /companies/{companyId}/currencies
  - /companies/{companyId}/reporting-scopes
  - /companies/{companyId}/reporting-scopes/{reportingScopeId}/versions/{versionId}/rollups
  - /companies/{companyId}/reporting-scopes/{reportingScopeId}/versions/{versionId}/translation-adjustments
  - /companies/{companyId}/presentation-report-snapshots
  - /companies/{companyId}/reporting-trial-balances


# --- truncated at 32 KB (37 KB total) ---
# Full source: https://artifacts.apis.io/medianfi-com/openapi/medianfi-com-companies-api-openapi.yml