Smokeball Portal API

openapi: 3.2.0
info:
  title: Smokeball Activity Codes Portal API
  version: '1.0'
  description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
  contact:
    name: Smokeball Developer Support
    url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
  x-api-id: smokeball
  x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
  token: []
tags:
- name: Portal
paths:
  /matters/{matterId}/portal/tasks:
    post:
      tags:
      - Portal
      summary: Creates a portal task
      description: Creates a new client portal task associated with the specified matter.
      operationId: CreatePortalTaskAsync
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PortalTaskDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PortalTaskDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PortalTaskDto'
        required: true
      responses:
        '202':
          description: When request is accepted. Returns the id of the task to be created.
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the authenticated account does not have access to the matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When matter with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/portal/messages:
    post:
      tags:
      - Portal
      summary: Sends a portal message
      description: "Sends a message to the specified contact on the client portal. \n\nWhen using the Client Credentials grant type, include the UserId header to impersonate\nthe lawyer in the firm who is sending the message."
      operationId: SendPortalMessageAsync
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PortalMessageDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PortalMessageDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PortalMessageDto'
      responses:
        '202':
          description: When request is accepted.
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the authenticated account does not have access to the matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When matter with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/portal/tasks/{taskId}:
    patch:
      tags:
      - Portal
      summary: Patch a portal task
      description: Updates a client portal task.
      operationId: PatchPortalTaskAsync
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: taskId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PatchPortalTaskDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PatchPortalTaskDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/PatchPortalTaskDto'
      responses:
        '202':
          description: When request is accepted. Returns the id of the task to be updated.
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: When the authenticated account does not have access to the matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When matter with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    PatchPortalTaskDto:
      type: object
      properties:
        externalUserId:
          type:
          - string
          - 'null'
          description: The optional external user identifier of the external system.
        title:
          type:
          - string
          - 'null'
          description: The title of the task to be displayed in the UI.
          example: 'Sign: Verification of Identity'
        url:
          type:
          - string
          - 'null'
          description: The URL that will be displayed within the task content.
          example: http://www.yourwebsite.com
        actionText:
          type:
          - string
          - 'null'
          description: "Optional action text, a single word to describe the action the task relates to. \n\nDefaults to \"Complete\", but other examples could be \"Sign\" or \"Review\"."
          example: Complete
        cancelled:
          type:
          - boolean
          - 'null'
          description: Whether the task is Cancelled
          example: true
        cancelledText:
          type:
          - string
          - 'null'
          description: Optional cancelled text, used on the task cancelled screen if provided.
          example: Signing Cancelled!
        cancelledUrl:
          type:
          - string
          - 'null'
          description: 'Optional cancelled URL, which is a URL that is loaded in the task content body instead of the default cancelled screen if provided.


            This option overrides CancelledText if provided.'
          example: http://www.yourwebsite.com
        completed:
          type:
          - boolean
          - 'null'
          description: Whether the task is Completed
          example: true
        completedText:
          type:
          - string
          - 'null'
          description: Optional completed text, used on the task success screen if provided.
          example: Signing Complete!
        completedUrl:
          type:
          - string
          - 'null'
          description: 'Optional completed URL, which is a URL that is loaded in the task content body instead of the default success screen if provided.


            This option overrides CompletedText if provided.'
          example: http://www.yourwebsite.com
        expired:
          type:
          - boolean
          - 'null'
          description: Whether the task is Expired
          example: true
        expiredText:
          type:
          - string
          - 'null'
          description: Optional expired text, used on the task expired screen if provided.
          example: Signing Expired!
        expiredUrl:
          type:
          - string
          - 'null'
          description: 'Optional expired URL, which is a URL that is loaded in the task content body instead of the default expired screen if provided.


            This option overrides ExpiredText if provided.'
          example: http://www.yourwebsite.com
      additionalProperties: false
    PortalMessageDto:
      required:
      - message
      type: object
      properties:
        contactId:
          type: string
          description: Unique identifier of the contact.
          format: uuid
          example: 93421c6f-40bd-465d-bb95-3b3b5e200e30
        message:
          minLength: 1
          type: string
        requireMFA:
          type: boolean
          description: Whether MFA is required before showing the message content.
          example: true
      additionalProperties: false
    PortalTaskDto:
      required:
      - externalUserId
      - title
      - url
      type: object
      properties:
        contactId:
          type:
          - string
          - 'null'
          description: Unique identifier of the contact.
          format: uuid
          example: 93421c6f-40bd-465d-bb95-3b3b5e200e30
        email:
          type:
          - string
          - 'null'
          description: Email address of the contact. If provided, this takes precedence over ContactId.
          example: contact@example.com
        externalUserId:
          minLength: 1
          type: string
          description: The optional external user identifier of the external system.
        title:
          minLength: 1
          type: string
          description: The title of the task to be displayed in the UI.
          example: 'Sign: Verification of Identity'
        url:
          minLength: 1
          type: string
          description: The URL that will be displayed within the task content.
          example: http://www.yourwebsite.com
        requireMFA:
          type: boolean
          description: Whether MFA is required before showing the task content.
        optional:
          type: boolean
          description: 'Whether the task is "Required" or "Optional".


            Optional tasks appear in a separate section in the UI.'
        actionText:
          type:
          - string
          - 'null'
          description: "Optional action text, a single word to describe the action the task relates to. \n\nDefaults to \"Complete\", but other examples could be \"Sign\" or \"Review\"."
          example: Complete
        completedText:
          type:
          - string
          - 'null'
          description: Optional completed text, used on the task success screen if provided.
          example: Signing Complete!
        completedUrl:
          type:
          - string
          - 'null'
          description: 'Optional completed URL, which is a URL that is loaded in the task content body instead of the default success screen if provided.


            This option overrides CompletedText if provided.'
          example: http://www.yourwebsite.com
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
  securitySchemes:
    api-key:
      type: apiKey
      name: x-api-key
      in: header
    token:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools