> ## Documentation Index > Fetch the complete documentation index at: https://docs.smokeball.com/llms.txt > Use this file to discover all available pages before exploring further. # Patch a matter > Patches a specified matter. Note: This endpoint can also be used to update a `Lead`, convert `Lead` to `Matter` and change the `Lead`/`Matter` type. See `Matters` documentation for more details on how to use this. The following actions are not supported: - `items` cannot be updated where either `clientIds` and/or `otherSideIds` are being updated - `items` cannot be updated when converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type - `clientRole` cannot be updated, unless converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type - `Matter` cannot be converted back to `Lead` - `splitOriginatingStaffSettings` cannot be updated without also providing `originatingStaffIds` in the same PATCH request - `personAssistingStaffIds` cannot contain `personAssistingStaffId` - `originatingStaffIds` cannot contain `originatingStaffId` - If split originating staff settings are enabled, `originatingStaffIds` and `originatingStaffId` cannot be updated - When updating via `items`, client role items and their sub-items must contain at least one item (cannot be empty), while non-client role items and their sub-items can be empty arrays to remove all items ## OpenAPI ````yaml /openapi.json patch /matters/{matterId} openapi: 3.0.1 info: title: API version: '1.0' 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: [] paths: /matters/{matterId}: patch: tags: - Matters summary: Patch a matter description: "Patches a specified matter.\r\n \r\nNote: This endpoint can also be used to update a `Lead`, convert `Lead` to `Matter` and change the `Lead`/`Matter` type.\r\n \r\nSee `Matters` documentation for more details on how to use this.\r\n\r\nThe following actions are not supported:\r\n\r\n- `items` cannot be updated where either `clientIds` and/or `otherSideIds` are being updated\r\n \r\n- `items` cannot be updated when converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type\r\n \r\n- `clientRole` cannot be updated, unless converting a `Lead` to `Matter` or changing the `Lead`/`Matter` type\r\n \r\n- `Matter` cannot be converted back to `Lead`\r\n \r\n- `splitOriginatingStaffSettings` cannot be updated without also providing `originatingStaffIds` in the same PATCH request\r\n \r\n- `personAssistingStaffIds` cannot contain `personAssistingStaffId`\r\n \r\n- `originatingStaffIds` cannot contain `originatingStaffId`\r\n \r\n- If split originating staff settings are enabled, `originatingStaffIds` and `originatingStaffId` cannot be updated\r\n \r\n- When updating via `items`, client role items and their sub-items must contain at least one item (cannot be empty), while non-client role items and their sub-items can be empty arrays to remove all items" operationId: PatchMatter parameters: - name: matterId in: path required: true schema: type: string format: uuid requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/MatterDto2' application/json: schema: $ref: '#/components/schemas/MatterDto2' application/*+json: schema: $ref: '#/components/schemas/MatterDto2' responses: '202': description: >- When request is accepted. Returns a hypermedia 'Link' object of the matter to be patched. content: application/json: schema: $ref: '#/components/schemas/Link' '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: MatterDto2: type: object properties: externalSystemId: type: string description: External system id for the matter. nullable: true example: EXT01 number: type: string description: Human-friendly number assigned to matter. nullable: true example: FUS-124 matterTypeId: type: string description: "Unique identifier of the matter type associated with the matter.\r\n \r\nMatter types define what information can be saved to the matter, relevant to that area of law and state / location.\r\n \r\nA pre-configured list of matter types can be obtained via the 'GET /mattertypes' API.\r\n \r\n'Lead' matter types are different from the standard matter types used when creating a 'Matter'.\r\n \r\nUse the 'Type' query parameter in the 'GET /mattertypes' API call to get 'Lead' specific matter types." nullable: true example: 009f778f-83df-454a-b344-768a862a7e55 description: type: string description: Brief description of the matter. nullable: true example: This is a brief description for the matter status: type: string description: "Current status of matter.\r\n\r\nPossible values: Open, Pending, Closed, Deleted or Cancelled." nullable: true example: Open dateOpened: type: string description: Date when the matter was opened. This can be backdated if required. format: date-time nullable: true example: '2022-04-23T14:00:00Z' openedDate: type: string description: Date the matter was opened. This can be backdated if required. format: date-time nullable: true example: '2022-04-23T14:00:00Z' closedDate: type: string description: Date the matter was closed. This can be backdated if required. format: date-time nullable: true example: '2022-04-23T14:00:00Z' leadOpenedDate: type: string description: "Date the lead was opened. This can be backdated if required.\r\n\r\nOnly applies if isLead is true." format: date-time nullable: true example: '2022-04-23T14:00:00Z' leadClosedDate: type: string description: "Date the lead was closed. This can be backdated if required.\r\n\r\nOnly applies if isLead is true." format: date-time nullable: true example: '2022-04-23T14:00:00Z' leadClosedReason: type: string description: "Reason the lead was closed.\r\n\r\nOnly applies if isLead is true." nullable: true example: No longer interested referralType: type: string description: "Referral Type of the matter.\r\n\r\nPossible values are different per region." nullable: true example: Google referrerId: type: string description: Contact id of the person that referred the matter. nullable: true example: 97bbe49f-6460-4bfc-b287-34ddfdbb81ef referralAgreementFeeType: type: string description: "The referral agreement fee type.\r\n\r\nPossible values: %, Flat fee, Other" nullable: true referralAgreementFee: type: number description: The referral agreement fee value. format: double nullable: true referralAgreementFeeComment: type: string description: The referral agreement fee comment. nullable: true personResponsibleStaffId: type: string description: Staff id of the person responsible for the matter (if applicable). nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed personAssistingStaffId: type: string description: Staff id of the person assisting in the matter (if applicable). nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed personAssistingStaffIds: type: array items: type: string description: >- Staff ids of the other persons assisting in the matter (if applicable). nullable: true example: - c85d28cb-a760-4627-aa59-0a853c2e65ed originatingStaffId: type: string description: >- Staff id of the originating attorney (if in US) or an Introducer (if in AU) nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed originatingStaffIds: type: array items: type: string description: "Staff ids of the other originating attorneys (if in US) or an Introducer (if in AU)\r\n\r\nRequired when SplitOriginatingStaffSettings is provided and enabled.\r\nThis field must be included when updating SplitOriginatingStaffSettings." nullable: true example: - c85d28cb-a760-4627-aa59-0a853c2e65ed splitOriginatingStaffSettings: allOf: - $ref: '#/components/schemas/SplitMatterStaffSettingsDto' description: >- Settings for splitting originating staff members on a matter. When enabled, this allows distribution of originating staff responsibilities across multiple staff members using either equal splits or custom ratios. The staff IDs specified in SplitMatterStaffs must exactly match the OriginatingStaffIds provided. OriginatingStaffIds must be included in the same request when updating these settings. Validation rules: - OriginatingStaffIds must be provided when this setting is enabled - Staff ratios must sum to 10000 (100%) when using UseRatio split method - RemainderStaffId must be one of the staff members in the SplitMatterStaffs collection - No duplicate staff members allowed nullable: true supervisorStaffId: type: string description: "Staff id of the supervisor of the matter.\r\n\r\nOnly supported in the UK." nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed clientCode: type: string description: "Associates an external client code to this matter.\r\n\r\nOnly supported in AU and UK." nullable: true example: Client A branchId: type: string description: Unique identifier of the associated branch. nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed branchProviderId: type: string description: Unique identifier of the associated branch provider. nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed clientRole: type: string description: "'Client' matter type representative option for the matter.\r\n\r\nRequired and only supported when converting a 'Lead' to 'Matter'." nullable: true example: Buyer isLead: type: boolean description: "Optional boolean flag indicating if matter is a 'Lead'.\r\n \r\nThis must be set to 'false' when converting a 'Lead' to 'Matter'." example: false clientIds: type: array items: type: string description: >- List of unique identifiers of 'Client' contacts associated with the matter. nullable: true otherSideIds: type: array items: type: string description: >- List of unique identifiers of 'OtherSide' contacts associated with the matter. nullable: true items: type: object additionalProperties: type: array items: $ref: '#/components/schemas/MatterItemDto' nullable: true description: Items associated with the matter. 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: {} SplitMatterStaffSettingsDto: type: object properties: isEnabled: type: boolean description: >- Indicates whether the split matter staff settings are enabled or not. splitMatterStaffs: type: array items: $ref: '#/components/schemas/SplitMatterStaffDto' description: List of staff members involved in the split matter settings. nullable: true splitMethod: type: string description: "Method used to split the matter staff.\r\n\r\nPossible values: Unknown, SplitEvenly, UseRatio." nullable: true remainderStaffId: type: string description: >- The unique identifier for the staff member who will handle the remainder of the matter after the split. nullable: true additionalProperties: false MatterItemDto: type: object properties: id: type: string description: Unique identifier of the matter item. nullable: true example: 009f778f-83df-454a-b344-768a862a7e55 contactId: type: string description: "Unique identifier of the associated contact.\r\n\r\nOnly applicable for 'role' matter items." nullable: true example: c85d28cb-a760-4627-aa59-0a853c2e65ed contact: allOf: - $ref: '#/components/schemas/MatterItemContactDto' description: "Associated contact.\r\n\r\nOnly applicable for 'role' matter items." nullable: true roleDescription: type: string description: "Displayed name for the matter item.\r\n \r\nOnly applicable for 'role' matter items." nullable: true description: type: string description: "Description for the matter item.\r\n \r\nOnly applicable for 'role' matter items." nullable: true subItems: type: object additionalProperties: type: array items: $ref: '#/components/schemas/MatterItemDto' nullable: true description: "SubItems associated with the matter item.\r\n\r\nNot applicable for matter sub items." nullable: true additionalProperties: false SplitMatterStaffDto: type: object properties: matterStaffId: type: string description: The unique identifier for the split matter staff. nullable: true matterStaffRatio: type: integer description: The split ratio for the matter staff. format: int64 additionalProperties: false MatterItemContactDto: type: object properties: id: type: string description: Unique identifier of the contact. nullable: true example: 009f778f-83df-454a-b344-768a862a7e55 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 ````