This article provides information on the ExtAPI feature that allows importing users. The endpoint is designed to streamline the process of adding multiple users to the system in a single request.
- Authentication
- Endpoint
- Limitations
- Request Body
- Example Request
- HTTP Status Codes
- Frequently Asked Questions (FAQ)
1. Authentication
The endpoint requires authentication via an API Access Token (API Key). You can generate this token by logging into your account and navigating to the Personal Settings section. Once created, the token will be displayed only once, so be sure to copy and store it securely. The token does not expire.
To disable an API Key delete it by clicking on the trash can symbol.
1. Log in and open your User Account
2. Open Personal Settings
3. Scroll down and click Create to generate an API key
2. Endpoint
Include the previously generated API key in the HTTP Authorization header under Token token=APIKEY.
curl -X POST https://api.lanes-planes.com/ext/users \ -H 'Content-Type: application/json' \ -H "Accept: application/json" \ -H "Authorization: Token token=APIKEY" \ -d @users.json
3. Limitations
- The Lanes & Planes API supports the
POSTmethod. -
GET,PUTandDELETEare not supported. - The payload must be submitted in
JSONformat. - The payload must include all users who should be active. Any missing user will be interpreted as to be deactivated.
- Each new
POSTrequest will overwrite and update all current user information. -
The import is asynchronous. A status page, within the Lanes & Planes Company Account, is provided, including error indications.
4. Request Body
Valid role names:
admin → Adminmanager → Managertravel_assistant → Travel Assistantaccountant → Accountanttraveller → Travellerread_only_traveller → Traveller, without right
to
bookread_only_admin → Read-Only Admin
Each object may include:
-
ident → required-
name → required-
valid_from → optional-
valid_until → optionalEach object may include:
-
ident → required-
name → required-
valid_from → optional-
valid_until → optionalRemoval is possible, either through delegation dates provided in the past or submitting an empty string:
"delegation": {}.Each object may include:
-
starts_on → required-
ends_on → required-
delegate_email → required
5. Example request
{
"users": [
{
"ident": "1",
"first_name": "User",
"last_name": "Traveller",
"email": "traveller@test.com",
"abbreviation": "gk",
"creditor_account": "12231",
"company_creditor_account": "123123",
"reference_cost_center": "12231231",
"managers_emails": ["manager@test.com", "manager2@test.com"],
"personnel_number": "123",
"cost_centers": [
{
"valid_from": "2022-01-01",
"valid_until": "2026-12-31",
"ident": "1231254",
"name": "Human readable CostCenter name"
}
],
"cost_units": [
{
"valid_from": "2022-01-01",
"valid_until": "2025-12-31",
"ident": "456798",
"name": "Human readable CostUnit name"
}
],
"accounting_invoice_profile_ids": [
123,
1234
],
"group_ids": [
378
],
"roles": [
"admin",
"accountant"
],
"delegation": {
"starts_on": "2025-07-19",
"ends_on": "2025-07-30",
"delegate_email": "delegation@test.com"
}
},
{ ...
}
]
}
6. HTTP Status Codes
Lanes & Planes uses standard HTTP status codes to indicate whether the API request was successful or resulted in an error.
| Code | Description |
|---|---|
| 200 | Request processed successfully. |
| 400 | Malformed or incomplete JSON body. |
| 401 | Missing or invalid API token. |
| 403 | Authentication succeeded, but access is not allowed. |
| 404 | Requested resource does not exist. |
| 422 | Validation failed — correct format, but invalid data. |
| 429 | Too many requests — please retry later. |
| 500 | Internal Server Error. |
7. Frequently Asked Questions (FAQ)
Why does the API not support UPDATE or DELETE operations?
Our API is designed to work exclusively with POST. Each new push fully replaces the previous data set. Any user not included in the latest payload is interpreted as inactive and therefore deactivated automatically.
Because the complete user state is always derived from the most recent POST, additional PUT or DELETE methods are not required.
Should all user data be sent with every request?
Yes. All users must be included in each POST request. Any user omitted from the JSON payload will be deactivated.
Can I retrieve existing users from the API?
The API does not provide a separate GET method. After a successful upload, all users included in your JSON payload are visible in the Lanes & Planes tool. You have the option to download a User CSV file in your company account.
Is the upload a push or pull?
The upload is always a push. The API does not pull data from your systems.
How often can new data be pushed?
There are no restrictions. Data can be pushed as often as needed.
Which data fields are mandatory?
The following are required for all users:
First Name, Last Name, Email Address and Invoice Profile ID.
Depending on your company settings, cost centers, cost units and manager email may be required.
Do Managers need to be created before other users?
No. All users should be included in the same POST request.
Do Cost Centers/Units need to be created beforehand?
No. Cost Centers/Units do not need to be created in advance.
Can a user have multiple Managers?
Yes.
Can a user manage themselves?
No, only other Admins, Managers or Accountants can be assigned as Travel Manager.
Is it mandatory to use valid_from and valid_to for Cost Centers?
No. These fields can be omitted entirely from the JSON payload.
Which data gets overridden if it was manually adjusted in the Lanes & Planes tool before the next data push?
The following fields will be overwritten or removed if they are sent without values (e.g., as an empty array [] or null):
- ident
- abbreviation
- creditor_account
- company_creditor_account
- reference_cost_center
- personnel_number
- managers_emails
- cost_centers
- cost_units
- group_ids
- roles
- delegation
What happens if the data is not in the correct form?
If fields such as accounting_invoice_profile_ids, group_ids, roles, managers_emails, or cost_centers are missing or incorrect, the user remains unchanged. An error message is displayed in the Lanes & Planes tool. Users are not deactivated.
When are users deactivated?
Users are deactivated if they are not included in the JSON payload during the upload. Any missing user will be fully deactivated in Lanes & Planes.
What can cause an upload error?
- If the push fails (e.g., a relevant manager is missing), no updates are applied; all data remains as it was before.
- If only one user fails (who does not perform critical actions), the rest of the users are updated normally.
Roles without responsibilities with wrong or missing information in JSON
If a user with a role that has no responsibilities is present in the payload but contains incorrect or missing information, the user is not deactivated. A “failed” status appears in the User Import Logs with the appropriate reason.
Roles with responsibilities with wrong or missing information in JSON
- If a user with responsibilities is present in the payload but contains incorrect or missing information, the user is not deactivated, and a “failed” status appears in the User Import Logs with the appropriate reason.
- If a user with responsibilities is missing from the payload, the entire push fails, and no updates are applied.
What happens if a user is listed multiple times in JSON (duplicates)?
An existing user remains unchanged, and a “failed” status appears in the User Import Logs.
Users cannot be created multiple times.
How to add a cost center that was created previously in the Lanes & Planes tool
If a cost center already exists in the tool, you must include the given name in both ident and name.
Example:
A cost center created as “12345 ABC” should be added in the JSON payload as follows:
"cost_centers": [
{
"valid_from": "2022-01-01",
"valid_until": "2022-12-31",
"ident": "12345 ABC",
"name": "12345 ABC"
}
]
Kommentare