---
title: "User Read API"
method: GET
path: "/v1/users/{user_id}"
tags: ["User APIs"]
---

# User Read API

`GET /v1/users/{user_id}`

This API endpoint retrieves the details of a specific user using their `user_id`.
To fetch the user information, make a GET request to the following URL:

**Notice**: Make sure the user_id is an urlencode string.

```
GET /v1/users/{user_id}
```

Replace `{user_id}` with the unique identifier of the user you wish to fetch.

## Response Format

The API will return the user details in a JSON object if the given `user_id` is valid and
exists in the system. The JSON object will include fields like `name`, `age`, `city`, `gender`
, and other user information.

### Example Response

Here's an example of a successful API response for a user with the `user_id` "user123":

```json
{
    "message": "success",
    "data": {
        "user_id": "user123",
        "name": "johndoe",
        // ... other user details
    }
}
```

If the provided `user_id` is invalid or does not exist in the system, the API will return an
error response with a `status_code=404`.

### Example Error Response

```json
{
    "message": "not found"
}
```

## Query parameters

- `userId` string, required

## Response `200`

Successful Response

- UserReadOut
  - `message` string, required — Human-readable message
  - `data` UserRecord, required
    - `user_id` string, required — Unique identifier for a user who has signed in. `user_id` can be in any format (e.g. users' email, internal user UUID or serial ID). The only restriction is that the first character must not be an underline `_`. Miso will use this id to cross-reference your User records with your Interaction records.
    - `created_at` union — The date the user’s account was created as an ISO-8601 date or datetime string.
      - string, date-time
      - string, date
    - `updated_at` union — The date the user’s account was updated as an ISO-8601 date or datetime string.
      - string, date-time
      - string, date
    - `name` string — The user's full name.
    - `profile_image` string, uri — URL to the profile image of the user.
    - `age` integer — Age of the user. We will internally convert it to year of birth.
    - `gender` string — The user's gender.
    - `city` string — City or zipcode the user is based in.
    - `state` string — State the user is based in.
    - `country` string — Country the user is based in.
    - `group_id` string — Group or Account ID from your CRM. This is useful in B2B scenarios. For example, you can use `group_id` to associate a user with their company or account. We will use this information to infer the user's interests and fine-tune their personalization and search results. For example, users from the same group might have similar interests on the site, and we can improve their user experience accordingly
    - `description` string — Text description of the user. This can be the user's own bio or the internal notes about the user. If available, Miso will analyze this description to better profile a user.
    - `custom_attributes` object — Dictionary of custom attributes about the user. As with the [Product API](#operation/content_write_api_v1_products_post ), you can specify attributes specific to your business in a `{"KEY" : VALUE}` format, where `KEY` must be a string, and `VALUE` can be: * a `string` or `an array of strings` * a `number` or `an array of numbers` * an `array of objects` * a `bool` * `null` * Example: ``` { "custom_attributes": { "acquisition_channel": "Facebook Campaign 2020", "declared_interests": ["Drama", "Romance"] } } ``` These custom attributes types must be consistent across all User records in your data set. Records with inconsistent types will fail to be inserted.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — User not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/miso/apis/miso-api.md) · [All operations](https://skmtc.net/miso/apis/miso-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/miso/miso-api/versions/f2fa5ba6025f/schema)