> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msportal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update company defaults

> Partially update a company's defaults. Only the provided fields change; null clears a field; array fields and ai_context replace their whole stored value. default_import_role_id is not writable here. Requires `companies.write` and write_settings_companies.



## OpenAPI

````yaml /openapi.json patch /api/public/v1/companies/{id}/defaults
openapi: 3.0.3
info:
  title: MSPortal Public API
  version: 1.0.0
  description: >-
    Public API for MSPortal - provides programmatic access to tenant data.


    ## Authentication


    All endpoints require authentication via API key passed as a Bearer token:


    ```

    Authorization: Bearer <your-api-key>

    ```


    API keys can be created in the MSPortal dashboard under Settings →
    Integrations → API Access.


    **Important:** Do not include cookies in API requests. The public API uses
    stateless authentication only.


    ## Scopes


    API keys are granted specific scopes that determine what operations they can
    perform. Each endpoint documents its required scope(s).


    ## Rate Limiting


    API calls are rate limited per API key. Rate limit information is returned
    in response headers:


    - `X-RateLimit-Limit`: Maximum requests per minute

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: When the rate limit resets (ISO 8601)


    ## Request ID


    All responses include an `X-Request-Id` header for debugging and support.
    You can also pass your own `X-Request-Id` header to correlate requests.
  contact:
    name: MSPortal Support
    email: support@msportal.ai
  license:
    name: Proprietary
servers:
  - url: https://app.msportal.ai
    description: Production (US)
  - url: https://eu.msportal.ai
    description: Production (EU)
security:
  - BearerAuth: []
tags:
  - name: Budgets
    description: >-
      Budget management - create, track, and forecast budgets with line items,
      categories, and products
  - name: Calendar
    description: Calendar and meeting management - events, participants, and meeting types
  - name: Companies
    description: Company management endpoints
  - name: Company Users
    description: Company user management - client portal contacts (read-only, paginated)
  - name: Compliance
    description: Compliance check management - runs, assigned checks, and status updates
  - name: Dashboards
    description: Dashboard management - external iframe resources and internal dashboards
  - name: Devices
    description: Device management - inventory, types, and locations
  - name: Goals
    description: Goal management - create, track, and manage goals with tasks and updates
  - name: NPS Surveys
    description: >-
      NPS survey management - Net Promoter Score surveys, responses, and
      analytics
  - name: Reports
    description: >-
      Report management - create, manage, and schedule reports with templates
      and types
  - name: Planner
    description: >-
      Planner item management - tasks, roadmap items, and project planning with
      linked goals, compliance, and projects
  - name: Surveys
    description: >-
      General survey management - multi-question surveys, responses, and
      statistics
  - name: Tickets
    description: Ticket management - view and filter tickets from PSA integrations
  - name: Training
    description: >-
      Training management - courses, enrollments, certificates, and progress
      tracking
  - name: Users
    description: Tenant user management - internal staff and team members (read-only)
  - name: Automation Rules
    description: >-
      Automation rule management - create, configure, and monitor automation
      rules with triggers, conditions, and actions
  - name: Analytics
    description: >-
      Analytics and reporting - company audit data, training analytics, user
      activity, and portfolio metrics
  - name: Client Onboarding
    description: >-
      Client onboarding - portals (phases, tasks, contacts, activation),
      templates, checklist templates, forms and documentation pages
  - name: Backup
    description: >-
      Backup - summaries, protected devices, alerts and SaaS protection (Datto,
      Axcient, Slide, Kaseya)
  - name: Microsoft 365
    description: Microsoft 365 - licenses, users, domains and Secure Score
  - name: Security
    description: >-
      Security - posture summary, EDR incidents, vulnerabilities, email threats,
      firewalls, DNS filtering and security awareness
  - name: Financial
    description: Financial - quotes, invoices and revenue summaries
  - name: Integrations
    description: Integrations - status, sync health, pause and resume (never credentials)
  - name: Documentation
    description: >-
      Documentation - pages, folders and articles synced from Hudu or IT Glue,
      plus built-in pages
  - name: Broadcasts
    description: Broadcasts - emergency broadcasts, recipients and groups
  - name: Notifications
    description: Notifications - the linked user's in-app notifications
  - name: Standards
    description: >-
      Standards - technology standards catalog, service plans, applicability,
      deployment statuses, compliance rollups, white space and costs
  - name: Customer Success
    description: >-
      Customer success - client health scores, trends, benchmarks and Traffic
      Light Reviews
  - name: Tasks
    description: Tasks - the linked user's personal task list
  - name: Tenant Setup
    description: Tenant setup - profile, branding and portal settings (never secrets)
  - name: Roles
    description: Roles - staff and client roles and their permission grants
  - name: Ticket Templates
    description: Ticket templates - reusable ticket definitions
  - name: Readiness
    description: Client readiness - account readiness assessments
  - name: Projects
    description: >-
      Projects - PSA projects with health overlays (deliverables, milestones,
      client actions, weekly updates), phases, tickets, time entries, PSA
      status/owner/priority write-through, ticket notes, task controls, display
      settings and the document library
paths:
  /api/public/v1/companies/{id}/defaults:
    patch:
      tags:
        - Companies
      summary: Update company defaults
      description: >-
        Partially update a company's defaults. Only the provided fields change;
        null clears a field; array fields and ai_context replace their whole
        stored value. default_import_role_id is not writable here. Requires
        `companies.write` and write_settings_companies.
      parameters:
        - schema:
            type: string
            format: uuid
            description: Company ID
          required: true
          description: Company ID
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCompanyDefaultsRequest'
      responses:
        '200':
          description: Company defaults after the update
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyDefaults'
                required:
                  - data
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Forbidden - missing scope (companies.write), the linked user lacks
            write_settings_companies, or a company user addressed another
            company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    UpdateCompanyDefaultsRequest:
      type: object
      properties:
        email_format:
          type: string
          nullable: true
          maxLength: 500
          description: Email address pattern for new users, e.g. "first.last"
        default_email_domain:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        preferred_contact_method:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        standard_computer_model:
          type: string
          nullable: true
          maxLength: 500
          description: Deprecated alias for standard_laptop_model
        standard_laptop_model:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        standard_desktop_model:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        standard_monitor_model:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        standard_keyboard_model:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        standard_mouse_model:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        exclude_from_global_hardware_defaults:
          type: boolean
          description: >-
            When true, this company does not inherit tenant-wide hardware
            defaults
        other_peripherals:
          type: array
          nullable: true
          items:
            type: string
            minLength: 1
            maxLength: 500
          maxItems: 100
          description: Replaces the whole list; null clears
        standard_software:
          type: array
          nullable: true
          items:
            type: string
            minLength: 1
            maxLength: 500
          maxItems: 100
          description: Replaces the whole list; null clears
        operating_system:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        default_location:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        default_office:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        default_department:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        default_time_zone:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        business_hours:
          type: object
          nullable: true
          properties:
            start:
              type: string
              nullable: true
              maxLength: 50
              description: Max 50 characters; null or "" clears
            end:
              type: string
              nullable: true
              maxLength: 50
              description: Max 50 characters; null or "" clears
            days:
              type: array
              nullable: true
              items:
                type: string
                minLength: 1
                maxLength: 20
              maxItems: 7
          additionalProperties: false
          description: >-
            e.g. {"start":"8:00","end":"17:00","days":["Mon","Tue"]}; unknown
            keys are rejected; null clears
        default_user_type:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        onboarding_checklist:
          type: array
          nullable: true
          items:
            type: string
            minLength: 1
            maxLength: 500
          maxItems: 100
          description: Replaces the whole list; null clears
        vpn_required:
          type: boolean
          nullable: true
          description: null clears
        mfa_required:
          type: boolean
          nullable: true
          description: null clears
        network_access_level:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        security_clearance_required:
          type: boolean
          nullable: true
          description: null clears
        default_ticket_priority:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        default_ticket_urgency:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        default_response_time_hours:
          type: integer
          nullable: true
          minimum: 0
          maximum: 8760
        auto_assign_tickets:
          type: boolean
          nullable: true
          description: null clears
        default_assignee_group:
          type: string
          nullable: true
          maxLength: 500
          description: Max 500 characters; null or "" clears
        company_description:
          type: string
          nullable: true
          maxLength: 10000
          description: Max 10000 characters; null or "" clears
        industry_specific_requirements:
          type: string
          nullable: true
          maxLength: 10000
          description: Max 10000 characters; null or "" clears
        special_instructions:
          type: string
          nullable: true
          maxLength: 10000
          description: Max 10000 characters; null or "" clears
        ai_context:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
          description: >-
            Structured AI reference data for this company (e.g. VIP users,
            escalation contacts). Replaces the whole object; null clears; at
            most 20000 serialized characters.
      description: >-
        Partial update: only provided fields change. The description,
        requirements, instructions and ai_context fields feed the AI assistant;
        write factual reference data only.
    CompanyDefaults:
      type: object
      properties:
        companyId:
          type: string
          format: uuid
        emailFormat:
          type: string
          nullable: true
        defaultEmailDomain:
          type: string
          nullable: true
        preferredContactMethod:
          type: string
          nullable: true
        standardComputerModel:
          type: string
          nullable: true
          description: Deprecated alias of standardLaptopModel
        standardLaptopModel:
          type: string
          nullable: true
        standardDesktopModel:
          type: string
          nullable: true
        standardMonitorModel:
          type: string
          nullable: true
        standardKeyboardModel:
          type: string
          nullable: true
        standardMouseModel:
          type: string
          nullable: true
        excludeFromGlobalHardwareDefaults:
          type: boolean
        hardwareDefaults:
          type: object
          properties:
            laptop:
              $ref: '#/components/schemas/CompanyHardwareDefaultItem'
            desktop:
              $ref: '#/components/schemas/CompanyHardwareDefaultItem'
            monitor:
              $ref: '#/components/schemas/CompanyHardwareDefaultItem'
            keyboard:
              $ref: '#/components/schemas/CompanyHardwareDefaultItem'
            mouse:
              $ref: '#/components/schemas/CompanyHardwareDefaultItem'
          required:
            - laptop
            - desktop
            - monitor
            - keyboard
            - mouse
          additionalProperties:
            nullable: true
          description: Effective hardware standards after tenant inheritance
        otherPeripherals:
          type: array
          nullable: true
          items:
            type: string
        standardSoftware:
          type: array
          nullable: true
          items:
            type: string
        operatingSystem:
          type: string
          nullable: true
        defaultLocation:
          type: string
          nullable: true
        defaultOffice:
          type: string
          nullable: true
        defaultDepartment:
          type: string
          nullable: true
        defaultTimeZone:
          type: string
          nullable: true
        businessHours:
          type: object
          nullable: true
          properties:
            start:
              type: string
              nullable: true
            end:
              type: string
              nullable: true
            days:
              type: array
              nullable: true
              items:
                type: string
        defaultUserType:
          type: string
          nullable: true
        onboardingChecklist:
          type: array
          nullable: true
          items:
            type: string
        vpnRequired:
          type: boolean
          nullable: true
        mfaRequired:
          type: boolean
          nullable: true
        networkAccessLevel:
          type: string
          nullable: true
        securityClearanceRequired:
          type: boolean
          nullable: true
        defaultTicketPriority:
          type: string
          nullable: true
        defaultTicketUrgency:
          type: string
          nullable: true
        defaultResponseTimeHours:
          type: integer
          nullable: true
        autoAssignTickets:
          type: boolean
          nullable: true
        defaultAssigneeGroup:
          type: string
          nullable: true
        companyDescription:
          type: string
          nullable: true
        industrySpecificRequirements:
          type: string
          nullable: true
        specialInstructions:
          type: string
          nullable: true
        aiContext:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
        updatedAt:
          type: string
          nullable: true
      required:
        - companyId
        - emailFormat
        - defaultEmailDomain
        - preferredContactMethod
        - standardComputerModel
        - standardLaptopModel
        - standardDesktopModel
        - standardMonitorModel
        - standardKeyboardModel
        - standardMouseModel
        - excludeFromGlobalHardwareDefaults
        - hardwareDefaults
        - otherPeripherals
        - standardSoftware
        - operatingSystem
        - defaultLocation
        - defaultOffice
        - defaultDepartment
        - defaultTimeZone
        - businessHours
        - defaultUserType
        - onboardingChecklist
        - vpnRequired
        - mfaRequired
        - networkAccessLevel
        - securityClearanceRequired
        - defaultTicketPriority
        - defaultTicketUrgency
        - defaultResponseTimeHours
        - autoAssignTickets
        - defaultAssigneeGroup
        - companyDescription
        - industrySpecificRequirements
        - specialInstructions
        - aiContext
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        requestId:
          type: string
          description: Request correlation ID
        details:
          nullable: true
          description: Additional error details
        code:
          type: string
          description: Error code
      required:
        - error
    CompanyHardwareDefaultItem:
      type: object
      properties:
        modelName:
          type: string
          nullable: true
        source:
          type: string
          description: company, tenant or none
      required:
        - modelName
        - source
      additionalProperties:
        nullable: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Use your API key as a Bearer token. API keys can be generated in
        Settings → Integrations → API Access.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.