Contents

LegalSuite 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.

Example
POST https://api.legalsuite.net/matter/get/71017  
Header: 'authorization'='Bearer API Key'  
Response:
{
"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.

Example
POST https://api.legalsuite.net/auth
Header : 'authorization'='Developer Key'
Body : 'company'='ACME'
       'login'='Kobus'
       'password'='Password12345'
Response:
{
"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
Example
POST https://api.legalsuite.net/filenote/get
Header: 'authorization'='Bearer API Key'
Response:
{
"data": [{
"recordid": "6615999",
"matterid": "942",
"docfilenoteid": "2",
...
},
{,
"recordid": "6616000",
"matterid": "945",
"docfilenoteid": "5",
...
}]
}
Get a Single FileNote (with RecordID 610024)
Example
POST https://api.legalsuite.net/filenote/get/610024
Header: 'authorization'='Bearer API Key'
Response:
{
"data": [{
"recordid": "610024",
"matterid": "145",
"docfilenoteid": "1",
...
}]
}
Create a New FileNote
Example
POST https://api.legalsuite.net/filenote/store
Header: 'authorization'='Bearer API Key'
Body : 'matterid'='71017'
       'employeeid'='1034'
       'description'='FileNote Description'
       '...'
Response:
{
"data": [{
"recordid": "621111",
"matterid": "71017",
"docfilenoteid": "0",
...
}]
}
Update a FileNote (with the RecordID 621111)
Example
POST https://api.legalsuite.net/filenote/update
Header: 'authorization'='Bearer API Key'
Body : 'recordid'='621111'
       'employeeid'='1011'
       'docfilenoteid'='35'
Response:
{
"data": [{
"recordid": "621111",
"matterid": "71017",
"docfilenoteid": "35",
...
}]
}
Delete a FileNote (with the RecordID 621111)
Example
POST https://api.legalsuite.net/filenote/delete
Header: 'authorization'='Bearer API Key'
Body : 'recordid'='621111'
Response:
{
"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
Example
POST https://api.legalsuite.net/createview
Header: 'authorization'='Bearer API Key'
Body : viewname:AppNameStageCodeListView
SQL: SELECT
Stage.RecordID,
Stage.Description,
Stage.Code,
StageGroup.Description AS stagegroupdescription,
Stage.StageGroupID
FROM Stage
LEFT JOIN StageGroup ON
Stage.StageGroupID = StageGroup.RecordId
Response:
{
"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
Example
POST https://api.legalsuite.net/appnamestagecodelistview/get
Header: 'authorization'='Bearer API Key'
Response:
{
"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
Example
POST https://api.legalsuite.net/favourites/get
Header :'authorization'='Bearer API Key'
Body : 'addselect[]:Matter.FileRef'
       'addselect[]:Employee.Name'
       'leftjoin[]:Matter,Matter.RecordID,=,Favourites.MatterID'
       'leftjoin[]:Employee,Employee.RecordID,=,Favourites.EmployeeID'
       'method:getSql'
Response:
{
"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)
Example
POST https://api.legalsuite.net/matter/get
Header: 'authorization'='Bearer API Key'
Body: 'addselect:Matter.RecordId'
       'selectraw:Matter.FileRef as MatterFileRef'
       'select:Matter.Description
Response:
{
"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
Example
POST https://api.legalsuite.net/matter/get
Header: 'authorization'='Bearer API Key'
Body: 'select:Matter.RecordId'
       'select:Matter.FileRef'
       'select:Matter.Description
       'where[]:Matter.EmployeeID,=,8'
       'where[]:Matter.FileRef,like,ACO1%'
Response:
{
"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
Example
POST https://api.legalsuite.net/matter/get
Header: 'authorization'='Bearer API Key'
Body: 'orderby:Matter.FileRef,desc'
Response:
{
"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.

Example
POST https://api.legalsuite.net/auth/checkregister
Header: 'authorization'='Developer Key'
Body: 'firmcode:ACME02'
Example
POST https://api.legalsuite.net/auth/testconnection
Header: 'authorization'='Developer API Key'
Body: db_host:legalsuite.org
db_port:1433
db_database:legalsuite
db_user:ls
db_password:password
Example
POST https://api.legalsuite.net/auth/register
Header: 'authorization'='Developer API Key'
Body: contact_name:Paul
contact_email:paul@acme.co.za
db_host:legalsuite.org
db_port:1433
db_database:legalsuite
db_user:ls
db_password:password

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.

Example
POST https://api.legalsuite.net/utils/matters/get
Header: 'authorization'='Developer API Key'
Body: companycode":acme01

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

Example
POST https://api.legalsuite.net/utils/documents/upload
Header: 'authorization'='Developer API Key'
Body: fileref:0001/0001
companycode":acme01
description":Uploading Document to Cloud
filename:TestDoc.docx
filecontents:{MetaData of File Contents}

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.