LapID API - Integration Guide 3.2.0

LapID Service GmbH is the leading automation provider for compliance obligations in vehicle fleets. With LapID, you can use one convenient system for the driver’s license checks and instructions required by law for all fleets and organizations. The automated driver’s license check provides the right solution for every fleet. LapID’s three checking methods provide simple, automated, and secure solutions to support fleet managers:

• LapID Driver App (AI-based self-check of the employee's driver's license via smartphone)
• LapID Label (presenting the driver’s license with a passive NFC label at a checking station)
• LapID Manager App (app-supported visual inspection by an authorized person)

Instructions by LapID Service GmbH provide efficient and easy training. Companies benefit from location- and time-independent, DGUV-compliant e-learning instructions that include topics relevant to the fleet (e.g., driver instruction) as well as topics relevant to companies in general (e.g., occupational health and safety, fire protection). LapID Service GmbH provides legal protection, regular data protection audits by TÜV Süd, ISO 27001 certification, the fastest implementation for users, and personal support.

Changelog

3.2.0

• Added dedicated endpoint to move a person to another company: POST /persons/{personUuid}/move
• During person move, assigned person products are deactivated and supervisor assignments are removed
• If required, products and supervisors must be assigned again in the target company via separate API calls

Authorization

To use the API, a Bearer Token is required. You can create this token as an administrator via the settings in the LapID customer system.

1. Log into the LapID Customer Portal, go to Settings and navigate into the company for which you want to create a new API token.
2. Create a new API token.
3. Use this API token as Bearer Token in the Authorization header for every request.

Please Note: An API token has access to the company it was created for, as well as to all sub-companies.

Getting started

Use the GET /companies request to check whether your API token has access to all relevant companies. This request also returns the company UUIDs that are required for all company-level requests. Having verified that your token is working, continue with the following sections depending on your use case.

Supervisor

A supervisor is responsible for a person. The person will be notified by the LapID system to complete their driver's license check and/or instructions (for more information, see Person). If the person ignores their check or instruction reminders, the supervisor will be notified through escalation management.

