> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/administration/attributes/upload-attributes-manually.md).

# Upload attributes manually

How to prepare a CSV or Excel file and upload it through the Userlane portal to add users and their attributes.

You can add users and their attributes to Userlane manually by uploading a comma-separated values (CSV) or Excel (XLSX) file through the portal. This method is primarily used with browser extension implementations, where users and their attributes are not created through the `identify` [command](/developer-reference/quick-reference-of-commands.md) in code. Prepare a file with one row per user, upload it, and the values are available immediately for building audiences[^1] and filtering analytics. Because the data is a snapshot, it goes stale from the day of upload. For attributes[^2] that need to stay current, [connect an attribute source](/administration/attributes/connect-an-attribute-source.md) instead.

{% hint style="warning" %}
**Before you start.** You need the **Admin**, **Portfolio Owner**, or **Deployment Manager** role in the Userlane portal, and a prepared CSV or XLSX file with the users and attributes you want to add or update.
{% endhint %}

## Prepare the file

The upload accepts CSV files (UTF-8 encoding, any standard delimiter is auto-detected) and XLSX files (ANSI encoding). Each row represents one user, and the first row contains column headers.

* The first column is the identifier, typically the user's email address in lowercase. If the organization uses an ID-based identifier instead of email, use that.
* Each additional column holds one attribute. The column header must match the attribute name as it appears in the portal. Column order does not matter, and columns can be skipped during import.
* Remove any cell formatting, merged cells, or formulas before uploading. Plain values only.

A minimal file might look like this: email in column A, department in column B, location in column C, with one row per user and the header row at the top.

## Upload and map the file

{% stepper %}
{% step %}

#### Open the user import page

In the portal, go to **Settings** > **Company Users** and select **+ Add Users**.
{% endstep %}

{% step %}

#### Upload the file

Select the prepared CSV or XLSX file from your computer. The portal opens a mapping wizard once the file is loaded.
{% endstep %}

{% step %}

#### Map columns to attributes

The wizard suggests a mapping for each column based on its header. Review every suggestion and adjust any column that is marked as **Skip** but should be imported. If an attribute does not exist in the portal yet, you can create it during this step.
{% endstep %}

{% step %}

#### Confirm and start the upload

Review the summary screen and confirm. The portal processes the file and shows how many users were added or updated.
{% endstep %}
{% endstepper %}

The uploaded users and attribute values then appear in the portal and take effect immediately, without users having to sign in again. You can review the status of any import under **Settings** > **Processes**.

To update attributes later, prepare a new file with the current values and upload it through the same process. Existing users are matched by their identifier, and their attribute values are overwritten with whatever the new file contains. Re-uploading does not trigger additional email invitations to users who are already active.

{% hint style="info" %}
**Watch for empty cells.** Check whether your file includes all attribute columns or only the ones being updated, and confirm how the portal handles cells that are left blank.
{% endhint %}

## Troubleshooting

If an upload stays in **Processing** or **Waiting** for an extended period, it is usually caused by a large file or temporary system load. Check the import status under **Settings** > **Processes** and wait before retrying. If the status does not resolve, [contact Userlane support](/support/contact-and-escalation.md).

When attributes do not appear as expected after upload, the most common cause is an identifier mismatch. The identifier in the file must match the format the portal expects, typically an email address in lowercase. A mistyped identifier may create a duplicate user record rather than update the intended one, so check identifier formatting before uploading.

## Relevant articles

{% content-ref url="/pages/gtcOzAVjL7zzv75As2Jd" %}
[Attributes](/administration/attributes.md)
{% endcontent-ref %}

{% content-ref url="/pages/heUmxS6HxlGKqCQSjqbs" %}
[Attribute sources](/administration/attributes/attribute-sources.md)
{% endcontent-ref %}

{% content-ref url="/pages/5RV9H7dUyIbkTHBrF8Av" %}
[Connect an attribute source](/administration/attributes/connect-an-attribute-source.md)
{% endcontent-ref %}

{% content-ref url="/pages/Zk1PSRimln0YLI1l2ZkI" %}
[Build an audience from attribute rules](/administration/audiences/build-an-audience-from-attribute-rules.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>Does the upload create new users in Userlane?</summary>

Yes. If a row in the file contains an identifier that does not match an existing user, the portal creates that user and applies the attribute values from the file. Existing users are matched by their identifier and updated with the new values.

</details>

<details>

<summary>Can the upload create new attributes that do not exist in the portal yet?</summary>

Yes. When the wizard encounters a column header that does not match an existing attribute, it offers the option to create it during the mapping step.

</details>

<details>

<summary>How often should attributes be re-uploaded?</summary>

Uploaded attribute data is a snapshot that does not refresh on its own. If the underlying data changes frequently, each change requires a new upload. For attributes that need to stay current automatically, connecting an attribute source is the better path because it syncs on a regular schedule without manual intervention.

</details>

<details>

<summary>Is the manual upload available for all deployment types?</summary>

The manual upload through **Settings** > **Company Users** is primarily used with browser extension implementations. With the JavaScript snippet, users and their attributes are created through the `identify` command in code, so the CSV upload path is not the standard method. Contact your Customer Value Manager if you have questions about your deployment.

</details>

[^1]: An audience is a reusable group of users defined by attribute conditions, used to target content and filter analytics.

[^2]: An attribute is a fact Userlane holds about a user, such as department, job title, or location, used to build audiences and filter analytics.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/administration/attributes/upload-attributes-manually.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.