# Import Via API

### Overview

MangoApps allows administrators to bulk import users via API by configuring the endpoint and mapping API fields to user fields in MangoApps. Follow the steps below to successfully import users.

<figure><img src="https://1733114811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lclpq021Ai9jH1_X4gO%2Fuploads%2F7uD7XDVegwzGrEkirFxm%2F13-02-2025-12-43-29.png?alt=media&#x26;token=c56de6f9-550e-4c1b-9be6-d97d9b1dc53a" alt="" width="563"><figcaption></figcaption></figure>

***

### Configure Synchronization Settings

Navigate to **Synchronize Settings** and select when to synchronize users from the API.

Choose one of the following options:

* **One Time Import (All Users)**: Imports and syncs users only once.
* **On User Login**:
  * **On First Login**: Syncs users when they log in for the first time.
  * **On Every Login**: Syncs users every time they log in.

{% hint style="info" %}
Users imported via **Admin Portal > Users > Add Users > Import via API** are automatically assigned the "Network User" role, regardless of their email domain.
{% endhint %}

***

### Configure Advanced Sync Settings

This section will only appear if **One Time Import (All users)** is selected in the above **Synchronization Settings**.

In **When Fetched Users Already Exist in MangoApps**, choose an option:

* **Skip Existing Users**: Avoids overwriting existing user data.
* **Update Existing Users**: Overwrites existing user data.

In **Email Invites for Newly Added Users**, check the box to send login credentials via email to new users.

***

### Configure API Endpoint and Parameters

A request will be sent to the listed URL to sync all users.

In **Import API URL**, select the preferred method from the dropdown menu (e.g., "GET") and enter the API URL.

<figure><img src="https://1733114811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lclpq021Ai9jH1_X4gO%2Fuploads%2Fxulgh875vOs0Au1O0ZAK%2F13-02-2025-01-17-07.png?alt=media&#x26;token=109f05a8-5e6b-43fc-be41-87aaf611e6cc" alt="" width="563"><figcaption></figcaption></figure>

**Request Parameters -&#x20;**<mark style="color:red;">**On User Login Synchronize Option Only**</mark>

* Enter the API field name in **API Field**.
* Enter the corresponding MangoApps field name in **MangoApps Field**.
* Click **+ Add** to add more parameters or **Remove** to delete parameters.

**Response Parameters -&#x20;**<mark style="color:red;">**Required for Either Synchronize Option**</mark>

* Enter the API field name in **API Field**.
* Enter the corresponding MangoApps field name in **MangoApps Field**.
* Check **User Identifier** for the field that uniquely identifies users. Only **one field** can be marked as the user identifier.
* Click **+ Add** to add more parameters or **Remove** to delete parameters.

{% hint style="danger" %}
The API field names in request and response parameters **must** match the third-party API field names.
{% endhint %}

***

### Configure Authentication Options

When connecting to the HCM/HRIS system to retrieve user profile data, select the method that best suits your system's security and integration requirements.

<figure><img src="https://1733114811-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Lclpq021Ai9jH1_X4gO%2Fuploads%2F3OXkC9m0Kv8jrFB8xNhN%2F13-02-2025-01-05-45.png?alt=media&#x26;token=4dc0635f-c238-4992-8849-21c7a394e8ef" alt="" width="563"><figcaption></figcaption></figure>

Enter the necessary authentication details:

* **OAuth Token URL**
* **Authorization URL**
* **Username**
* **Password**

Click **Save Settings & Test Connection** to verify the configuration.

***

### Preview & Synchronize

Click **Preview & Synchronize** to review the user data before importing. If everything is correct, click **Synchronize** to complete the process. Once the import is successful, a confirmation message appears, and the system sends an email notification to the network admin.