Documentation: User Import via ExtAPI – Lanes & Planes

Help-Center

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.

1. Authentication
2. Endpoint
3. Limitations
4. Request Body
5. Example Request
6. HTTP Status Codes
7. 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

POST https://api.lanes-planes.com/ext/users

Include the previously generated API key in the HTTP Authorization header under Token token=APIKEY.

cURL

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 POST method.
• GET, PUT and DELETE are not supported.
• The payload must be submitted in JSON format.
• The payload must include all users who should be active. Any missing user will be interpreted as to be deactivated.
• Each new POST request 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

Request Body Attributes

• ident (string) • optional

  An external ident.

• first_name (string) • required

  The first name of the user.

• middle_name (string) • optional

  The middle name of the user.

• last_name (string) • required

  The last name of the user.

• email (string) • required

  The user’s email address. This value serves as the unique identifier for the user within Lanes & Planes.

• personnel_number (string) • optional

• managers_emails (array of strings) • optional

  The email address of the user's manager. Depending on the company settings, this value may become required.

• creditor_account (string) • optional

• abbreviation (string) • optional

• company_creditor_account (string) • optional

• reference_cost_center (string) • optional

• accounting_invoice_profile_ids (array of integers) • required

  The IDs will be provided by Lanes & Planes. Multiple IDs need to be separated by a comma.

• group_ids (array of integers) • optional

  The IDs of the travel policy groups will be provided by Lanes & Planes. Multiple IDs need to be separated by a comma.

• roles (array of strings/integers) • optional

  The role of the user.

• cost_centers (array of objects) • optional

  The cost centers of the user. Depending on the company settings, this value may become required.

• cost_units (array of objects) • optional

  The cost units of the user. Depending on the company settings, this value may become required.

• delegation (array of objects) • optional

  The delegate of the user. Delegates can only be provided for users with the roles “Admin”, “Manager” or “Accountant”. A delegate must have the role “Admin”, “Manager” or “Accountant”.

5. Example request

JSON

{
    "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.

7. Frequently Asked Questions (FAQ)

Why does the API not supportUPDATE orDELETE 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.

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:

JSON

"cost_centers": [
  {
    "valid_from": "2022-01-01",
    "valid_until": "2022-12-31",
    "ident": "12345 ABC",
    "name": "12345 ABC"
  }
]