LegalSuite API Documentation
Connect to a LegalSuite database in a secure environment.
Introduction
LegalSuite is a Windows-based program designed to assist Attorneys in managing their legal practices. It is written in Clarion and .Net and uses the MS SQL database to store the program’s data. It also provides an API to allow 3rd party programs to access the data.
This document serves to explain how to use the LegalSuite API to connect to a LegalSuite database and retrieve data and (optionally) save, update and delete data.
Calls are made to our API at https://api.legalsuite.net/ using an API Key
The API Key serves to not only authenticate the request but also to point the request at a specific LegalSuite Database.
{
"data": [{
"recordid": "71017",
"fileref": "0001/0001",
"description": "Kelvin Test",
"clientid": "28787",
"docgenid": "5",
"mattertypeid": "5",
"documentlanguageid": "1",
"employeeid": "69",
...
}]
}
Getting Started
To use the LegalSuite API you will need to be registered as a Developer and recieve a Developer Key. Please contact us to register as a Developer.
This Developer Key is used by the API to identify the Developer. This must be sent in the first request with the LegalSuite Employee's LoginId and Password.
The LegalSuite Employee's LoginId and Password are the same as those used to login to LegalSuite itself.
{
"apikey": "8jjh70XcSkzVvqOe1...",
"employee": {
"recordid": "1034",
"name": "Kobus",
"loginid": "Kobus Smith",
"email": "kobus@Attorney.co.za",
"suspendedflag": "0",
"supervisorflag": "1",
...
}
If the login is successful, an API Key will be returned in the response.
This API Key is then used in all subsequent queries to the API.
Note: Not all LegalSuite clients allow access to their databases via the API.
To enable access via the API, a LegalSuite client needs to register with the API and grant specific rights to each Developer.
See Registering a Client below.
Postman
Postman is a free to use 3rd Party application that can be used to build and Test API Queries.
We have also built a library of all the API example queries in this documentation for easy access.
Once you have Postman set up, click the Run In Postman button below to add all these queries to the application.
Note: These queries are linked to a demo API key which only has read access test environment.
Retrieving Data
You can retrieve data from the LegalSuite Database by querying a Table or a View
Tables queries provide full CRUD (Create, Read, Update and Delete) functionality, while views only offer read access.
Although the LegalSuite API offers CRUD Functionality, some Developers are only granted Read Access - depending on the scope of their Application.
Retrieve All FileNotes
{
"data": [{
"recordid": "6615999",
"matterid": "942",
"docfilenoteid": "2",
...
},
{,
"recordid": "6616000",
"matterid": "945",
"docfilenoteid": "5",
...
}]
}
Get a Single FileNote (with RecordID 610024)
{
"data": [{
"recordid": "610024",
"matterid": "145",
"docfilenoteid": "1",
...
}]
}
Create a New FileNote
{
"data": [{
"recordid": "621111",
"matterid": "71017",
"docfilenoteid": "0",
...
}]
}
Update a FileNote (with the RecordID 621111)
{
"data": [{
"recordid": "621111",
"matterid": "71017",
"docfilenoteid": "35",
...
}]
}
Delete a FileNote (with the RecordID 621111)
{
"data": []
}
Creating SQL Views and retreiving data from Views
The API not only allows you to retrieve data from a View, but also you to create your own SQL Views
This is done by including the view name and SQL Script in the body of the request to :
https://api.legalsuite.net/createview
Note: If the view exist, it will be replaced therefore it is important to prefix your Application Name to any Views you create to ensure they do not clash with any existing Views and are also easily identifiable.
Creating a View
{
"success": [{
"You may access the view at api.legalsuite.net/AppNameStageCodeListView/get"
}]
}
Once the view is successfully created the API will give you a response with the URL to retrieve data from this view.
All of the customizing you are able to perform on normal tables you are also able to apply to SQL views.
Retrieving data from a View
{
"data": [{
{
"recordid": "1",
"description": "Letter of Demand",
"code": "0000",
"stagegroupdescription": "General Collections",
"stagegroupid": "1"
},
{
"recordid": "2",
"description": "Section 57 AOD & consent to Judgment",
"code": "0010",
"stagegroupdescription": "General Collections",
"stagegroupid": "1"
},
...
}]
}
Customizing Queries
API requests can be customized to add additional functionality.
The LegalSuite API comes with many useful Parameters. It contains a lot of native SQL syntax including WHERE clauses and table JOINs.
It also allows you to set Paging parmeters to allowing you to retrieve smaller subsets of data to improve performance.
| Field | Description | Example |
|---|---|---|
| start | The record position to start from must be used with the length parameter Useful to add paging functionality to the result set, | start=0 |
| length | How many records to return must be used with the start parameter | length=10 |
| getSql | Instead of a results set, returns the SQL Query. | method:getSql |
| Count | Returns a Count of the result set. | method:Count |
{
"data": [{
"select [Matter].[FileRef],
"[Employee].[Name], [Favourites].*
"from [Favourites]
"left join [Matter] on [Matter].[RecordID]
"= [favourites].[MatterID]
"left join [Employee] on [Employee].[RecordID]
"= [favourites].[EmployeeID]
}]
}
Selecting Columns
The API returns a default set of columns when retrieving data from a table.
These are often all that are required, but you can specify the columns returned by using select and addselect.
If you want to add multiple Columns, you may send through an array of Select fields in the URL. EG select[]=matter.fileref, select[]=matter.description
This will return the FileRef and Description records from the Matter Table, we recommend using the paging parameters that can be found under Customizing Queries to receive smaller result sets.
This can be done on any of the select field types, an example of this can be found below.
| Field | Description | Example |
|---|---|---|
| select | Select specific columns, e.g. fileRef and description - Send this in the body: | select[]=matter.fileRef select[]=matter.description |
| addselect | Add additional columns to the default columns - Send this in the body: | addselect=employee.name |
| selectraw | To be used when you want to use a function within a Select | selectraw=MAX(matter.RecordID) |
{
"data": [{
"recordid": "71017",
"matterfileref": "0001/0001",
"description": "Kelvin Test",
}]
}
Where Clauses
SQL WHERE Clauses are a very powerful feature when using SQL. We are happy to tell you that the API offers this same powerful functionality.
WHERE clauses help users filter down the result sets on all CRUD functionality.
The format of any type of where clause will follow this pattern
where=ColumnName,Operator,Value.
To send multiple where clauses in one query we can make use of the array feature, and example can be found below.
Hint: You can always use the Method:toSql to get back your constructed SQL query to check the WHERE clauses you have.
| Field | Description | Example |
|---|---|---|
| where | adds a sql where clause. | where[]=Matter.RecordID,=,17 where[]=Matter.Employee,=,17 |
| orwhere | adds a sql or Where clause. | orwhere=fileRef,like,1200 |
| wherein | adds a sql where In clause. | wherein=recordId,17,25,32 |
| wherenull | adds a sql or Where clause. | wherenull=matter.description |
| orwhere | adds a sql orWhere clause. | orwhere=fileRef,like,1200 |
| whereraw | To be used when you want to use a function within a where. | whereraw=MAX(Matter.RecordID) |
| whereBetween | To be used when you want to use a function within a where. | wherebetween=recordId,1000,1200 |
{
"data": [{
"recordid": "61810",
"fileref": "ACO1/0003",
"description": "No Description"
},
{
"recordid": "61811",
"fileref": "ACO1/0004",
"description": "No Description"
}]
}
Ordering and Grouping
The API also allows you to ORDER BY or GROUP BY your result set.
The ORDER BY is used to sort the result-set in ascending or descending order. The ORDER BY keyword sorts the records in ascending order by default. To sort the records in descending order, use the DESC keyword.
GROUP BY is also supported by the API and can be used to arrange identical data into groups
| Field | Description | Example |
|---|---|---|
| orderby | Provides a Sql OrderBy Functionality | orderby=matter.fileRef,DESC |
| orderbyraw | Provides a Sql OrderBy when wanting to use a SQL Function | orderbyraw=MAX(CustomTable.RecordID),DESC |
| groupby | Provides a Sql GroupBy Clause | groupby=Matter.DateInstructed |
{
"data": [{
"fileref": "0001/0001",
"name": "Jennifer Daly",
"recordid": "74249",
"matterid": "71017",
"employeeid": "23",
"date": "80460",
"time": "4521774"
}]
}
Registering as a Developer
To register as a developer for the API you need to contact our admins at tech@LegalSuite.co.za
Registering a Client
For a connection between a Clients SQL database and the LegalSuite API to be made a client has to register and add their SQL database details.
The API makes this easy, below are examples of functions that can be used to check if a client is already registered to the API, one to test SQL Database connections and the last to register new clients to the API.
How to get Matter FileRefs
As part of uploading documents to our document log, a file reference (fileref) will need to be added as a parameter.
Use this example to fetch a list of all File References and descriptions.
Uploading Documents
The Legalsuite API allows you upload documents to existing matters by adding them to the document log.
These documents are then easily accessible on the LegalSuite Apps for Clients to view
Database Structure
To gain a more indepth understanding of the LegalSuite Database Structure you can find a document explaining the core relationships here
Exporting Collections Matters
The document Exporting Collections Matters to LegalSuite guides on automating bulk debt collection in LegalSuite.
It details how you can export debtor data to the LegalSuite API for users to import.