openapi: 3.0.0
info:
  title: Accounts API
  description: REST API to manage accounts.
  version: 2.0.0
  contact:
    name: API Support
    url: https://www.watchguard.com/wgrd-support/contact-support
  termsOfService: 
    https://www.watchguard.com/help/docs/api/Content/en-US/license_agreement.html?cshid=18007
paths:
  /health:
    get:
      description: Checks API health.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthResponse'
  /v2/accounts/{accountId}/children:
    get:
      tags:
        - Accounts
      summary: Retrieves a list of managed accounts.
      description: Retrieves a list of managed accounts. Results can be filtered
        by account *type*, *name*, and delegation status, and can be sorted and 
        paginated.
      parameters:
        - name: accountId
          in: path
          description: >-
            Your WatchGuard Cloud account ID. For example, WGC-1-123abc456 or ACC-1234567.
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: |
            Specifies the type of account to return. Default: 0. Allowed values:
              - 0 - All accounts.
              - 1 - Service Provider accounts.
              - 2 - Subscriber accounts.
          required: false
          schema:
            type: integer
            enum:
              - 0 # Returns all accounts.
              - 1 # Returns Service Provider accounts.
              - 2 # Returns Subscriber accounts.
            default: 0
        - name: sortBy
          in: query
          description: |
            Specifies the field to sort results by. Default: `name`. Allowed values:
              - `name` - Sorts results by account name.
              - `type` - Sorts results by account type.
          required: false
          schema:
            type: string
            enum:
              - name
              - type
            default: name
        - name: sortOrder
          in: query
          description: |
            Specifies the sort order. Default: `asc`. Allowed values:
              - `asc` - Shows results in ascending order.
              - `desc` - Shows results in descending order.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: offset
          in: query
          description: 'Specifies the number of the first record to include in the
            results. Default: 0.'
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          description: |
            Maximum number of accounts to return in the response. Default: 25. A value of -1 returns all records.
          required: false
          schema:
            type: integer
            default: 25
            minimum: -1
        - name: name
          in: query
          description: Specifies the account name to search for. Supports 
            partial or full matches. If not specified, all accounts are 
            returned.
          required: false
          schema:
            type: string
        - name: includeDelegatedAccounts
          in: query
          description: |
            Specifies whether to retrieve delegated accounts. Default: false. Allowed values:
            - true - Retrieves delegated accounts.
            - false - Excludes delegated accounts.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listChildAccountsResponse'
        default:
          description: Error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /v2/accounts/{accountId}:
    get:
      tags:
        - Accounts
      summary: Retrieves account information.
      description: Retrieves information for the specified account.
      parameters:
        - name: accountId
          in: path
          description: >-
            Your WatchGuard Cloud account ID. For example, WGC-1-123abc456 or ACC-1234567.
          required: true
          schema:
            type: string
        - name: fields
          in: query
          description: |
            Specifies one or more comma-separated account field names in the *fields* parameter to return specific information about the specified WatchGuard Cloud account. If not specified, all fields are returned. For example, /v2/accounts/ACC-1234567?fields=contacts,addresses,industry.
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
      responses:
        '200':
          description: Account information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAccountInfoResponse'
        default:
          description: Error response.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    post:
      tags:
        - Accounts
      summary: Creates a managed account.
      description: >-
        Creates a managed account. All request fields are required, including contact
        phone, billing and mailing addresses, and industry classification.
      parameters:
        - name: accountId
          in: path
          description: >-
            Your WatchGuard Cloud account ID. For example, ACC-1234567.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createAccountRequest'
      responses:
        '200':
          description: Account information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createAccountResponse'
        default:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    delete:
      tags:
        - Accounts
      summary: Deletes the specified account.
      description: Deletes a managed account.
      parameters:
        - name: accountId
          in: path
          description: >-
            Your WatchGuard Cloud account ID. For example, WGC-1-123abc456 or ACC-1234567.
          required: true
          schema:
            type: string
        - in: query
          name: force
          description: |
            Specifies whether to delete the account if it manages other accounts. Default: false. Allowed values:
              - true - Deletes the account and any accounts it manages.
              - false - Retains all accounts.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: The account and its managed accounts were successfully 
            deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deleteAccountResponse'
        '204':
          description: The account was successfully deleted.
        default:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
    patch:
      tags:
        - Accounts
      summary: Updates the specified managed account.
      description: >-
        Updates a managed account. All request fields are required, including contact
        phone, billing and mailing addresses, and industry classification.
      parameters:
        - name: accountId
          in: path
          description: >-
            Identifies the WatchGuard Cloud account to be updated. Example: WGC-1234567.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateAccountRequest'
      responses:
        '204':
          description: The account was successfully updated.
        default:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    errorResponse:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: An absolute URI that identifies the type of error.
          default: about:blank
        title:
          type: string
          description: A descriptive title for the error.
        status:
          type: integer
          description: HTTP status code the server returns.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: A description of the error.
          example: Connection to the database timed out.
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the error.
    healthResponse:
      type: object
      required:
        - healthy
      properties:
        healthy:
          type: boolean
          default: false
        message:
          type: string
    childAccount:
      type: object
      properties:
        accountId:
          description: Your WatchGuard Cloud account ID.
          type: string
        name:
          description: Specifies the name of the managed account.
          type: string
        type:
          description: |
            Indicates the type of WatchGuard Cloud account. 
            - 1: Tier-n Service Provider
            - 2: Tier-n Subscriber
            - 3: Tier-1 Service Provider
            - 4: Tier-1 Subscriber
          type: integer
        parentAccess:
          description: Indicates whether the Service Provider has access to the 
            managed account.
          type: boolean
        relationType:
          description: Indicates the relationship between the Service Provider 
            and the managed account.
          type: string
        relationName:
          description: Specifies the name of the relationship between the 
            Service Provider and the managed account.
          type: string
        totalOperators:
          description: Specifies the number of operators the account has.
          type: integer
        childrenList:
          description: Lists the managed accounts for the Service Provider.
          type: array
          items:
            $ref: '#/components/schemas/childAccount'
    listChildAccountsResponse:
      description: List of managed accounts.
      type: object
      properties:
        items:
          description: Lists information about your managed accounts.
          type: array
          items:
            $ref: '#/components/schemas/childAccount'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    pageControls:
      description: Settings that specify how to paginate search results.
      type: object
      properties:
        limit:
          description: Maximum number of accounts to return in the response. A 
            value of -1 returns all records.
          type: integer
        offset:
          description: Specifies the number of the first record to include in 
            the results.
          type: integer
        totalItems:
          description: Specifies the total number of records available.
          type: integer
    getAccountInfoResponse:
      description: Account information.
      type: object
      required:
        - accountInfo
      properties:
        accountInfo:
          $ref: '#/components/schemas/account'
    account:
      type: object
      description: Account information.
      required:
        - accountId
        - type
        - name
        - status
        - industry
      properties:
        accountId:
          type: string
          description: WatchGuard Cloud account ID of the managed account.
        type:
          description: |
            Type of WatchGuard Cloud account. 
            - 1: Tier-n Service Provider
            - 2: Tier-n Subscriber
            - 3: Tier-1 Service Provider
            - 4: Tier-1 Subscriber
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
        name:
          description: Specifies the name of the account.
          type: string
        status:
          description: |
            Indicates the status of the account. Allowed values: 0 (inactive), 1 (active).
          type: integer
          format: int64
          enum:
            - 0
            - 1
        industry:
          description: Industry classification for the account.
          type: string
          enum:
            - Government/State Owned
            - Private or Publicly Traded Company (not gov't owned) / Sole 
              Proprietor
        contacts:
          description: List of contacts for the account.
          type: array
          items:
            $ref: '#/components/schemas/contact'
        delegatedParent:
          $ref: '#/components/schemas/delegatedParent'
        addresses:
          type: object
          properties:
            mailingAddress:
              $ref: '#/components/schemas/address'
            billingAddress:
              $ref: '#/components/schemas/address'
        serviceProperties:
          type: object
          properties:
            ssourlname:
              type: string
              description: Specifies the identifier used for Single Sign-On 
                (SSO).
        parent:
          type: object
          description: Service Provider account information.
          required:
            - id
          properties:
            id:
              type: string
              description: WatchGuard Cloud account ID of the Service Provider 
                that manages this account.
              default: WGC
            access:
              type: boolean
              description: Indicates whether the Service Provider has access to 
                managed accounts.
              default: false
    delegatedParent:
      type: object
      properties:
        id:
          type: string
          description: WatchGuard Cloud account ID of the Service Provider that 
            manages this delegated account.
        expirationDate:
          type: string
          description: Date that delegated access ends.
        name:
          type: string
          description: Name of the Service Provider account that manages this 
            delegated account.
        phone:
          type: string
          description: Phone number of the Service Provider account that manages
            this delegated account.
        email:
          type: string
          description: Email address of the Service Provider account that 
            manages this delegated account.
    address:
      type: object
      description: Address.
      required:
        - address1
        - city
        - country
        - state
        - postalCode
      properties:
        address1:
          type: string
          description: Primary street address.
        address2:
          type: string
          description: Secondary street address.
        city:
          type: string
          description: City name.
        state:
          type: string
          description: State or province.
        country:
          type: string
          description: Country name.
        postalCode:
          type: string
          description: Zip or postal code.
    contact:
      type: object
      description: Contact details.
      required:
        - firstName
        - lastName
        - email
      properties:
        primaryContactId:
          type: string
          description: Unique ID that identifies this contact.
        firstName:
          type: string
          description: First name of the primary contact.
        lastName:
          type: string
          description: Last name of the primary contact.
        email:
          type: string
          description: Email address of the primary contact.
        phone:
          type: string
          description: Phone number of the primary contact.
    createAccountRequest:
      type: object
      description: Request body to create a new managed account.
      required:
        - type
        - name
        - firstName
        - lastName
        - email
        - phone
        - billingAddress
        - mailingAddress
        - industry
      properties:
        type:
          description: |
            Type of account to create. This can be one of these values:
              - 1 - Service Provider.
              - 2 - Subscriber.
          type: integer
          enum:
            - 1
            - 2
        name:
          description: Specifies the name of the new account.
          type: string
        firstName:
          type: string
          description: First name of the primary contact.
        lastName:
          type: string
          description: Last name of the primary contact.
        email:
          type: string
          description: Email address of the primary contact.
        phone:
          type: string
          description: Phone number of the primary contact.
        industry:
          description: Industry classification for the account.
          type: string
          enum:
            - Government/State Owned
            - Private or Publicly Traded Company (not gov't owned) / Sole 
              Proprietor
        billingAddress:
          $ref: '#/components/schemas/addressInput'
        mailingAddress:
          $ref: '#/components/schemas/addressInput'
    updateAccountRequest:
      type: object
      description: Request body to update a managed account.
      required:
        - name
        - firstName
        - lastName
        - email
        - phone
        - billingAddress
        - mailingAddress
        - industry
      properties:
        name:
          type: string
          description: Specifies the name of the updated account.
        firstName:
          type: string
          description: First name of the primary contact.
        lastName:
          type: string
          description: Last name of the primary contact.
        email:
          type: string
          description: Email address of the primary contact.
        phone:
          type: string
          description: Phone number of the primary contact.
        industry:
          description: Industry classification for the account.
          type: string
          enum:
            - Government/State Owned
            - Private or Publicly Traded Company (not gov't owned) / Sole 
              Proprietor
        billingAddress:
          $ref: '#/components/schemas/addressInput'
        mailingAddress:
          $ref: '#/components/schemas/addressInput'
    addressInput:
      type: object
      description: Billing or mailing address for account create and update 
        requests.
      required:
        - address1
        - city
        - country
        - zipcode
      properties:
        address1:
          type: string
          description: Primary street address.
        address2:
          type: string
          description: Secondary street address.
        city:
          type: string
          description: City name.
        state:
          type: string
          description: State or province.
        country:
          type: string
          description: Country code.
        zipcode:
          type: string
          description: Zip or postal code.
    createAccountResponse:
      type: object
      description: WatchGuard Cloud account ID of the newly created account.
      required:
        - accountId
      properties:
        accountId:
          type: string
          description: Created WatchGuard Cloud account ID.
          example: WGC-1-123abc456
    deleteAccountResponse:
      type: object
      description: List of deleted managed accounts.
      properties:
        childIds:
          type: array
          items:
            type: string
            description: WatchGuard Cloud account ID of the deleted account.
            example: WGC-1-123abc456
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: WatchGuard-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
servers:
  - url: https://api.usa.cloud.watchguard.com/rest/platform/accounts
    description: Prod USA Region
  - url: https://api.deu.cloud.watchguard.com/rest/platform/accounts
    description: Prod DEU region
  - url: https://api.jpn.cloud.watchguard.com/rest/platform/accounts
    description: Prod JPN region
security:
  - ApiKeyAuth: []
    BearerAuth: []
externalDocs:
  description: Additional documentation
  url: https://www.watchguard.com/help/docs/api/Content/en-US/home.html
