The Klyant API
1. Klyant REST API
2. Security
2.1. Workflow
2.2. Example
Using Laravel Framework
3. API Documentation
4. Data format
5. Generic error codes
6. Troubleshooting/F.A.Q
1. Klyant REST API
The Klyant REST API provides you with access to read and write data into Klyant software. In order to access the Klyant data you need to be first registered within the Klyant software application.
A registered user can use his or her credentials to access data using the REST Klyant API.
2. Security
Klyant API uses Oauth as the authentication mechanism for the API. The user will use a CliendID and Secret Key together with the login credentials to get an API token. Furthermore the API token will be the one used for further API calls.
2.1 Workflow
Use a HTTP Client appropriate for your development technology. Authenticate within the system based on user credentials. Once authenticated the http client instance will be used for future http calls within the system. This authentication requires the server to use SSL for better protection.
2.2 Example
Using Laravel Framework
In order to use the Klyant API your Laravel project needs to have at least:
"guzzlehttp/guzzle": "~4.0" in composer.json
Run composer update or composer install to update this dependency. The GuzzleHttp is a client php class library which helps you create http calls to a certain server.
Using the Klyant API means:
Step 1. Authenticate using your secret and client unique identification which can be found in Klyant under the Settings page and get your token:
$this->client = new \GuzzleHttp\Client([ 'base_url' => 'https://app.klyant.com/api/' ]); $this->response = $this->client->post('access_token', [ 'body' => [ 'grant_type' => 'password', 'client_id' => 'your client id', 'client_secret' => 'your client secret', 'username' => 'Klyant login email', 'password' => 'Klyant password' ] ]); $token = $this->response->json(); $this->token = $token['access_token'];
Any calls from this moment can use the authentication token:
$response = $this->client->get('v2/clients?access_token=' . $this->token);
3. API Documentation
The following methods can be called using the Klyant API:
Path | Method | Method Details |
---|---|---|
v2/clients?access_token= | GET | Load all clients or landlords |
v2/client?access_token= | POST | Create a new client or landlord |
v2/clientLedger?access_token= | GET | Load the client ledger card view |
v2/matters?access_token= | GET | Load matters or properties |
v2/matter?access_token= | POST | Create a new matter or property |
v2/portfolios?access_token= | GET | Load all portofolios |
v2/portfolio?access_token= | POST | Create a new portfolio |
How to …
Authenticate
The following method can be used to authenticate a user using user email, password, client API key and secret id.
public function iSignIn ($email, $password) { try { $this->response = $this->client->post('access_token', [ 'body' => [ 'grant_type' => 'password', 'client_id' => 'client Id or API key',// can be read from environment variable 'client_secret' => 'secret',// can be read from environment variable 'username' => $email, 'password' => $password ] ]); $token = $this->response->json(); $this->token = $token['access_token']; } catch (GuzzleHttp\Exception\BadResponseException $e) { //do something with the error } }
Usage:
$this->client = new \GuzzleHttp\Client([ 'base_url' => 'https://app.klyant.com/api/' ]); $this->response = $this->iSignIn('my@email.com', 'mypassword');
Create a Client
The following fields can be set when you create a new client:
Field Tag | Required |
---|---|
First_Name/td> | Y |
Last_Name | Y |
Client_Code | Y |
Date | N (current date by default) |
Is_Company (0/1) | N (0 by default) |
Address_1 | N |
Address_2 | N |
Address_City | N |
Address_Region | N |
Address_Country | N |
Address_Postcode | N |
PPS_Number | N |
Notes | N |
N | |
Phone | N |
Mobile | N |
Contact_Person | N |
Once the token is obtained via the authentication method described above a client can be created by a
code similar to the one below:
$response = $this->client->post('v2/client', [ 'body' => [ 'access_token' => $this->token, 'First_Name' => 'Johnny', 'Last_Name' => 'Walker', 'Client_Code' => 'WALJ001' ] ]);
Retrieve All Clients
The following GET example can be used to load all clients:
$response = $this->client->get('v2/clients?access_token=' . $this->token); return $response->json();
Retrieve one client
The following GET example can be used to load one client uniquely identified by the Client_Code:
$response = $this->client->get('v2/client/WALJ001?access_token=' . $this->token); return $response->json();
Create a Property or Matter
The following fields can be set when you create a new property/matter:
Field Tag | Required |
---|---|
Client_Account_1 | Y |
Client_Code | Y |
Date | Y |
Matter_Code | Y |
Name | Y |
Status (0 = Closed, 1 = Open) | N (default 1) |
Load All Properties or Matters
The following GET example can be used to load all matters/properties:
$response = $this->client->get('v2/matters?access_token=' . $this->token); return $response->json();
Data format
All results of the Klyant REST API are in json format.
In case of failure the json result contains a message explaining the failure reason and a generic status code.
Generic error codes
Here is the list of error codes and reasons why they may appear:
Code | Method | Reason |
---|---|---|
200 | OK | Successfull call. |
201 | Created | The requested entity is succesfully created. |
400 | Bad Request | This error usually appear when your request fails the validation (e.g. missing required fields or invalid data provided to field: specifying string for numerics etc). Consider checking the validation message or your input data. |
404 | Not Found | The requested entity was not found in the database. Verify the id you provided or the query conditions. It also may be possible that you do not have access to that data. |
500 | Internal Server Error | An unexpected error occurs processing your request. Please contact the Klyant administrator for support |