# Import

The endpoints on this page provide an abstract way of importing data into **ClearXP** without the need to understand the underlying implementation details. Because **ClearXP** is a configuration-driven platform, these endpoints are versatile in their use and can be adapted to each organisation's unique data needs.

Take for example, importing an [**Org Structure**](/clear-api-reference/import.md#import-org-structure) and the two use-cases below:

{% hint style="success" %}
**Use Case 1: Import Position Hierarchy**\
As demonstrated in the documented examples below, by attaching a *Position Number* to each user profile and linking this to an org structure by *id*, the system would be able to place the user within the org structure and attach metadata to their profile to control permissions, learning assignments and enhance reporting.

Furthermore, linking this to [**Job Architecture**](/clear-api-reference/import.md#import-job-architecture) would enable the platform to be able to automatically recommend content to learner to satisfy the requirements for promotion to the next position in the org hierarchy.
{% endhint %}

{% hint style="success" %}
**Use Case 2: Import Location Data**\
Alternatively, the org structure endpoint can be minimally used to attach flat location data to each user's profile. In this case, the *parentId* isn't required and the *id* may represent an attribute on the user's profile such as *City*. In this case, the org data could be used to populate the S*tate* and *Country* for that user.

Again, this location data can assist with configuring permissions, learning assignments and enhance reporting.
{% endhint %}

Although not essential for **ClearXP** to operate, importing richer data enables greater platform functionality. AI and Machine Learning algorithms utilised by the platform benefit from clean and complete metadata and will ensure more accurate results.

## Imports users

> Imports user profile information for one or more users into ClearXP. Where one\
> of the attributes is a unique identifier that matches an existing user in the system, an update operation will be performed, otherwise a new user will be created.<br>

```json
{"openapi":"3.0.0","info":{"title":"API for clear-api-o322","version":"1"},"servers":[{"description":"ClearXP","url":"https://clearlrs.com"}],"paths":{"/api/import/users":{"post":{"description":"Imports user profile information for one or more users into ClearXP. Where one\nof the attributes is a unique identifier that matches an existing user in the system, an update operation will be performed, otherwise a new user will be created.\n","operationId":"POST:import.users","requestBody":{"content":{"application/json":{"schema":{"properties":{"users":{"items":{"$ref":"#/components/schemas/import.UserDefinition"},"title":"Array of users to import into the system\n","type":"array"},"verify":{"title":"When true, will validate the import request without importing any users\n","type":"boolean"}},"required":["users"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"errorCount":{"title":"The total number of errors detected\n","type":"number"},"errors":{"items":{"$ref":"#/components/schemas/import.UserImportError"},"title":"List of import errors with detailed messages\n","type":"array"},"existing":{"title":"The number of users that will be updated\n","type":"number"},"new":{"title":"The number of users that will be created\n","type":"number"},"rows":{"title":"The number of users sent for import\n","type":"number"},"skipped":{"title":"Number of users skipped from import due to errors\n","type":"number"},"warningCount":{"title":"The total number of warnings detected\n","type":"number"},"warnings":{"items":{"$ref":"#/components/schemas/import.UserImportError"},"title":"List of import warnings with detailed messages\n","type":"array"}},"required":["rows","new","existing","skipped","errorCount","warningCount","errors","warnings"],"type":"object"}}},"description":"Success response"},"default":{"$ref":"#/components/responses/APIError"}},"summary":"Imports users"}}},"components":{"schemas":{"import.UserDefinition":{"properties":{"attributes":{"additionalProperties":{"type":"string"},"title":"Key-value pairs of any attributes to attach to the imported or updated user\n","type":"object"},"name":{"title":"The display name of the user\n","type":"string"}},"required":["name","attributes"],"type":"object"},"import.UserImportError":{"properties":{"message":{"type":"string"},"row":{"type":"number"},"type":{"type":"string"},"value":{"type":"string"}},"required":["type","message","value","row"],"type":"object"}},"responses":{"APIError":{"content":{"application/json":{"schema":{"properties":{"code":{"description":"Error code","type":"string"},"details":{"description":"Error details","type":"object"},"message":{"description":"Error message","type":"string"}},"title":"APIError","type":"object"}}},"description":"Error response"}}}}
```

## Import Org Structure

<mark style="color:orange;">`PUT`</mark> `https://{organisation}.clearlrs.com/api/import/organisation`

Imports organisational structure data into **ClearXP** which can be used to populate additional metadata against the user for reporting, activity assignment and Machine Learning purposes. When attaching org data to users, **ClearXP** will match the *id* against an attribute in the user's profile and look-up the remaining associated attributes.

#### Request Body

| Name       | Type   | Description                                                                                                         |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| id         | string | A unique ID for each entry in the org data – this could be a Position Code or Location ID depending on the dataset. |
| parentId   | string | A reference to the parent in the org structure for the entry, if relevant.                                          |
| attributes | object | Key-value pairs of any organisational data for the entry.                                                           |

{% tabs %}
{% tab title="204 Org structure successfully imported." %}

```
```

{% endtab %}
{% endtabs %}

#### Example Request Body

```javascript
[
    {
        "id": "00002",
        "parentId": "00001",
        "attributes": {
            "Position Number": "00002",
            "Position Title": "Sales Representative",
            "Department": "Sales",
            "State": "VIC",
            "Country": "Australia"
        }
    }
]
```

## Import Job Architecture

<mark style="color:orange;">`PUT`</mark> `https://{organisation}.clearlrs.com/api/import/jobs`

Imports job and competency data into the platform for utilisation in talent management functionality such as identifying skills gaps and recommending training to suit job roles. To take full advantage of this data, competencies should then be linked to courses and learning activities in the system.

#### Request Body

| Name         | Type   | Description                                                            |
| ------------ | ------ | ---------------------------------------------------------------------- |
| id           | string | A unique ID for this job (i.e. job code).                              |
| name         | string | The name of the job.                                                   |
| competencies | array  | An array of **Competencies** that should be attached to the job.       |
| attributes   | object | Any additional metadata attributes that should be attached to the job. |

{% tabs %}
{% tab title="204 Job data successfully imported." %}

```
```

{% endtab %}
{% endtabs %}

#### Example Request Body

```javascript
[
    {
        "id": "10001",    
        "name": "Sales Representative",
        "competencies": [
            {
                "Name": "Persuades",
                "Description": "Using compelling arguments to gain the support and commitment of others."
            },
            {
                "Name": "Being Resilient",
                "Description": "Rebounding from setbacks and adversity when facing difficult situations."
            }
        ],
        "attributes": {
            "Job Family": "Sales & Marketing",
        }
    }
]
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.clearxp.com/clear-api-reference/import.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.