# Identify

**Users** sit at the core of Attuitive. Everything revolves them and generally all data relates to a user, or users. `/identify` provides a way to create and read them through **identifiers**.

## Create a new user

<mark style="color:orange;">`POST`</mark> `/identify`

Inserts a new user to the workspace.

**Headers**

| Name                                            | Value              |
| ----------------------------------------------- | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>  | `application/json` |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>`   |

**Body**

| Name          | Type   | Description                                              |
| ------------- | ------ | -------------------------------------------------------- |
| `identifiers` | object | An object containing identifying properties on the user. |
| `traits`      | object | An object containing attributes of the user.             |

**Response**

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

```json
{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {
    // Identifiers provided on the request
  },
  "traits": {
    // Traits provided on the request
  },
  "createdAt": "2025-04-10T00:10:41.840Z",
  "updatedAt": null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "status": 400,
  "message": "Invalid identifiers",
  "moreInfo": "The provided identifiers should be a valid JSON object."
}
```

{% endtab %}
{% endtabs %}

> **Important:** Fields with a `*` must be included in your request!

## Get an existing user

<mark style="color:green;">`GET`</mark> `/identify/:userId`

Gets a user by their ID.

**Headers**

| Name                                            | Value              |
| ----------------------------------------------- | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>  | `application/json` |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>`   |

**Query**

| Name                                        | Type   | Description                           |
| ------------------------------------------- | ------ | ------------------------------------- |
| `:userId`<mark style="color:red;">\*</mark> | string | ID of the user. `usr_[A-Za-z0-9]{16}` |

**Response**

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

```json
{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {
    ...
  },
  "traits": {
    ...
  },
  "createdAt": "2025-01-31T01:02:54.506Z",
  "updatedAt": "2025-04-09T10:06:06.813Z" // or null
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "status": 400,
  "message": "Invalid user ID",
  "moreInfo": "The provided user ID is not in the correct format of 'usr_[A-Za-z0-9]{16}'."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "status": 404,
  "message": "User with ID not found",
  "moreInfo": "A user with the provided ID does not exist."
}
```

{% endtab %}
{% endtabs %}

## Search users

<mark style="color:green;">`GET`</mark>`/identify`

Gets users matching the provided criteria. You can use `limit` & `pageToken` parameters to paginate results. See [pagination](https://tristans-organization-4.gitbook.io/attuitive/api-reference/pagination) for more details.

`...param` includes any number of additional parameters to filter identifiers based on. The user must match **all** parameters. Sending no parameters is the same as retrieving all users.

For example, to search by an email you would send: `/identify?email=test@example.com`&#x20;

> **TIP:** Nested searches are also supported. If your identifiers includes `{"name": {"first": "John", "last": "Doe"}}` you can search for this by sending `/identify?name.last=Doe`.

**Headers**

| Name                                            | Value              |
| ----------------------------------------------- | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>  | `application/json` |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>`   |

**Query**

| Name      | Type   | Description                                                                                               |
| --------- | ------ | --------------------------------------------------------------------------------------------------------- |
| limit     | number | Maximum number of results to return between `1` & `100`. Defaults to `50`.                                |
| pageToken | string | Token for the page to retrieve. Available on requests with multiple pages of results. Starts with `ey...` |
| ...param  | string | Parameters that should match a property in a user's `identifiers` e.g. `phoneNumber` or `email`           |

> **Important:** It is expected you will encode the URL to escape specific characters. For example, if searching on a phone number, the `+` character should be encoded as `%2B`.

**Response**

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

```json
{
  "data": [
    {
      "id": "usr_XXX",
      "workspaceId": "ws_XXX",
      "identifiers": {},
      "traits": {},
      "createdAt": "2025-01-31T01:02:54.506Z",
      "updatedAt": "2025-04-09T10:06:06.813Z"
    }
    ...
  ],
  "meta": {
    "limit": 50,
    "nextPageUrl": "/api/v1/identify?limit=50...", // or null
    "previousPageUrl": "/api/v1/identify?limit=50...", // or null
    "url": "/api/v1/identifiy?limit=50"
  }
}
```

{% endtab %}

{% tab title="400" %}

<pre class="language-json"><code class="lang-json">{
<strong>  "status": 400,
</strong>  "message": "Limit parameter out of range",
  "moreInfo": "The 'limit' parameter provided should be between 1 and 100."
}
</code></pre>

{% endtab %}
{% endtabs %}

## Update a user

<mark style="color:orange;">`POST`</mark> `/identify/:userId`

Updates an existing user's identifiers.

Updates use a **append & merge** approach. Properties will **override** an existing value if that key already and any new properties will be added.

You do not need to send existing properties when updating, these will continue to be persisted (or overwritten per the above section). To remove a value, send the key and a `null` value. For example to remove `phoneNumber`:

```json
{
    ...
    "phoneNumber": null
}
```

**Headers**

| Name                                            | Value              |
| ----------------------------------------------- | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>  | `application/json` |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>`   |

**Query**

| Name                                        | Type   | Description                           |
| ------------------------------------------- | ------ | ------------------------------------- |
| `:userId`<mark style="color:red;">\*</mark> | string | ID of the user. `usr_[A-Za-z0-9]{16}` |

**Body**

| Name        | Type   | Description                                             |
| ----------- | ------ | ------------------------------------------------------- |
| identifiers | object | An object containing identifying properties on the user |

**Response**

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

```json
{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {},
  "traits": {},
  "createdAt": "2025-04-05T00:10:41.840Z",
  "updatedAt": "2025-04-09T10:06:06.813Z"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "status": 400,
  "message": "Invalid identifiers",
  "moreInfo": "The provided identifiers should be a valid JSON object."
}
```

{% endtab %}
{% endtabs %}

## Delete a user

<mark style="color:red;">`DELETE`</mark> `/identify/:userId`

Delete a user by ID.

**Headers**

| Name                                            | Value              |
| ----------------------------------------------- | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>  | `application/json` |
| Authorization<mark style="color:red;">\*</mark> | `Bearer <token>`   |

**Query**

| Name                                        | Type   | Description                           |
| ------------------------------------------- | ------ | ------------------------------------- |
| `:userId`<mark style="color:red;">\*</mark> | string | ID of the user. `usr_[A-Za-z0-9]{16}` |

**Response**

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

```json
{
  "id": "usr_XXX",
  "workspaceId": "ws_XXX",
  "identifiers": {},
  "traits": {},
  "createdAt": "2025-04-05T00:10:41.840Z",
  "updatedAt": "2025-04-09T10:06:06.813Z"
}
```

{% endtab %}
{% endtabs %}