> ## 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. # Get matters > Returns a list of matters. To return leads, set the `isLead` search option to true. ## OpenAPI ````yaml /openapi.json get /matters 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: get: tags: - Matters summary: Get matters description: >- Returns a list of matters. To return leads, set the `isLead` search option to true. operationId: GetMatters parameters: - name: Offset in: query schema: maximum: 2147483647 minimum: 0 type: integer format: int32 - name: Limit in: query schema: maximum: 500 minimum: 1 type: integer format: int32 - name: Search in: query description: "Filter matters by specified search term.\r\nThis field is wide reaching, it is used to search by clients, othersides, description and matter numbers." schema: type: string example: Bob example: Bob - name: MatterTypeId in: query description: Filter by matter type identifier. schema: type: string example: 009f778f-83df-454a-b344-768a862a7e55 example: 009f778f-83df-454a-b344-768a862a7e55 - name: ContactId in: query description: Filter by the contact identifier. schema: type: string example: 7fdbdd5b-0f5e-4095-af9e-ae5b055325c7 example: 7fdbdd5b-0f5e-4095-af9e-ae5b055325c7 - name: Status in: query description: "Filter by current status of the matter.\r\n\r\nPossible values: Open, Pending, Closed, Deleted or Cancelled." schema: type: array items: type: string - name: IsLead in: query description: "Boolean flag to return 'Leads'. This is false by default.\r\n\r\nA Lead is a potential matter that has not yet been converted to a full matter. The data structure of a lead is similar to a matter, but with some small variances." schema: type: boolean example: true deprecated: true example: true - name: Type in: query description: "Type of matter to search for. This is set to Matters by default. \r\n \r\nA Lead is a potential matter that has not yet been converted to a full matter. The data structure of a lead is similar to a matter, but with some small variances.\r\n \r\nPossible values: \"Matters\", \"Leads\", \"Matters,Leads\"." schema: type: string example: Leads example: Leads - name: UpdatedSince in: query description: "Filter by matters updated since a specified time (.net ticks representation of the UTC datetime). Cannot be used in conjunction with `LastUpdated`.\r\n\r\nThis field will not be supported in future, please use LastUpdated instead." schema: type: integer format: int64 example: 637873555398585000 example: 637873555398585000 - name: LastUpdated in: query description: >- Filter by last updated date of matter. Cannot be used in conjunction with `UpdatedSince`. schema: type: string format: date-time example: '2022-04-23T14:00:00Z' example: '2022-04-23T14:00:00Z' - name: Sort in: query description: ' Available fields: status, lastUpdated' schema: type: string - name: Fields in: query description: ' Available fields: items, tags' schema: type: string responses: '200': description: >- When request is successful. Returns a paged collection of 'Matter' objects. content: application/json: schema: $ref: '#/components/schemas/MatterPagedCollection' components: schemas: MatterPagedCollection: 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 value: type: array items: $ref: '#/components/schemas/Matter' nullable: true offset: type: integer format: int32 nullable: true limit: type: integer format: int32 nullable: true size: type: integer format: int64 first: allOf: - $ref: '#/components/schemas/Link' nullable: true previous: allOf: - $ref: '#/components/schemas/Link' nullable: true next: allOf: - $ref: '#/components/schemas/Link' nullable: true last: allOf: - $ref: '#/components/schemas/Link' 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 Matter: 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 matter. nullable: true example: b471682e-fa17-4e46-b7fe-9b2b8fdcb3c2 externalSystemId: type: string description: External system id for the matter. nullable: true example: EXT01 versionId: type: string description: >- Version id of the record. This can be used in the UpdatedSince query parameter. nullable: true example: '637771038395217729' number: type: string description: Human-friendly number assigned to matter. nullable: true example: FUS-124 title: type: string description: Title of the matter. nullable: true example: AM-0323-0005 - Smith - Sale - Jones matterType: allOf: - $ref: '#/components/schemas/Link' description: Hypermedia link of the associated matter type. nullable: true clients: type: array items: $ref: '#/components/schemas/Link' description: >- List of hypermedia links of 'Client' contacts associated with the matter. nullable: true otherSides: type: array items: $ref: '#/components/schemas/Link' description: >- List of hypermedia links of 'OtherSide' contacts associated with the matter. nullable: true 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 the matter.\r\n\r\nPossible values: Open, Pending, Closed, Deleted or Cancelled." nullable: true example: Open personResponsible: allOf: - $ref: '#/components/schemas/Link' description: >- Hypermedia link of the person responsible for the matter (if applicable). nullable: true personAssisting: allOf: - $ref: '#/components/schemas/Link' description: >- Hypermedia link of the person assisting in the matter (if applicable). nullable: true personAssistingStaffs: type: array items: $ref: '#/components/schemas/Link' description: >- List of hypermedia links of additional person assisting staff members associated with the matter. nullable: true originatingStaff: allOf: - $ref: '#/components/schemas/Link' description: >- Hypermedia link of the originating attorney (if in US) or introducer (if in AU) of the matter. nullable: true originatingStaffs: type: array items: $ref: '#/components/schemas/Link' description: >- List of hypermedia links of additional originating (if in US) or introducer (if in AU) staff members associated with the matter. nullable: true splitOriginatingStaffSettings: allOf: - $ref: '#/components/schemas/SplitMatterStaffSettings' description: Settings for splitting originating staff members on a matter. nullable: true supervisor: allOf: - $ref: '#/components/schemas/Link' description: "Hypermedia link of the supervisor of the matter.\r\n\r\nOnly supported in the UK." nullable: true 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 openedDate: type: string description: Date the matter was opened. format: date-time nullable: true example: '2022-04-23T14:00:00Z' closedDate: type: string description: Date the matter was closed. format: date-time nullable: true example: '2022-04-23T14:00:00Z' leadOpenedDate: type: string description: "Date the lead was opened.\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.\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 isLead: type: boolean description: Boolean flag indicating if the matter is a lead. example: false branch: allOf: - $ref: '#/components/schemas/Link' description: Hypermedia link of the associated branch. nullable: true branchProviderId: type: string description: Unique identifier of the associated branch provider. nullable: true example: Smokeball referralType: type: string description: The referral type of the matter. nullable: true referrer: allOf: - $ref: '#/components/schemas/Link' description: The referrer contact of the matter. nullable: true referralAgreementFeeType: type: string description: The referral agreement fee type. 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 items: type: object additionalProperties: type: array items: $ref: '#/components/schemas/IMatterItem' nullable: true description: Items associated with the matter. nullable: true tags: type: array items: $ref: '#/components/schemas/MatterTag' description: Tags associated with the matter. nullable: true additionalProperties: false SplitMatterStaffSettings: 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/SplitMatterStaff' 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 IMatterItem: type: object properties: type: type: string description: Type of the matter item. nullable: true readOnly: true example: role or layout id: type: string description: Unique identifier of the matter item. nullable: true example: 009f778f-83df-454a-b344-768a862a7e55 name: type: string description: Name of the matter item as it appears on the matter. nullable: true example: Vendor subItems: type: object additionalProperties: type: array items: $ref: '#/components/schemas/IMatterItem' nullable: true description: >- Subitems associated to the matter item. These items vary depending on the matter. nullable: true additionalProperties: false MatterTag: 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 tag. nullable: true example: a15086f5-4da7-4271-8fea-b24d479ced2b type: type: string description: Tag type. example: Staff name: type: string description: Name of the tag. nullable: true example: '' color: type: string description: |- Color associated with the tag. Defaults to 'Brown' if not specified. nullable: true example: Light Blue staff: allOf: - $ref: '#/components/schemas/Link' description: >- Link to staff. Available when `P:MatterManagement.Api.Shared.Resources.MatterTag.Type` is `F:MatterManagement.Api.Shared.Resources.MatterTagType.Staff`. nullable: true additionalProperties: false SplitMatterStaff: 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 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 ````