The person will be notified 3 times to do the necessary checks (driver's license check, instructions).

• In general the first reminder will be sent out 21 days before due date.
• The second will be sent out 14 days before due date.
• The third will be sent out 7 days before due date.

If the person didn't do the necessary checks, the escalation managements starts one day after the due date. All the following notifications to supervisors will be via email:

• The assigned supervisor with escalationLevel1 will be notified that the person is overdue to do the necessary checks.
• After 14 days, the assigned supervisor with escalationLevel2 will be notified that the person is overdue to do the necessary checks.
• After 30 days, the assigned supervisor with escalationLevel3 will be notified.

After that, no further notifications will be sent.

Create a Supervisor

The minimal set of data needed to create a supervisor is the name, first name and the email address.

Example:

{
  "name": "Doe",
  "firstName": "Jane",
  "emailAddress": "junk@lapid.de"
}

Set Supervisor's Product Settings

For each product, you can separately configure when the supervisor should be notified. For an explanation of escalation management and the levels, please refer to Supervisor. Set the escalation levels for the driver's license check and/or instructions product:

{
  "escalationLevel1": true,
  "escalationLevel2": false,
  "escalationLevel3": true
}

Activate Supervisor

After you are done with the configuration, you can activate the supervisor.

Example:

{
  "active": true
}

Person

A person will be notified by the LapID system to do the driver's license check and / or the instructions. It is possible to decide per person which LapID products should be activated and monitored.

If a product is active, every person has a status that indicates whether everything is correctly set up to process the necessary driver's license check and/or instructions:

• Green means everything is correctly set up.
• Yellow means there is room for improvement. For example, a supervisor is not yet assigned.
• Red means something still needs to be set up for the driver's license check or instruction, or the person has not yet completed them.

Create a Person

The minimal set of data needed to create a person is the last name, first name, and at least one contact option (email address or mobile phone number for SMS).

Example:

{
  "name": "Doe",
  "firstName": "John",
  "contact": {
    "sendEmail": true,
    "emailAddress": "junk@lapid.de"
  }
}

The default language is DE (German). If the person needs to be contacted in another language, please also set the language parameter as described in the API documentation.

If you are using our staging system, please note that SMS and E-Mails will be sent out regardless. Be careful to choose appropriate contact information accordingly.

Activate a Person's Driver's License Check

Follow the next steps to activate the driver's license check for this person.

At first you need to decide between the three available license check types. For more explanations about licenseCheckType please refer to Driver's License Check Types.

When you activate the driver's license check, you can set a custom date or use a generated date. For more information please refer to Custom Date vs generated Date.

Example (activate license check with generated date):

{
  "mode": "afterFuturePeriod",
  "licenseCheckType": "label",
  "interval": "yearly"
}

Example (activate license check with custom date):

{
  "scheduledDate": "2023-01-01",
  "licenseCheckType": "label",
  "interval": "yearly"
}

Additional Steps for Driver App

If the person's driver's license will be checked by the LapID Driver App, no additional information is needed. The driver's license is automatically registered during the first check and stored in the LapID system. After the first successful check, this information can be retrieved via the driver's license endpoint.

Additional Steps for Label

To use the label license check type you need to additionally add the person's driver's license and the LapID label which was applied onto this license.

Example (create a driver's license):

{
  "licenseNumber": "1234567890",
  "licenseType": "card",
  "issueDate": "2005-01-01",
  "countryOfIssue": "DE"
}

Example (assign a label):

{
  "labelNumber": 12345678,
  "checksum": 12345
}

Additional Steps for Manual

To use the manual license check type you need to additionally add the person's driver's license.

Example (create a driver's license):

{
  "licenseNumber": "Z014AB837X95",
  "licenseType": "card",
  "issueDate": "2005-01-01",
  "countryOfIssue": "DE"
}

Activate a Person's Instructions

Follow the next steps to activate the instructions for this person.

First you need to get all available instructions. You have the option to get all available instruction for the company or for a specific person. Getting instructions for a person provides you with instructions which are available and not already assigned to the person.

When you activate the instructions, you can set a custom date or use a generated date. For more information please refer to Custom Date vs generated Date. Optionally, you can assign single modules of the instruction for a person by setting moduleUuids. If you do not set moduleUuids, all modules of the instruction will be activated. The modules field is deprecated.

Example (activate instruction with generated date):

{
  "mode": "afterFuturePeriod",
  "interval": "yearly"
}

Example (activate instruction with generated date and specific modules):

{
  "mode": "afterFuturePeriod",
  "interval": "yearly",
  "moduleUuids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

Example (activate instruction with a custom date):

{
  "scheduledDate": "2023-01-01",
  "interval": "yearly"
}

Example (activate instruction with a custom date and specific modules):

{
  "scheduledDate": "2023-01-01",
  "interval": "yearly",
  "moduleUuids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ]
}

Assign a Supervisor

To assign all responsible supervisors to a person, provide all supervisor IDs as an array.

Example:

{
  "supervisorIds": [
    123456
  ]
}

Move a Person to another Company

To move a person from company A to company B, use the dedicated endpoint POST /persons/{personUuid}/move.

During this move:

• all assigned person products will be deactivated
• all supervisor assignments will be removed

After moving, product activation in the target company must be done with separate API calls (e.g. via the person's license check and instructions endpoints). If required, supervisors must be assigned again in the target company (e.g. via PUT /persons/{personUuid}/supervisors).

Example (move by company UUID):

{
  "companyUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Example (deprecated move by numeric company id):

{
  "companyId": 123456
}

Activate a Person

After you are done with the configuration, you can activate the person.

{
  "active": true
}

Company

For managing your customer data across different tenants, the LapID API provides company endpoints to create, update, and delete companies, as well as configuration endpoints for the LapID product settings.

Please note: All company endpoints require an extended API token with multi-tenant permissions. Please contact LapID support for more information.

Create a Company

The minimal set of data needed to create a company is the name for the new company and the parentCompanyUuid. The parentCompanyUuid is the UUID of the company which should be the parent company. The deprecated field parentCompanyId may still be used for backward compatibility. If parentCompanyUuid is set, it is used. If parentCompanyUuid is not set and parentCompanyId is set, parentCompanyId is used.

All product settings from the parent company will be inherited by the new child company. To change these settings, please see Set LapID Product Settings.

Example:

{
  "parentCompanyUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "GuideTestCompany"
}

Update a Company

When updating a company, parentCompanyUuid takes precedence over the deprecated parentCompanyId. If parentCompanyUuid is set, it is used. If parentCompanyUuid is not set and parentCompanyId is set, parentCompanyId is used. If neither parentCompanyUuid nor parentCompanyId is set, the existing parent company remains unchanged.

Set LapID Product Settings

Set the company's product settings for each product you want to use.

Driver's License Check Settings

Activate the product and set the check methods to be used for driver's license checks. For more information about check methods, please refer to Driver's License Check Types.

In addition, you can set the contact information for the person responsible for the driver's license check in the company. This information will be shown in all email notifications sent by the system in the context of the driver's license check.

Example:

{
  "active": true,
  "driverAppEnabled": true,
  "labelEnabled": true,
  "manualEnabled": true,
  "contactName": "John Doe",
  "contactEmail": "junk@lapid.de",
  "contactPhone": "+49271489720"
}

Instruction Settings

Activate the product and define which instructions should be available for assignment to persons in this company (for more information, see Activate a Person's Instructions). To set up these instructions, you can either copy all available instructions from the parent company, or configure your own instructions in collaboration with LapID support.

In addition, you can set the contact information for the person responsible for the instructions in the company. This information will be shown in all email notifications sent by the system in the context of instructions.

Example:

{
  "active": true,
  "contactName": "John Doe",
  "contactEmail": "junk@lapid.de",
  "contactPhone": "+49271489720"
}

Activate a Company

After you are done with the configuration, you can activate the company.

{
  "active": true
}

General Product Information

Driver's License Check Types

Below you will find further information about the different check types for the driver's license with LapID.

Driver App

With the LapID Driver App, a person's driver's license check can be carried out regardless of location and time. Prerequisites are an EU driver's license card from Germany or Austria and a smartphone with camera and flash. For more information please see: Product Information - LapID Driver App

Label

With the LapID Label, the person's license check can be performed for any driver's license. The check is performed at a LapID checking station. To find the nearest station you can use the LapID Station Finder. For more information about this check type, please see: Product Information - LapID Label

Manual

This check type is used for a visual inspection of the person's driver's license by an authorised person, e.g., a supervisor.

Custom Date vs Generated Date

This setting only applies to the first driver's license check or instruction. After the first date, LapID will always generate the next one based on the configured interval.

You have two options for the first date: either set a custom date manually, or let LapID generate one automatically.

There are two modes for automatic date generation:

• afterFuturePeriod — the date is scheduled after the provided interval starting from today. Use this when onboarding a new person who has not yet had their first check.
• nextNeeded — LapID calculates the next legally required date based on existing check history. Use this when a person already has prior check records.

Intervals

The LapID system offers a list of different intervals you can set to check a person's driver's license or conduct an instruction.

¹ To use non-standard intervals, a mutual agreement with LapID is required. LapID can then unlock the interval.

² These intervals are intended for testing and implementation purposes only. To use them in the LapID staging environment, please contact LapID support.

³ Spontaneous can only be used with the driver's license check type "manual".

Feedback

We welcome any feedback regarding this integration guide or the API implementation in general. If you have suggestions, found an issue, or just want to share your experience, please reach out to us at feedback@lapid.de.