Lexly API

GET /api/v1/meeting/{date}/{dealid}

GET /api/v1/partnerform

POST /api/v1/company

POST /api/v1/partnerform

POST /api/v1/user

POST /api/v1/upgradeToBankIdVerificationMail

POST /api/v1/authenticateBankIdUpgrade

GET /api/v1/account/{id}

Partner Oauth Credentials

Auth Workflow using cURL

Here we provide an examples using the cURL command.

1. Get authorization token via cURL:

$ curl 'https://${host}/api/v1/oauth/token' \
      -u '${partner_username}:${partner_password}' -d 'grant_type=client_credentials&email=${client_email}&password=${client_password}'

You should now be able to perform an API call with the access_token or jwt you received above, for example:

$  curl 'https://${host}/api/v1/user' \
      -H 'Authorization: Bearer 929a7c3cffbb0c03a87dec5153efb310a983f360'

As a partner you can gain access to user information by either sending a request with a username (e-mail address) and password or with a personal identity number (ssn - for this you must write a personal identity number - example 197702190485 ). If the request is approved, you will receive an oauth access token that can be used to access all APIs. To be able to login with just the personal identity number you need a special access and a BankID login on your side of the setup or use the BankID on our side - see below.

The Curl request should be in one of the following two formats depending on the type of request:

curl 'https://${host}/api/v1/oauth/token' -u '${partner_username}:${partner_password}' -d 'grant_type=client_credentials&email=${client_email}&password=${client_password}'
curl 'https://${host}/api/v1/oauth/token' -u '${partner_username}:${partner_password}' -d 'grant_type=client_credentials&ssn=${client_personal_identity_number}'

You can also do a combination request with both email/password and personal identity number at the same time. In this case it will first test the email/password combination and then the personal identity number (just for partners with special access):

curl 'https://${host}/api/v1/oauth/token' -u '${partner_username}:${partner_password}' -d 'grant_type=client_credentials&email=${client_email}&password=${client_password}&ssn=${client_personal_identity_number}'

When a token has expired you can request for a new one by sending the "refresh_token" as follow:

curl 'https://${host}/api/v1/oauth/token' -u '${partner_username}:${partner_password}' -d 'grant_type=refresh_token&refresh_token=${refresh_token}'

You can include the following parameters

If all are included a new user will be created if no existing one is found.

Parameter	Description	Type	In
`grant_type`	Required and should have the value: client_credentials	string client_credentials	Form Data
`email` required	The email for the user.	string xxxxx@yyyy.xx	Form Data
`ssn`	The swedish personal number.	interger YYYYMMDDNNNN	Form Data
`phone`	The phonenumber to the customer.	string only numbers	Form Data
`first_name`	The first name of the customer.	string application/json	Form Data
`last_name`	The last name of the customer.	string application/json	Form Data
`deal_id`	Without this the customer willn't get the partner deals.	integer int64	Form Data
`password` Not required for creating a new account	The login password for the account.	string	Form Data

Responses

Code	Description
200	Login ok and a token is returned.
201	A new user is registered, login ok and a token is returned.
400	One or more required fields are missing or are incorrect.
401	The user exist, please login with password (invalid_password).
401	The user exist, please login with bankid (missing_bankid).
401	An error with the auth credentials or the credentials may not have sufficient privileges (invalid_grant).
403	Auth credentials are invalid or they may not have sufficient privileges (invalid_grant).
404	User does not exists or can't be found with the given parameters (user_does_not_exists).

Here we provide an examples using the cURL command for BankID login.

1. Get orderRef and activate the BankID login via cURL:

$ curl 'https://${host}/api/v1/oauth/bankid' \
      -u '${partner_username}:${partner_password}' -d 'bankid=${client_personal_identity_number}'

2. Check if BankID verification is done via cURL:

$ curl 'https://${host}/api/v1/oauth/bankid' \
      -u '${partner_username}:${partner_password}' -d 'orderRef=${orderRef}'

When the BankID is verified by the user you should be able to perform an API call with the access_token or jwt you received above, for example:

$  curl 'https://${host}/api/v1/user' \
      -H 'Authorization: Bearer 929a7c3cffbb0c03a87dec5153efb310a983f360'

BankID login

If you do not have special access and would like to let the end user login with bankid you can do it this way:

curl 'https://${host}/api/v1/oauth/bankid' -u '${partner_username}:${partner_password}' -d 'bankid=${client_personal_identity_number}'

