---
title: "User Upload API"
method: POST
path: "/v1/users"
tags: ["User APIs"]
---

# User Upload API

`POST /v1/users`

Bulk API to insert User records. This API endpoint accepts POST requests with JSON data
containing a list of User records wrapped in a dictionary.

```
POST /v1/users
```

```json
{
  "data": [user_1, user_2, user_3]
}
```

If a record with the same `user_id` already exists in the dataset, the existing record will
be replaced (no partial update is allowed at this time). We recommend limiting your calls to
around 100 records at a time to avoid memory issues or timeout risks.

### Schema validation

This API validates the inserted records against the API schema. Any schema error will cause
the whole request to fail (`status_code=422`), and none of the records will be inserted. As
long as the request passes the schema validation, the API will return `status_code=200`, but
you should still check if there is any error occurring with individual records.

```json
{
    "errors": true,
    "data": [
        "data.0.user_id is invalid. The attribute was expected to be a `string`"
    ]
}
```

## Response Format

The API will return a JSON object with a `task_id` that can be used to retrieve.

#### Example Successful Response

```json
{
  "data": {
    "task_id": "{task_id}"
  }
}
```

To check the exact response body of this task_id, make a GET request to the following endpoint:

```
GET /v1/users/_status/{task_id}
```

Replace `{task_id}` with the task_id returned from the response.

## Request body

- UserBulkIn
  - `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.

## Response `200`

Successful Response

- CreateResponse
  - `message` string, required — Human-readable message
  - `data` TaskId, required
    - `task_id` string, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

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