Introduction
Legalsense offers a REST(ful) API, currently APIv3. Version 3 is actively maintained and also still being expanded.
The Legalsense API is largely self-documented in the sense that the API offers a clickable UI in which basic documentation of the API has been added and objects can be viewed.
This can be found at:
https://<yourinstallation>.legalsense.nl/api/v3/
Registration and authentication
To connect to the API of Legalsense Online, you need to provide the following headers:
- X-Legalsense-Api-Client-Identifier
- X-Legalsense-Api-Client-Token
To obtain a client identifier and client token to be used for the API, please contact Legalsense support at support@legalsense.nl.
Authentication with the API is done using a Token-based access method over HTTPS. There are two main endpoints related to the flow:
1. https://<yourinstallation>.legalsense.nl/api/v3/auth/login/: it creates a token that lives until you call /auth/logout/
.
2. https://<yourinstallation>.legalsense.nl/api/v3/auth/logout/: will invalidate the token.
For more information and guidance about authentication, please see:
https://<yourinstallation>.legalsense.nl/api/v3/
Structure
Within the API there are several endpoints that maintain all information within Legalsense, also reachable through UI. As in the UI, endpoints are available based on permissions you have as user or not.
All endpoints are reachable with a GET
call. Depending on the endpoint, it is also possible to do a PUT
, POST
or DELETE
call. The GET
response is seen as valid PUT
request.
Each endpoint has a listview sorted by id that is paginated (page size 100) and a detailview with more specific information. Within the listview it is possible to add filters by using certain query parameters. The available filters are listed within the api.
The server accepts requests in JSON format only and will respond in JSON format.
Extra fields
The data that is returned in our list views is limited to help with performance and to comply with the permission structure of Legalsense. In some endpoints you have the ability of using 'extra_fields' to include data you're missing.
In order to use an extra parameter, like 'number' in the endpoints 'Clients', add to your request the query parameter with an ? or & symbol depending on a single or multitude of query parameters in your request.
When performing this request, you will find the field 'number' is included in the list view through this parameter.
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"display_name": "Johnson International Shipping B.V.",
"url": "baseUrl/api/v3/clients/1/",
"softkill_status": 1,
"number": "10001"
},
{
"id": 2,
"display_name": "Dhr. de Bakker",
"url": "baseUrl/api/v3/clients/2/",
"softkill_status": 1,
"number": "10002"
}
]
}
Notice how the field 'number' is included in the list view through this parameter.
Pagination
List endpoints will return only a limited set of data, by default 500 records. To obtain more records, follow the next
key in the record:
To fetch all the pages, follow next
for each separate respons until the next
value is null
.
If a page size different from 500 is preferred, you can supply an alternate page size using ?page_size=n
with a page size of up to 1000.
Example use cases
Creating clients
"As a CRM partner I would like to create a client through the API, so my customer doesn't have to do this twice and by that ensuring data integrity across our systems."
In this case we will perform a POST-request to the 'Clients' endpoint:
In the body of your request you can pass information required or optional to create a client, for example:
{
"softkill_status": 1,
"tags": [
"Tag"
],
"alternative_names": "Alternative name",
"branches": [],
"billing_instructions": "Billing instructions",
"contact": {
"id": 29
},
"currency": {
"internal": "EUR"
},
"date": "2024-07-11",
"description": "Description",
"engagement_letter_status": 1,
"is_billable": true,
"is_identified": true,
"name": "Name",
"number": "12345"
}
If the request is successful, you will see a similar response to
{
"created_date": "2024-07-11T12:22:33.217887",
"modified_date": "2024-07-11T12:22:33.263584",
"id": 14,
"display_name": "Name",
"url": "baseUrl/api/v3/clients/14/",
"softkill_status": 1,
"tags": [
"Tag"
],
"alternative_names": "Alternative name",
"branches": [],
"billing_instructions": "Billing instructions",
"client_status": {
"display_name": "Actief",
"id": 1,
"url": "baseUrl/api/v3/clientstatuses/1/"
},
"contact": {
"display_name": "TurnContactIntoClient",
"id": 29,
"url": "baseUrl/api/v3/contacts/29/"
},
"currency": {
"is_derived": true,
"internal": null,
"representation": "EUR"
},
"custom_fields": [],
"date": "2024-07-11",
"description": "Description",
"engagement_letter_status": 1,
"is_billable": true,
"is_identified": true,
"name": "Name",
"number": "12345",
"office_expenses_rate": {
"is_derived": true,
"internal": null,
"representation": "6.00"
},
"originating_user": null,
"parent_client": {
"display_name": "Name",
"id": 14,
"url": "baseUrl/api/v3/clients/14/"
},
"price_list": {
"display_name": "<PriceList 276>",
"id": 276,
"url": "baseUrl/api/v3/pricelists/276/"
},
"reduction_rate": "0.00",
"referrer": null,
"sector": null
}
Contacts
"As a marketing automation partner I want to retrieve relevant contacts to sync with, for example Hubspot"
In this case we can perform a request to retrieve the contacts in the list view.
This would be a representative response:
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 4,
"display_name": "Contact 4",
"url": "baseUrl/api/v3/contacts/4/",
"softkill_status": 1
},
{
"id": 5,
"display_name": "Contact 5",
"url": "basUrl/api/v3/contacts/5/",
"softkill_status": 1
},
{
"id": 6,
"display_name": "Contact 6",
"url": "baseUrl/api/v3/contacts/6/",
"softkill_status": 1
}
]
}
In order to access the detail view, add the contact id.
Which will lead to the following response:
{
"created_date": "2000-01-01T00:00:00",
"modified_date": "2023-10-24T14:22:31",
"id": 6,
"display_name": "Contact 6",
"url": "baseUrl/api/v3/contacts/6/",
"softkill_status": 1,
"tags": [],
"is_debtor": true,
"is_organization": true,
"account_manager_user": null,
"address_label_name": {
"is_derived": true,
"internal": null,
"representation": "Contact 6"
},
"custom_fields": [],
"default_billing_address": {
"display_name": "OrgSix Group Headquarters 6 address",
"id": 6,
"url": "baseUrl/api/v3/addresses/6/"
},
"details": [
{
"is_billing_cc_email": false,
"is_billing_to_email": false,
"is_dunning_to_email": false,
"is_dunning_cc_email": false,
"kind": "email",
"value": "info@example.com"
}
],
"email": "info@example.com",
"firm": {
"display_name": "Brouwers & Van Leeuwen",
"id": 1,
"url": "baseUrl/api/v3/firms/1/"
},
"notes": "",
"add_payment_link": {
"is_derived": true,
"internal": null,
"representation": true
},
"bank_account_bic": null,
"bank_account_iban": null,
"has_dunning": true,
"include_ubl": {
"is_derived": true,
"internal": null,
"representation": true
},
"invoice_language": "en-us",
"invoice_send_method": null,
"number": "D00006",
"payment_deadline": {
"is_derived": true,
"internal": null,
"representation": 30
},
"tax_scheme": 1,
"vat_number": "",
"organization_kind": null,
"organization_name": "OrgSix",
"organization_number": "",
"default_contact_person": null,
"peppol_id": null,
"organization_kind_subtype": null
}
Matters
"As A DMS partner I want to retrieve new matters, so I can create a folder in our DMS system, without having the customer to do this and by that ensuring data integrity across our systems"
With endpoint 'Matters' we can look in the detail view with this request:
This is a representative response:
{
"count": 3,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"display_name": "Johnson International Shipping B.V. / General Services",
"url": "baseUrl/api/v3/matters/1/",
"softkill_status": 1
},
{
"id": 2,
"display_name": "Johnson International Shipping B.V. / Due Diligence Van Puffelen",
"url": "baseUrl/api/v3/matters/2/",
"softkill_status": 1
},
{
"id": 3,
"display_name": "Dhr. de Bakker / Huurovereenkomst Bakkerij Bakker",
"url": "baseUrl/api/v3/matters/3/",
"softkill_status": 1
}
]
}
If you would like to retrieve all new matters you can, after defining what's new, use a few 'created_date' filters as query parameters in your request. See for reference the filter documentation of the endpoint within the API documentation.
These are three simplified use cases of how you can use the Legalsense API to work efficient, effective and result-oriented on your data goal.
Comments
0 comments
Please sign in to leave a comment.