---
updatedAt: 2026-08-06T13:23:30.000Z
agentTools:
  projectIndex: https://docs.data.one/llms.txt
---

# Search for Users

Given a search term that is at least 3 characters long, this endpoint will return users that are an exact match of either the `userId` or the `correlationId` or a substring/fuzzy match on the `name`. It will return the results in descending order of when the user was initially created. If the search term is empty or no results are found then the response body will also return no results under the `users` field. The response will include a maximum of 20 users.

Unlike the v1 search endpoint, the response does not include a `dataOrigin` field.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "info": {
    "version": "v1",
    "title": "Hosted Web Journey",
    "description": "Endpoints relating to creating and managing users and sessions. These are only relevant for usage of the direct connection journey, for more details please see the guides on https://docs.data.one."
  },
  "paths": {
    "/v2/users/search": {
      "get": {
        "tags": [
          "Users V2"
        ],
        "operationId": "searchUsersV2",
        "summary": "Search for Users",
        "description": "Given a search term that is at least 3 characters long, this endpoint will return users that are an exact match of either the `userId` or the `correlationId` or a substring/fuzzy match on the `name`. It will return the results in descending order of when the user was initially created. If the search term is empty or no results are found then the response body will also return no results under the `users` field. The response will include a maximum of 20 users.\n\nUnlike the v1 search endpoint, the response does not include a `dataOrigin` field.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/SearchTerm"
          }
        ],
        "responses": {
          "200": {
            "description": "The users that matched the specified search term.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsersResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "Search query is missing or shorter than 3 characters."
          },
          "401": {
            "$ref": "#/components/responses/ApiKeyUnauthorizedError"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api-sandbox.data.one",
      "description": "Hostname for sandbox API"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Secret API key used for authentication."
      }
    },
    "schemas": {
      "UserResponseV2": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "format": "uuid",
            "description": "User ID used to uniquely identify applicant."
          },
          "partnerId": {
            "type": "string",
            "format": "uuid",
            "description": "The ID of the partner who created the user."
          },
          "created": {
            "type": "string",
            "format": "date-time",
            "description": "The DateTime that the user was created."
          },
          "name": {
            "type": "string",
            "description": "Full name of the user."
          },
          "correlationId": {
            "type": "string",
            "description": "An optional ID that can be used to correlate to a user."
          }
        },
        "required": [
          "userId",
          "partnerId",
          "created"
        ],
        "example": {
          "userId": "2590eaff-94dc-43f4-be30-bdab6c2cec8b",
          "partnerId": "88735265-b560-4151-91b7-5b87c99da0aa",
          "created": "2022-12-12T13:37:42.123Z",
          "name": "Jane Doe",
          "correlationId": "u7741887"
        }
      },
      "UsersResponseV2": {
        "type": "object",
        "properties": {
          "users": {
            "type": "array",
            "description": "List of users",
            "items": {
              "$ref": "#/components/schemas/UserResponseV2"
            }
          }
        },
        "required": [
          "users"
        ],
        "example": {
          "users": [
            {
              "userId": "2590eaff-94dc-43f4-be30-bdab6c2cec8b",
              "partnerId": "88735265-b560-4151-91b7-5b87c99da0aa",
              "created": "2022-12-12T13:37:42.123Z",
              "name": "Jane Doe",
              "correlationId": "u7741887"
            }
          ]
        }
      }
    },
    "responses": {
      "ApiKeyUnauthorizedError": {
        "description": "API key authentication unsuccessful."
      }
    },
    "parameters": {
      "SearchTerm": {
        "in": "query",
        "name": "q",
        "schema": {
          "type": "string"
        },
        "required": true,
        "description": "This query parameter can be used as a search term to exactly match either userId, correlationId or name.",
        "example": "2590eaff-94dc-43f4-be30-bdab6c2cec8b"
      }
    }
  }
}
```