Returning.AIDevelopers
v1

API reference / Legacy / Users

.md

Get user

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

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/users/{userId}
Permission
getUserData
Retries
The authenticated 404 is the stable rejection.

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.

Request#

Path parameters#

userId#stringREQUIRED
Any user identifier. ObjectId, email, numeric id, and username currently all hit the same missing-route 404.

Eg61100af5c548eb5c7ebc7819

Headers#

Authorization#stringREQUIRED
Bearer community API key. A valid token still receives 404 because the route is not mounted.

EgBearer <API_KEY>

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. Community-scoped GET-by-ObjectId-or-email is Get user.
  • 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.
More examples and details

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.

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

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.

{
  "meta": {
    "status": "error",
    "statusCode": 404
  },
  "message": "Route not found error.",
  "detail": "Cannot GET /apis/v1/users/{userId}",
  "solution": "Read error detail and try again."
}

Errors#

Fix the data01

404Fix the data
Authenticated request reached the public gateway and the route is not mounted.
{
  "meta": {
    "status": "error",
    "statusCode": 404
  },
  "message": "Route not found error.",
  "detail": "Cannot GET /apis/v1/users/{userId}",
  "solution": "Read error detail and try again."
}

Next step#

Look up one user by email or numeric idPOST/v1/users/infoUse POST /v1/users/info. Send { "idOrEmail": "alex.admin@example.com" } or the numeric platform id as a string.