Matters
Create and update Matters
Matter Types
Smokeball comes with a range of pre-configured matter types for different areas of law. These are provided by Smokeball’s internal content team and are not user editable.
A Matter Type defines what information can be saved to the matter, relevant to that area of law and state / location.
When creating a matter in Smokeball we can see
- A list of Matter Types. Here, Financing is a matter type, under the Real Estate category.
- Representative options for the Financing matter type. This specifies who the Smokeball firm is acting for. In other words, who is their client.
Getting a Matter Type
Response
Here the important information to note is the
idandrepresentativeOptionsof the matter type. We’ll need those when creating a matter.
Contacts
In order to successfully create a matter, we’re going to need to provide one or more contacts that are clients and/or other-sides (if applicable).
In Smokeball’s desktop app you can create a contact as a Person, Firm/Business/Organization or Trust. Currently, the API supports the following contact types
- Person
- Company
Creating contacts
To create a client contact you can make the following request which would create a person called ‘Test Contact’.
To create an other-side contact you can make the following request which would create a person called ‘Other Contact’.
Response
Take note of the Contact’s id returned in the response, we’ll need that when creating a matter.
Alternatively, if the contact already exists in Smokeball, you can query it to find it’s id.
Tip
When creating a contact you can pass in an
externalSystemIdif you want to store your own reference id with this contact.
Staff
In Smokeball, staff can be assigned to a lead as the Attorney Responsible or the Person Assisting. The lead list can then be filtered by Attorney responsible, etc.
If you want to specify the Attorney Responsible or Person Assisting when creating a lead via the API, then we will first need to retrieve the staff member’s id.
Response
Creating a matter
Now we have everything we need to create a matter.
Bearer token for user authentication.
Format: Bearer YOUR_ACCESS_TOKEN
Must be application/json for this endpoint.
The matter number.
Can be left blank.
The matter type identifier.
Example: 8aca3574-aecb-4a6f-991d-680861bece1d_IL (the id we found earlier).
Contact Ids associated with the matter. Minimum: 1 client required.
Example: ["9a9ce552-6bee-45e4-8eb1-afe2c18c489f"]
The client’s role in the Matter (e.g., “Borrower”, “Lender”).
If left blank, the default role associated to the matter type will be used.
Example: "Borrower"
The other side’s role in the Matter (e.g., “Borrower”, “Lender”).
Example: "Borrower"
Description of the matter.
Example: "Created via API"
Initial matter status (typically “Open”).
Can be Open, Pending, Closed, Deleted or Cancelled
Example: "Open"
Lead creation date in ISO 8601 format (this can be backdated).
Example: "2020-05-20T04:20:55.035Z"
Staff Id of the primary responsible staff member (optional).
Example: "c85d28cb-a760-4627-aa59-0a853c2e65ed"
Staff Id of the assisting staff member (optional).
Example: "66f7fa24-bb03-4d89-ac28-e19620cc1e45"
Whether the matter is marked as a lead (default: false).
Example: true
Response
The matter is now shown in Smokeball:
Retrieving matters
Retrieving a matter
This is an enhanced version of the endpoint which combines the following APIs:
- Matters API
- MatterItems API
- Roles API
- Relationships API
Response
Most of this information is unchanged from what we passed in when creating the matter. You’ll notice that the clients, other-sides, staff and matter type properties have been expanded as links to resources with more information.
There is also the items collection which we’ll explore in more detail next.
Retrieving multiple matters
This endpoint can be used to sort, filter and retrieve one or more matters.
The endpoint returns a paginated list of matters based on the action/filter paramaters specified in the request.
Use this to limit number of records to be returned. Defaults to 500.
Use this to set offset for the records to be returned.
Use this to filter by matter type identifier.
Use this to filter by the contact identifier.
Use this to filter by current status of the matter. Possible values: Open, Pending, Closed, Deleted or Cancelled
Boolean flag to restrict search to Leads.
Use this to filter by matters updated since a specified time (.net ticks representation of the UTC datetime).
Use this to provide comma separated list of sort fields. Expected format asc/desc(field). Sort fields currently supported: Status, LastUpdated - e.g. asc(Status), desc(LastUpdated)
Use this to provide comma separated list of optional fields to include in the result. Optional fields currently supported: Items.
The matter
itemsfield is not returned by default. Use thefieldsin the request to include this in the result.
Response
Matter Items
A matter can contain various items and sub items that store hierarchical data relevant to that area of law.
The matter items list is ordered as follows:
- Matter Info
- Borrower (Client)
- Client’s Attorney - this is always the Smokeball firm. This relationship is hidden in the desktop UI but can be seen in the API.
- Matter Type
- Lender (Other Side)
- Other Side’s Attorney
- Other Roles, Relationships and Layouts
Matter sub items are shown indented under the matter item. Here Lender is a matter item, and Attorney and Loan Details are its subitems.
Here’s an example request to GET the Matter Items:
Response
Where available, the matter item will have a link to the relevant resource containing additional information.
Some matter items can be hidden on the matter by default. This is usually done for roles that aren’t common on the matter. They are still exposed in the api as “visible: false”. Currently the visibility can only be changed in the Smokeball desktop app under Matter Settings (1).
There are different types of matter items and sub items, including:
Roles and Relationships
A contact on a matter will be assigned to a specific role or relationship, based on how they relate to the matter. For example, in the above image, Test Contact is assigned to the Borrower role (2). By convention, the first Role in the list is the firm’s client. The client role has an Attorney relationship that links to the Smokeball Firm (hidden in the Smokeball UI)
Contacts can also be related to other contacts on the matter. For example in the above image, Lender is a Role with an Attorney relationship (3). This attorney acts for this specific Lender. There could be other Lenders relationships on this matter that are related to other roles (not shown in image)
Roles and relationships can be set in the API.
Layouts
Layouts are data entry screens that are tailored to the area of law. In this example there is a Loan Details layout (4) that would store information about that Lender’s loan. A layout can either be a sub item linked to a matter item (e.g. Loan Details as shown here) or a matter item itself (e.g. Property Details, not shown).
Following is a typical flow to get/set layout data.
- Get the layout design ID and currently set data by retrieving all the layout matter items
or a single layout matter item.
Example response:
- Retrieve the full list of fields for the given layout design.
Example response:
- Update the layout with new data values.
A field with type
Roleexpects an ID of a role. The name of the role needs to be the same as the layout field (e.g. for a field with keyMatter/CaseDetails/StandardCaseDetails/Judgeexpected role name isJudge).
A field with type
DateTimeexpects a UTC date/time in ISO 8601 format (e.g.2021-10-12T13:00:00.0000000Z).
Roles
To find out which contact is assigned to a role, we can get the role details:
Response
Here we can see the Borrower role has a contact assigned, and we can follow the link to the contact resource to find out more details. We can also see that there is an Attorney relationship that links to the Firm resource.
Setting a Role
In our example, the Lender role did not have a contact assigned. To set this, we first need to know the id / link to the role we want to update. This was retrieved earlier with the MatterItems api call:
Response
Let’s say we’ve already created a contact called ‘ABC Lender’ with id dcafdb9e-e46d-4720-a3f8-638b3dd4ca38 and now we want to assign it to this matter in the Lender role
Response
Updating a matter
There are two ways to update a matter.
Using PUT endpoint
This endpoint is similar to the endpoint used to create a new matter.
Response
Limitations:
- The
matterTypeIdfield can only be modified when converting aLeadto aMatter. - The
clientIdsfield cannot be modified. - The
otherSideIdsfield cannot be modified. - The
Mattercannot be converted back toLead.
Using PATCH endpoint (beta)
This endpoint can be used to update specific properties and also supports updating matter items, roles and relationships.
Response
Rule and limitations
The endpoint supports the following actions:
- Updating one or more supported properties (keeping in mind the other rules that follow).
- Converting a lead to a matter - by setting
isLead: true -> isLead: false. - Updating
matterTypeIdandclientRolewhen a lead is being converted to matter. - Updating the clients and/or other sides using the
clientIdsandotherSideIdsproperties. - Updating matter items of provider type
roleandlayoutusing theitemsproperty.
The endpoint does not support the following actions:
- Converting a
Matterback to aLeadis not supported. - Updating
matterTypeIdandclientRoleon matters or on leads that are not being converted to matter is not supported. - Updating
itemsin a patch request where a lead is being converted to a matter is not supported. - Updating
itemsin a patch request where clients and/or other sides are being patched viaclientIdsandotherSideIdsproperties is not supported. - Updating matter
itemsof provider type other thanroleorlayoutis not supported. - Removing all items of a type is not supported.
How updating items works:
- If the
itemsproperty is not passed in, they will be left unchanged. - There is no need to pass items of all types in a patch request.
- If one of more items of a type are being added/updated in the patch request, we must include all relevant items under that type (i.e., including the ones that are unchanged) in order to preserve them. Any existing item that is not included will be removed.
- The consumer cannot update the name on an item, e.g., the Vendor name.
- Contact Id must be provided when adding/update Items of role provider type.
- A new item/sub item of a ‘type’ can only be added if there is an existing item/sub item of that type already present in the lead/matter.
Also see examples in the usage scenarios section below.
Usage scenarios
Common scenarios are described below with clear examples.
Patch request to update the status and description
Patch request to convert lead to matter
Patch request to update the client
There are 2 ways we could do this. The first is to simply set the clientIds property, like so:
Alternatively, we can update the client in the items property, like so:
Patch request to add a new client/item
There are 2 ways we could do this. The first is to simply set the clientIds property, like so:
Alternatively, we can add the role in the items property, like so:
Patch request to remove a client/item
There are 2 ways we could do this. The first is to simply set the clientIds property where the missing items are removed, like so:
The client/item we are removing is omitted from the payload: