# Get user

> **Legacy.** This endpoint is kept for existing integrations. Use the current API reference for new work.

This page documents `GET /v1/users/{userId}`.

- Endpoint: `GET https://api.returning.ai/v1/users/{userId}`
- Section: Legacy / Users
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `getUserData`
- Retries: The authenticated 404 is the stable rejection.
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/legacy-users/get-user

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `getUserData`

A Bearer token is still checked before the missing route is reported:

| Failure | Observed result | Recovery | | --- | --- | --- | | Missing or invalid `Authorization` | `401` `API request rejected error.` with `detail: A valid bearer token or API key is required for this endpoint.` | Add a valid community API key. Then stop; the GET still has no route. | | Valid token | `404` `Route not found error.` `detail: Cannot GET /apis/v1/users/{userId}` | Switch to `POST /v1/users/info`. |

`POST /v1/users/info` requires the `getUserData` permission. A valid key without that permission returns `403`.

## Behaviour

That route is **not mounted** on the current public gateway `https://api.returning.ai`.

Do not use it to look up a user. Use `POST /v1/users/info` with an email or numeric platform id.

**Replacement:** Authenticate with a community API key that has Get User Data → `POST /v1/users/info` with `{ "idOrEmail": "<email-or-numeric-id>" }` → read `data._id` and `data.userId`.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | `string` | Yes | Any user identifier. ObjectId, email, numeric id, and username currently all hit the same missing-route 404. |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Bearer community API key. A valid token still receives 404 because the route is not mounted. |

### Watch for

- The public path `users/get-user-by-id` currently maps to `GET /v1/users/{userId}`. That application route is not exposed on `api.returning.ai`. One-user lookup is `POST /v1/users/info` at [Get User Data](https://docs.returning.ai/api-reference/users/get-user-data.md). Community-scoped GET-by-ObjectId-or-email is [Get user](https://docs.returning.ai/api-reference/community-community-users/get-user.md).
- Mongo `_id` and username are not accepted as `idOrEmail` on `POST /v1/users/info`; they return `404 USER_NOT_FOUND`.
- `{ "identifier": { "key": "id", "value": "<numeric-id>" } }` currently also returns the user. Prefer `idOrEmail`.
- An empty POST body returns `400` `Identifier is required. Use idOrEmail or identifier.`
- Community-scoped `GET /v1/communities/{communityId}/users/{userId}` is a different operation.

### Example request

```bash
curl --request GET \
  --url 'https://api.returning.ai/v1/users/<userId>' \
  --header 'Authorization: Bearer <API_KEY>'
```

### More examples

There is no success example for this GET. The structured `404` example is the current authenticated response for ObjectId, email, numeric id, and username.

The replacement success example in Next steps is a synthetic `POST /v1/users/info` body. Treat names as synthetic.

## Response

This GET has no success response on `https://api.returning.ai`.

`POST /v1/users/info` returns HTTP `200` with `status: success`, `code: USER_DATA_RETRIEVED`, and `message: User data retrieved successfully`. That response is the readback. Save `data._id` and `data.userId` if another call follows.

## Errors

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | Authenticated request reached the public gateway and the route is not mounted. |

**Retries:** The authenticated 404 is the stable rejection. Retrying the same path will not create a route. After a transient transport failure you may retry once to confirm the 404, then migrate to `POST /v1/users/info`. `POST /v1/users/info` is a read. Retry timeouts and `5xx` on that POST with bounded exponential backoff. Do not retry its `400`, `401`, `403`, or `404` without changing the body or credential.

## Next step

- [Look up one user by email or numeric id](https://docs.returning.ai/api-reference/users/get-user-data.md): `POST /v1/users/info`. Use `POST /v1/users/info`. Send `{ "idOrEmail": "alex.admin@example.com" }` or the numeric platform id as a string.