To check the BankID login status do as follow. The orderRef you will get as a result from the request above if the client_personal_identity_number is correct and the requester is valid to login:

curl 'https://${host}/api/v1/oauth/bankid' -u '${partner_username}:${partner_password}' -d 'orderRef=${orderRef}'

The response from the request above will either be "status": "pending" or the token.

You can include the following parameters

If all are included a new user will be created if no existing one is found.

Parameter	Description	Type	In
`bankid` one of the following is required	The swedish personal number.	interger YYYYMMDDNNNN	Form Data
`orderRef` one of the following is required	A orderRef you receive from the firest request with the bankid.	string a886a9c8-3036-491c-8b8a-668261b5e754	Form Data

Responses

Code	Description
200	If bankid is sent you will get the orderRef.
200	If orderRef is sent you will either get the "status": "pending" or the granted token.
400	One or more required fields are missing or are incorrect.
401	The user exist, please login with password (missing_password).
404	User does not exists or can't be found with the given parameters (invalid_grant).

The following APIs can be accessed in this way:

GET /api/v1/contactform

GET /api/v1/document/{file_id}

GET /api/v1/user

POST /api/v1/contact

POST /api/v1/upgradeToBankIdVerificationMail

POST /api/v1/authenticateBankIdUpgrade

DELETE /api/v1/document

PUT /api/v1/user

OAuth

Managing API access is done through an end customers user account, and each user account may have zero or more client credentials.

These client credentials may be used to request privileges from users. Users, in turn, can approve or deny granting such privileges.

The OAuth authorisation sequence allows you to request privileges from a user and retrieve token credentials. Once these have been approved, you may use the token credentials to make API requests on behalf of the user.

OAuth privileges

OAuth Workflow using cURL

Here we provide some examples using the cURL command.

2. Authorisation redirect:

http(s)://${host}/api/v1/oauth/authorize?response_type=code&client_id=testclient&state=abc

If the user grants access to your application, they will be redirected to:

http://www.mywebsite.com/login?code=cd52984f895b1710f962b89631a1c3b8cc411ba5&state=abc

3. You should now request for an OAuth token using all the information:

$ curl -u testuser:testpwd 'https://${host}/api/v1/oauth/token' \
      -d 'grant_type=authorization_code&code=cd52984f895b1710f962b89631a1c3b8cc411ba5'

You should now be able to perform an API call with the access_token or jwt you recived above, for example:

$ curl 'https://${host}/api/v1/user' \
      -H 'Authorization: Bearer 929a7c3cffbb0c03a87dec5153efb310a983f360'

Permission required for each API call are described on a per call basis.

Authorisation redirect
Token request and response

Before you can start sending requests for client credentials we will need to setup username and password for you. Please contact us on it@lexly.com to get this. When you request this you need to provide us with the oauth_callback URL.

1. Authorisation redirect

You authorize your client via an authorization page. Either our web login page or your own form. If you are using our form it will have a URL like this http(s)://${host}/api/v1/oauth/authorize?response_type=code&client_id=${client_id}&state=${oauth_state} where ${client_id} is the same as the username you've got from us and ${oauth_state} can be anything, example 'abc'.

The user will be asked to grant you the requested privileges by login with their existing account.

If they accept and login they will be redirected to:

${oauth_callback}?code=${oauth_code}&state=${oauth_state}

If they reject, the redirection will be to:

${oauth_callback}?error=access_denied&error_description=The+user+denied+access+to+your+application&state=${oauth_state}

Therefore, you should be able to inspect the redirection to the callback URL.

2. Token request

Now you should have the following pieces of information:

oauth_code

We then request the access_token, jwt and refresh_token by sending the oauth_code by cURL:

curl -u ${client_username}:${client_password} http(s)://${host}/api/v1/oauth/token -d 'grant_type=authorization_code&code=${oauth_code}'

This will generate something like the following:

{ "access_token": "446fa40e9bc80197410b7f24fb72e75bd33d4351", "expires_in": 3600, "token_type": "Bearer", "scope": "Private", "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJp4MTkwMTUzMCwia.....YILTZIY6kH_PvLTYCIXb6GOihmmdvd0SrAq15wOFy7x9Zt9itsjRVU", "refresh_token": "551d806eee00ceb0be27615652ebbb046ffd7e51" }

When a token has expired you can request for a new one by sending the "refresh_token" as follow:

