openapi: 3.0.1
info:
  title: Smokeball Activity Codes Roles 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: Roles
paths:
  /matters/{matterId}/roles:
    get:
      tags:
      - Roles
      summary: Get roles on a matter
      description: Returns associated roles for a specified matter.
      operationId: GetRolesOnMatter
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'MatterRoles' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatterRoles'
        '404':
          description: When the specified matter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    post:
      tags:
      - Roles
      summary: Add role to a matter
      description: Appends a new role in the specified matter.
      operationId: AddAnotherRoleToMatter
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Version
        in: header
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RoleDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RoleDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RoleDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the role to be created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an invalid role is provided for the specified matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When the specified matter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /matters/{matterId}/roles/{id}:
    get:
      tags:
      - Roles
      summary: Get role on a matter
      description: Returns a role in a specified matter.
      operationId: GetRoleOnMatter
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'Role' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '404':
          description: When the specified matter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - Roles
      summary: Update role on a matter
      description: Updates a specified role on a matter.
      operationId: UpdateRole
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RoleDto'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RoleDto'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RoleDto'
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the role to be updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: When the specified matter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    delete:
      tags:
      - Roles
      summary: Remove role from a matter
      description: Removes a specified role from a matter.
      operationId: RemoveRoleFromMatter
      parameters:
      - name: matterId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: Version
        in: header
        schema:
          type: integer
          format: int32
      responses:
        '202':
          description: When request is accepted. Returns a hypermedia 'Link' object of the role to be deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: When matter does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    RoleDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the role.
          nullable: true
          example: Provider
        displayName:
          type: string
          description: Display Name of the role.
          nullable: true
          example: Medical Provider
        description:
          type: string
          description: Description of the role.
          nullable: true
          example: Client
        contactId:
          type: string
          description: Unique identifier of the contact.
          nullable: true
          example: c85d28cb-a760-4627-aa59-0a853c2e65ed
        representativeIds:
          type: array
          items:
            type: string
          description: List of associated representative contact ids.
          nullable: true
          example:
          - 776e778f-83df-454a-b344-768a862a7e67
        isMatterItemRequired:
          type: boolean
          description: Boolean flag indicating if matter item is required.
        relationships:
          type: array
          items:
            $ref: '#/components/schemas/RelationshipDto'
          description: List if relationships associated with the role.
          nullable: true
      additionalProperties: false
    Role:
      type: object
      properties:
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        id:
          type: string
          description: Unique identifier of the role.
          nullable: true
          example: 009f778f-83df-454a-b344-768a862a7e55
        name:
          type: string
          description: Name of the role.
          nullable: true
          example: Client
        contact:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the associated contact.
          nullable: true
        roleDescription:
          type: string
          description: Name of the role (user editable).
          nullable: true
          example: Head Honcho
        description:
          type: string
          description: Description of the role.
          nullable: true
          example: The person for whom I am working
        representatives:
          type: array
          items:
            $ref: '#/components/schemas/Link'
          description: List of hypermedia links of the associated representatives.
          nullable: true
        relationships:
          type: array
          items:
            $ref: '#/components/schemas/Relationship'
          description: List of associated relationships.
          nullable: true
        isClient:
          type: boolean
          description: Boolean flag indicating if role belongs to a 'Client'.
          example: false
        isOtherSide:
          type: boolean
          description: Boolean flag indicating if role belongs to an 'OtherSide'.
          example: false
      additionalProperties: false
    MatterRoles:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        versionId:
          type: string
          description: Version id of the record.
          nullable: true
          example: 832e778f-83df-454a-b344-768a862a7e67
        matterId:
          type: string
          description: Matter id.
          nullable: true
          example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: List of associated roles.
          nullable: true
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    RelationshipDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the relationship.
          nullable: true
          example: Provider
        displayName:
          type: string
          description: Display Name of the relationship.
          nullable: true
          example: Medical Provider
        contactId:
          type: string
          description: Unique identifier of the contact.
          nullable: true
          example: c85d28cb-a760-4627-aa59-0a853c2e65ed
        representativeIds:
          type: array
          items:
            type: string
          description: List of associated representative contact ids.
          nullable: true
          example:
          - 776e778f-83df-454a-b344-768a862a7e67
        isMatterItemRequired:
          type: boolean
          description: Boolean flag indicating if a matter item is required.
      additionalProperties: false
    Relationship:
      type: object
      properties:
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        id:
          type: string
          description: Unique identifier of the relationship.
          nullable: true
          example: 009f778f-83df-454a-b344-768a862a7e55
        name:
          type: string
          description: Name of the relationship.
          nullable: true
          example: Solicitor
        contact:
          allOf:
          - $ref: '#/components/schemas/Link'
          description: Hypermedia link of the associated contact.
          nullable: true
        representatives:
          type: array
          items:
            $ref: '#/components/schemas/Link'
          description: List of hypermedia links of the associated representatives.
          nullable: true
      additionalProperties: false
  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