# Identify

The identify endpoint lets you add key-value properties to a user profile. This endpoint is optional and useful for getting a complete picture of a user just by looking at their profile, and additionally, these properties can be used for filtering and searching. 

For example, you may add a user's email address, their plan, last payment date, etc., to their profile and then use these properties to filter and search for users, such as searching for all users on a specific plan.

<figure><img src="/files/SWPMCJPItz7BMM0727nr" alt=""><figcaption></figcaption></figure>

## Add properties to user profiles.

<mark style="color:green;">`POST`</mark> `https://api.logsnag.com/v1/identify`

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Content-Type  | String | application/json |
| Authorization | String | Bearer \<TOKEN>  |

#### Request Body

| Name                                         | Type      | Description     |
| -------------------------------------------- | --------- | --------------- |
| project<mark style="color:red;">\*</mark>    | String    | Project name    |
| user\_id<mark style="color:red;">\*</mark>   | String    | User ID         |
| properties<mark style="color:red;">\*</mark> | Key/Value | User Properties |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Important:** Fields ending with an `*` are required in your request!
{% endhint %}

## Usage

It's important to remember that property keys override each other. For example, imagine that users of our product start with a free trial and then upgrade to a paid plan. We want to track the plan the user is currently on and other properties like their name and email address. We can do this by calling the identify endpoint once the user signs up and again when upgrading to a paid plan.

```json
{
    "project": "my-saas",
    "user_id": "123",
    "properties": {
        "plan": "free",
        "name": "John Doe",
        "email": "john@foo.com",
        "username": "johndoe"
    }
}
```

Later on, when the user upgrades to a paid plan, we can call the identify endpoint again with the new plan value:

```json
{
    "project": "my-saas",
    "user_id": "123",
    "properties": {
        "plan": "premium"
    }
}
```

## Properties Schema

Note that property keys may only contain lowercase alphabet characters and are optionally separated with `-` dashes. For example, `plan` and `plan-type` are valid tag keys, but `Plan` and `plan_type` are not. Values may be any string, boolean, or number.&#x20;


---

# 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://docs.logsnag.com/api-reference/identify.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.