---
title: "POST /_twake/identity/v1/lookup/match"
method: POST
path: "/_twake/identity/v1/lookup/match"
tags: ["Identity server"]
---

# POST /_twake/identity/v1/lookup/match

`POST /_twake/identity/v1/lookup/match`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/linagora/apis/twake-on-matrix-apis-documentation/docs/_twake/identity/v1/lookup/match/post.ts> (a function with typed inputs; its response is checked against the schema)

Looks up the Organization User IDs which match value sent

## Request body

- object
  - `scope` string[], required
  - `fields` string[], required
  - `val` string: Optional value to search
  - `limit` integer: Optional max number of result to return (default 30)
  - `offset` integer: Optional offset for pagination

## Response `200`

Success

- object
  - `matches` object[]: List of users that match
    - `address` string: Matrix address, will be included in uid
    - `uid` string: id of a matching user
    - `display_name` string: Display name of a matching user
    - `displayName` string: Display name of a matching user
    - `givenName` string: Display name of a matching user
    - `givenname` string: Display name of a matching user
    - `cn` string: Display name of a matching user
    - `avatar_url` string: Avatar URI of a matching user following the mxc format https://spec.matrix.org/v1.10/client-server-api/#matrix-content-mxc-uris
    - `last_name` string: Last name of a matching user
    - `first_name` string: First name of a matching user
    - `mail` string: Email address of a matching user
    - `emails` string[]
    - `mobile` string: Mobile phone number of a matching user
    - `phones` string[]
    - `language` string: Language of a matching user
    - `timezone` string: Timezone of a matching user

## Other responses

- `400`: Bad request
- `401`: Unauthorized

## Changes

- **2025-11-27** `c3d224128ef8`: 2 info
  - request property `fields/items/` deprecated
  - request property `scope/items/` deprecated
- **2025-11-19** `a97a68cf436a`: 15 info
  - added the optional property `matches/items/avatar_url` to the response with the `200` status
  - added the optional property `matches/items/cn` to the response with the `200` status
  - added the optional property `matches/items/displayName` to the response with the `200` status
  - added the optional property `matches/items/display_name` to the response with the `200` status
  - …11 more
- **2024-01-09** `c7a6d3a400a7`: 13 warning, 4 info
  - removed the optional property `matches/items/avatar_url` from the response with the `200` status
  - removed the optional property `matches/items/cn` from the response with the `200` status
  - removed the optional property `matches/items/displayName` from the response with the `200` status
  - removed the optional property `matches/items/display_name` from the response with the `200` status
  - …13 more

[Operation history](https://skmtc.dev/linagora/apis/twake-on-matrix-apis-documentation/changes/_twake/identity/v1/lookup/match/post.md)

---

[API](https://skmtc.dev/linagora/apis/twake-on-matrix-apis-documentation.md) - [All operations](https://skmtc.dev/linagora/apis/twake-on-matrix-apis-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/linagora/apis/twake-on-matrix-apis-documentation/revisions/3428c7bb5a46?raw)