###### 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](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KAKF9CFXRC8P7VXH8BBX225P)
2. [Endpoint](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KB54KM9MSHH45FDXNN92R9RK)
3. [Limitations](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KB54KM9MQ9R2CRVC3RSTGHW5)
4. [Request Body](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KAKH1G293EG1RX45KAZQQJWF)
5. [Example Request](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KB54KM9M876NS53A9Y8V1NVG)
6. [HTTP Status Codes](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KB54KM9M9XBFB2ASTJQWHTYD)
7. [Frequently Asked Questions (FAQ)](https://support.lanes-planes.com/hc/de/articles/31245986692370-Documentation-User-Import-via-ExtAPI#h_01KB54KM9MJ35FVEH2K1FN6KJM)

### 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.

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

**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](https://support.lanes-planes.com/hc/de/articles/115001764893-Nutzer-verwalten) 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"
  }
]
```