Dotfile Client portal API

openapi: 3.2.0
info:
  title: ⚙️ API specifications Client portal API
  description: Dotfile public API documentation
  version: v1
  contact: {}
servers:
- url: https://api.dotfile.com
  description: Production environment
security:
- DotfileAPIKey: []
tags:
- name: Client Portal
paths:
  /v1/cases/{id}/share-client-portal-link:
    post:
      operationId: client-portal-share-client-portal-link
      summary: Share client portal link
      description: 'Generate an authenticated link to access a client portal for a business contact.


        ---


        #### See also

        Learn more about Cases'
      parameters:
      - name: id
        required: true
        in: path
        description: Id of the case
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientPortalShareLink'
      responses:
        '201':
          description: '**ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPortalShareLinkResponse'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - Make sure the identifier specified in the URL is a valid UUID\n  - Make sure the body payload matches the expected schema\n  - Make sure that the client portal is online\n  - If `business_contact_id` is specified, the individual must belong to the case, be relevant, and have an email address. If not already a business contact, they will be marked as one\n  - If `business_contact_id` is not specified, the case must have a business contact\n  "
        '404':
          description: No case, client portal or business contact can be found.
      tags:
      - Client Portal
  /v1/cases/{id}/complete-client-portal-wait-step:
    post:
      operationId: client-portal-complete-client-portal-wait-step
      summary: Complete client portal wait step
      description: 'On a case in `draft` status, mark wait steps of client portal as completed


        ---


        #### See also

        Learn more about Cases'
      parameters:
      - name: id
        required: true
        in: path
        description: Id of the case
        schema:
          format: uuid
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteClientPortalWaitStepInput'
      responses:
        '200':
          description: '**ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteClientPortalWaitStepResponse'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - Make sure the identifier specified in the URL is a valid UUID\n  - Make sure the body payload matches the expected schema\n  - Case status is not `draft`\n  "
        '404':
          description: No case can be found.
      tags:
      - Client Portal
  /v1/client-portals:
    get:
      operationId: client-portal-get-many
      summary: Return a list of all client portals
      description: '#### See also

        Learn more about Client portals'
      parameters:
      - name: name
        required: false
        in: query
        description: "Filter items by the `name.{operator}` field.  \nYou can use the `eq`, `not_eq`, `like` and `ilike` operators, the `eq` operator being the default."
        schema:
          type: string
      - name: status
        required: false
        in: query
        description: "Filter items by the `status.{operator}` field.  \nYou can use the `eq`, `not_eq`, `in` and `not_in` operators, the `eq` operator being the default.  \nComma separated for multiple values (`in` and `not_in`)."
        schema:
          type: string
          enum:
          - offline
          - online
      - name: default_language
        required: false
        in: query
        description: "Filter items by the `default_language.{operator}` field.  \nYou can use the `eq`, `not_eq`, `like` and `ilike` operators, the `eq` operator being the default."
        schema:
          type: string
      - name: created_at
        required: false
        in: query
        description: "Filter items by the `created_at.{operator}` field.  \nYou can use the `eq`, `not_eq`, `gt`, `gte`, `lt` and `lte` operators, the `eq` operator being the default."
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,3})?(Z|([0-9]{2}:[0-9]{2}))?)?$
          example:
          - '2023-01-31'
          - '2023-01-31T13:30:00Z'
          - '2023-01-31T13:30:00.000Z'
          description: Date (`yyyy-MM-dd` eg `2023-01-31`) or date time (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`) in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
      - name: updated_at
        required: false
        in: query
        description: "Filter items by the `updated_at.{operator}` field.  \nYou can use the `eq`, `not_eq`, `gt`, `gte`, `lt` and `lte` operators, the `eq` operator being the default."
        schema:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,3})?(Z|([0-9]{2}:[0-9]{2}))?)?$
          example:
          - '2023-01-31'
          - '2023-01-31T13:30:00Z'
          - '2023-01-31T13:30:00.000Z'
          description: Date (`yyyy-MM-dd` eg `2023-01-31`) or date time (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`) in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
      - name: sort
        required: false
        in: query
        description: "Use this parameter to sort query results.  \nIf not specified, sorted in _ascending_ order with values of field `created_at`.  \nAvailable fields are `created_at`."
        schema:
          default: created_at
          type: string
        examples:
          created_at:
            summary: Sort by values of the "created_at" field in ascending order
            value: created_at
          created_at_descending:
            summary: Sort by values of the "created_at" field in descending order
            value: created_at.desc
      - name: page
        required: false
        in: query
        description: "Query response is paginated.  \nUse this parameter to choose which page you want to display.  \nPage index starts at 1 (the default)."
        schema:
          default: 1
          type: number
          minimum: 1
      - name: limit
        required: false
        in: query
        description: "Query response is paginated.  \nUse this parameter to choose the number of items per page.  \nLimit defaults to 20, maximum value is 100."
        schema:
          type: number
          default: 20
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: 'List of client portals in the workspace


            **ℹ️ Click to see full payload**'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientPortalList'
        '400':
          description: "The request is either malformed or contain invalid parameters.\n\n  - One or multiple filtering parameters might be malformed. Make sure to use a supported operator and value for each filter.\n  - If specified, make sure the value of the `page` or `limit` query parameter are valid.\n  - Value of the `sort` parameter is invalid. Make sure the field name is supported, the sorting order is correctly specified, and a same field is not used multiple times for sorting.\n  "
      tags:
      - Client Portal