curl 'https://${host}/api/v1/oauth/token' -u '${client_username}:${client_password}' -d 'grant_type=refresh_token&refresh_token=${refresh_token}'

Responses

Code	Description
200	Login ok and a token is returned.
400	Authorization code doesn't exist or is invalid for the client (invalid_grant).
400	The grant type was not specified in the request (invalid_request).
400	Missing parameter: "code" is required (invalid_request).

With this access token you can now access client data for the user who granted it by sending cURL requests as following:

curl http(s)://${host}/api/v1/user -H 'Authorization: Bearer [ ${access_token} or ${jwt} ]'

The following APIs can be accessed this way:

GET /api/v1/account/{id}

GET /api/v1/contactform

GET /api/v1/document/{file_id}

GET /api/v1/user

POST /api/v1/contact

DELETE /api/v1/document

PUT /api/v1/user

CID

Auth Workflow using cURL

Here we provide some examples using the cURL command.

1. Authorization for via cURL:

$ curl 'https://${host}/api/v1/${api}' \
      -H 'Auth: cid={CID} -H 'TimeZone: {TimeZone}

Instead of OAuth, the end user can access a same data by CID authentication. The CID will automatic be generated when a calendar entry for a specific client is created.

You will get the CID from the current customer. When you've got it you can access the APIs by sending it in the header regardless if you are using POST or GET. It should be written in the following format:

Auth: cid=${CID}

The following APIs can be accessed in this way:

GET /api/v1/account/{id}

Transaction

Register

Example of posted data:

{
  "userData": {
    "email": "test-003@lexly.com",
    "phone": "12345678",
    "language": "finnish",
    "timezone": "Europe/Helsinki"
  },
  "providerData": {
    "fiTupas":{
      "uiLocale": "sv-FI",
      "redirectUrl": "https://lexly.fi"
    }
  },
  "authProvider":  "fiTupas"
}

Example of returned data if all went well:

{
  "accessUrl": "https:// ...",
  "id": "580c7da5-375b-47f1-ac9f-34990edcf103"
}

POST /api/v1/oauth/transaction/register

Header

Header	Description	Example
`Authentication` required	Supports Partner Access Credentials	See Authentication

Parameters

Parameter	Type	In
`userData->email` required	string application/json	Json
`userData->phone` required	string application/json	Json
`userData->language` required	string application/json	Json
`userData->timezone` required	string application/json	Json
`providerData->fiTupas->uiLocale` required	string application/json	Json
`providerData->fiTupas->redirectUrl` required	string application/json	Json
`authProvider` required	boolean application/json	Json

Responses

Code	Description
200	Returning the transaction id and access url if everything went well
400	Missing or invalid parameters
403	Authentication failed (request_parameters_missing)
500	Could not connect to authentication provider

Auth

Example of posted data:

{
  "providerData": {
    "fiTupas":{
      "uiLocale": "sv-FI",
      "redirectUrl": "https://lexly.fi"
    }
  },
  "authProvider":  "fiTupas"
}

Example of returned data if all went well:

{
  "accessUrl": "https:// ...",
  "id": "580c7da5-375b-47f1-ac9f-34990edcf103"
}

POST /api/v1/oauth/transaction/auth

Header

Header	Description	Example
`Authentication` required	Supports Partner Access Credentials	See Authentication

Parameters

Parameter	Type	In
`providerData->fiTupas->uiLocale` required	string application/json	Json
`providerData->fiTupas->redirectUrl` required	string application/json	Json
`authProvider` required	boolean application/json	Json

Responses

Code	Description
200	Returning the transaction id and access url if everything went well
400	Missing or invalid parameters
403	Authentication failed (request_parameters_missing)
500	Could not connect to authentication provider

Get Transaction

Example of returned data if all went well:

{
	"status": "new" | "started" | "complete" | "failed",
	"authData": {
		"access_token": <access_token>,
		"expires_in": <expires_in>,
		"token_type": <token_type>,
		"scope": <scope>,
		"jwt": <jwt>,
		"refresh_token": <refresh_token>
	},
	"errorData": {
        "error": "access_denied",
        "errorCode": "cancel",
        "errorDescription": "..."
    }

}

GET /api/v1/oauth/transaction/{id}

Header

Header	Description	Example
`Authentication` required	Supports Partner Access Credentials	See Authentication

Parameters

Parameter	Description	Type	In
`id` required		string	Path

Responses