components:
  schemas:
    ClientPortalShareLinkResponse:
      type: object
      properties:
        case_id:
          type: string
          format: uuid
        client_portal_id:
          type: string
          format: uuid
        business_contact:
          $ref: '#/components/schemas/ClientPortalShareLinkResponseBusinessContact'
        link:
          type: string
          format: url
          description: URL to the client portal authenticated for the business contact
        expires_at:
          type: string
          format: date-time
          description: Date time in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`)
      required:
      - case_id
      - client_portal_id
      - business_contact
      - link
      - expires_at
    Pagination:
      type: object
      properties:
        page:
          type: number
          description: Current page number (defined in query parameter)
          default: 1
        limit:
          type: number
          description: Item count per page (defined in query parameter)
          default: 20
        count:
          type: number
          description: Total items count
          example: 42
      required:
      - page
      - limit
      - count
    CompleteClientPortalWaitStepInput:
      type: object
      properties:
        client_portal_id:
          type: string
          format: uuid
          description: Optional client portal id to only complete its own wait step. If not specified, all the wait steps of all client portals will be completed.
        wait_step_key:
          type: string
          description: Optional wait step key to only complete this specific step. If not specified, all the pending wait steps will be completed.
    ClientPortalShareLink:
      type: object
      properties:
        client_portal_id:
          type: string
          format: uuid
        business_contact_id:
          type: string
          format: uuid
          description: 'The business contact needs to exists in the case.


            If the individual is not yet business contact, it will be updated to be marked as such.


            If not specified, the case must have a business contact already and it will be used.'
      required:
      - client_portal_id
    CompleteClientPortalWaitStepResponse:
      type: object
      properties:
        completed_wait_step_keys:
          description: List of wait step keys that were completed
          type: array
          items:
            type: string
      required:
      - completed_wait_step_keys
    ClientPortalList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ClientPortal'
        pagination:
          example:
            page: 1
            limit: 20
            count: 42
          allOf:
          - $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
    ClientPortalShareLinkResponseBusinessContact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
      required:
      - id
      - first_name
      - last_name
      - email
    ClientPortal:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
          enum:
          - offline
          - online
        default_language:
          type: string
          enum:
          - en
          - fr
          - it
          - de
          - es
          - nl
          - pt
          - pl
          - hu
          - ja
          - ko
        url:
          type: string
        updated_at:
          type: string
          format: date-time
          description: "Creation date  \nDate time in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`)"
        created_at:
          type: string
          format: date-time
          description: "Creation date  \nDate time in format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) (`yyyy-MM-ddTHH:mm:ss.S+X` eg `2023-01-31T13:30:00.000Z`)"
      required:
      - id
      - name
      - status
      - default_language
      - url
      - updated_at
      - created_at
  securitySchemes:
    DotfileAPIKey:
      type: apiKey
      in: header
      name: X-DOTFILE-API-KEY
      description: Configure your api key in the Workspace settings
x-uploaded-at: '2026-08-14T14:05:07.336Z'
x-commit-sha: f460fa65a5cc33cf4211bbcee7818f93d5b9e8de