Code	Description
200	Returning the status of the transaction
400	Missing or invalid parameters
400	User doesn't have ssn
403	Authentication failed (request_parameters_missing)
404	The transaction doesn't exist or has expired
409	Transaction was started with "register" but user already exists
500	Could not connect to authentication provider

Enable single sign-on

To enable single sign-on from an external site to make it possible to create new agreements or going into the business portal you need to setup a session cookie with the following name and format for the current domain:

PHPSESSID=p8ln19nh69udh8pp3s45k6rde3; domain=.lexly.com

The value for the PHPSESSID should be the same as the one you get in your API request. You can get the current session id with the API function Get session id

Errors

Error responses will contain a JSON response body, structured as follows:

{
      "error_type": "${error_type}", 
      "error_message": "${error_type}", 
      "http_code": ${http_code}
    }

For example:

{
      "error_type": "invalid_client", 
      "error_message": "The client id supplied is invalid", 
      "http_code": 400
    }

Lexly uses HTTP status codes to indicate the success or failure of an API request.

HTTP response codes in the 2xx range indicate that the API call completed successfully. The 4xx range indicates an error, either due to missing, incomplete, or not applicable information (e.g. missing or invalid parameters, invalid authorisation, etc.).

When a request is well formed, but does not satisfy necessary conditions, then we will return a 409 code. For example, when trying to book a meeting that's already booked.

Codes in the 5xx range suggest an error with Lexlys booking system, they could also indicate planned system downtime, and will be rare.

The following table of error responses applies to all API calls, there may be additional errors which are specific to the respective API calls, but will follow the same structure.

HTTP code	Reason	Error Type and Message
400 Bad Request	Required parameter(s) missing	`request_parameters_missing` The parameter(s) $bad_parameters$ were missing. Please refer to our API documentation.
400 Bad Request	Login failure (Oauth specific) - different error messages	`invalid_grant_type` The grant_type is invalid `invalid_client` "Client credentials were not found in the headers or body", "Supplied response_type isn't supported", "No client id supplied", "The client id supplied is invalid"
400 Bad Request	Login failure (Calendar specific) - different error messages	`missing_calendar_information` Missing needed calendar information. `no_deal_id` Missing needed deal id. `missing_advisor_info` Missing needed advisor information.
400 Bad Request	Failed to upload a file (upload specific)	`failed_to_upload_file` This file type is not supported. `failed_to_upload_file` Failed to upload file.
401 Unauthorised	No or invalid access credentials	`invalid_authorisation` No valid access credentials were provided. Please refer to our API documentation. `invalid_grant` Authorization code doesn't exist or is invalid for the client
401 Unauthorised	No or invalid access credentials (oauth specific)	`invalid_authorisation` No valid access credentials were provided. Please refer to our API documentation. `invalid_grant` Authorization code doesn't exist or is invalid for the client `invalid_password` The user exist but the password is invalid. `missing_bankid` The user exist, please login with bankid. `missing_password` The user exist, please login with password. `invalid_grant` Some error with the auth credentials or the credentials may not have sufficient privileges.
401 Unauthorised	No or invalid access credentials (account specific)	`invalid_authorisation` You don't have access for the requested id.
403 Forbidden	User doesn’t have permission for a document action or retrieval	`insufficient_privileges` The access credentials provided do not have sufficient privileges for this request.
403 Forbidden	User doesn’t have permission for a document action or retrieval (oauth specific)	`invalid_grant` Auth credentials are invalid or they may not have sufficient privileges.
404 Not Found	The endpoint exists but the resource was not found.	`resource_not_found` The resource was not found. We will try to give additional information about what is missing.
409 Conflict	New new user is registered but the .	`user_already_exist` The user already exist.
500 Server Error	Other unexpected server error	`server_error` We encountered an unexpected error. Please contact Lexly support and include as much details about what caused the error.

List of API Calls

Get

GET /api/v1/contactform/{partner_id}

GET /api/v1/company/{organisation_number}

GET /api/v1/deals

GET /api/v1/document/{file_id}

GET /api/v1/getcompanyinfo/{organisation_number}

GET /api/v1/image

GET /api/v2/image

GET /api/v1/logout

GET /api/v1/meeting/{date}/{dealid}

GET /api/v1/partnerform

GET /api/v1/user

Post

POST /api/v1/contact

POST /api/v1/company

POST /api/v1/partnerform

POST /api/v1/upgradeToBankIdVerificationMail

POST /api/v1/user

POST /api/v1/authenticateBankIdUpgrade

Put