> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询用户 API：批量检查 ID 列表

> 使用 Didit 一次调用即可将最多 20,000 个供应商 ID、Didit 用户 ID 或邮箱解析为对应用户，并按您提交的顺序返回这些用户。



查找用户提示
        将提示词复制到剪贴板



      
      

\<pre>

\`Goal: Find out where a long list of accounts stands in Didit, in one call, then read exactly those users.

Step 1 - POST https://verification.didit.me/v3/users/lookup/
Auth header: x-api-key: <DIDIT_API_KEY>
Body: {"identifiers": ["usr_8842", "maria.o@gmail.com", "<didit user id>"]}
\- Send at most 100,000 entries; after blanks and duplicates are removed, 1 to 20,000 must remain. Either limit exceeded returns 400 with code "too_many_identifiers".
\- Each identifier is matched inside the application: vendor_data exactly, else the Didit user ID (UUID), else a verified email (case-insensitive). An email can match several users and all of them count.
\- Blank entries are dropped and duplicates removed, keeping the first.

Response 201:
\{"lookup_id": "<uuid>", "requested": 14, "found": 12, "not_found": [{"identifier": "usr_7001", "position": 7}], "expires_at": "<ISO 8601>"}
\- position is 1-based in the submitted, deduplicated order.
\- The result is kept for 24 hours, for this application only.

Step 2 - GET https://verification.didit.me/v3/users/?lookup=<lookup_id>&limit=200
Returns only the matched users, ordered by the position of their identifier. Paginate with limit and offset, or follow "next".
An expired or unknown lookup_id returns 404 with code "lookup_not_found": run Step 1 again.

Failure modes: 400 (validation, too_many_identifiers), 401 (missing key), 403 (revoked key), 404 (lookup_not_found), 429 (honour Retry-After).

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

粘贴到

Didit 的 Look Up Users API 可在一次调用中，将最多 20,000 个标识符解析为您应用中的用户，并告诉您哪些标识符未匹配到任何用户。当您持有一份账户列表时（例如代付批次的收款方、合作伙伴的账户，或欺诈查询的输出结果），并且需要了解其中每个账户的验证状态，请使用此接口。## 工作原理1) **查询列表。** 调用 `POST /v3/users/lookup/` 并传入您的标识符。该调用仅做读取，返回 `lookup_id`、计数，以及未匹配到任何用户的标识符。
2) **读取用户。** 将 `lookup_id` 作为 `lookup` 传给[列出用户](https://docs.didit.me/zh/management-api/users/list.md)。它只返回匹配的用户，顺序与您提交标识符的顺序一致。## 匹配规则每个标识符都在您的应用内按以下顺序匹配：| 顺序 | 匹配对象 | 规则 |
| - | - | - |
| 1 | `vendor_data` | 精确匹配 |
| 2 | Didit 用户 ID | UUID，即用户的 `didit_internal_id` |
| 3 | 已验证邮箱 | 不区分大小写。一个邮箱可以匹配多个用户，这些用户都会计入结果 |- 空白条目会被丢弃，重复项会被移除，并保留首次出现的条目。
- 单次请求最多发送 100,000 个条目。去除空白和重复项后，必须剩余 1 至 20,000 个标识符。超出任一上限都会返回 `400`，并附带 `code: too_many_identifiers`。
- 查询仅搜索您的应用。## 请求```json theme={null}
{
  "identifiers": [
    "usr_8842",
    "maria.o@gmail.com",
    "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
    "usr_7001"
  ]
}
```## 响应```json theme={null}
{
  "lookup_id": "b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11",
  "requested": 4,
  "found": 3,
  "not_found": [{ "identifier": "usr_7001", "position": 4 }],
  "expires_at": "2026-11-19T10:30:00Z"
}
```| 字段 | 说明 |
| - | - |
| `lookup_id` | 将其作为 `lookup` 传入 [列出用户](https://docs.didit.me/zh/management-api/users/list.md)。 |
| `requested` | 已读取的标识符，已去除空白项和重复项。 |
| `found` | 至少匹配到一个用户的标识符。 |
| `not_found` | 未匹配到任何用户的标识符。每个标识符都附有其在提交的去重列表中从 1 开始计数的 `position`，便于您在源头修正该列表。 |
| `expires_at` | 结果过期的时间。 |## 读取匹配的用户```bash theme={null}
curl -X GET 'https://verification.didit.me/v3/users/?lookup=b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11&limit=200' \
  -H 'x-api-key: YOUR_API_KEY'
```- 用户按照其标识符在您列表中的顺序返回，并使用 `limit` 和 `offset` 分页。当一个邮箱匹配多个用户时，账户创建最早的排在前面。
- 结果仅供您的应用使用，保留 24 小时。之后，`lookup` 会返回 `404` 和 `code: lookup_not_found`：请重新提交列表。## 读取已提交的查询`GET /v3/users/lookup/{lookup_id}/` 返回与查询相同的响应体，另外包含 `identifiers`：即您提交的列表，已去除空白值和重复值，并保持原有顺序。
当查询已过期、不存在或属于其他应用时，接口返回 `404`，并带有 `code: lookup_not_found`。## 错误| 状态 | 含义 |
| - | - |
| `400` | 验证错误：提交的条目超过 100,000 条，或清理后的标识符超过 20,000 个时返回 `too_many_identifiers`；列表为空时返回 `{"identifiers": ["Add at least one identifier."]}`。 |
| `401` | 缺少 `x-api-key`，或其值无效。 |
| `403` | 该密钥无权读取此应用的用户。 |
| `404` | `lookup_not_found`：该查询已过期、不存在，或属于其他应用。 |
| `429` | 超出速率限制。请遵守 `Retry-After`。 |## 权限API 密钥需要具备用户的**读取**权限，且该端点从不修改数据。没有此权限的密钥或已撤销的密钥会返回 `403`。
密钥范围按密钥分别设置，详见 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)。控制台的 [角色与权限](https://docs.didit.me/zh/console/roles-permissions.md) 决定人员在控制台中可以执行的操作，不用于评估 API 请求。
在控制台中，[查询列表](https://docs.didit.me/zh/entities/users/console.md#查询列表) 仅需要读取用户的权限。## 相关内容- [列出用户](https://docs.didit.me/zh/management-api/users/list.md)
- [控制台中的用户](https://docs.didit.me/zh/entities/users/console.md)
- [用户概览](https://docs.didit.me/zh/entities/users/overview.md)


## OpenAPI

````yaml zh/openapi-25.json POST /v3/users/lookup/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: Identity verification API. Authenticate with x-api-key header.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/users/lookup/:
    post:
      tags:
        - Users
      summary: Look up users
      description: >-
        Resolve a list of up to 20,000 identifiers to the users of your
        application, in one call. Each identifier is matched, in this order,
        against `vendor_data` (exactly), the Didit user ID (a UUID), then a
        verified email (case-insensitive). An email can match several users, and
        all of them count. Blank entries are dropped and duplicates removed,
        keeping the first; 1 to 20,000 identifiers must remain, and a request
        sends at most 100,000 entries before that clean-up. The call only reads.
        It answers with a `lookup_id`, the counts and the identifiers that
        matched nobody, each with its 1-based `position` in the submitted list.


        Pass the `lookup_id` as `lookup` to [List users](#get-/v3/users/) to
        page through exactly the matched users, in the order you submitted them.
        The result is kept for 24 hours for your application only, then answers
        `404` with `code: lookup_not_found`.
      operationId: lookup_users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsersLookupRequest'
            examples:
              Mixed identifiers:
                value:
                  identifiers:
                    - usr_8842
                    - maria.o@gmail.com
                    - f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418
                    - usr_7001
      responses:
        '201':
          description: The lookup was read. Use `lookup_id` with List users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersLookupResponse'
              examples:
                Example:
                  value:
                    lookup_id: b3a6f0c2-6a2e-4c0a-9d0e-5f3c1d2a7e11
                    requested: 4
                    found: 3
                    not_found:
                      - identifier: usr_7001
                        position: 4
                    expires_at: '2026-11-19T10:30:00Z'
        '400':
          description: >-
            Validation error. `too_many_identifiers` when the request holds more
            than 100,000 entries, or more than 20,000 identifiers once blanks
            and duplicates are removed. An empty list is keyed by field name.
          content:
            application/json:
              examples:
                Too many:
                  value:
                    detail: A lookup takes at most 20000 identifiers.
                    code: too_many_identifiers
                Empty:
                  value:
                    identifiers:
                      - Add at least one identifier.
        '401':
          description: No credentials supplied.
          content:
            application/json:
              examples:
                Missing credentials:
                  value:
                    detail: >-
                      You must be authenticated with a valid access token to
                      access this endpoint.
        '403':
          description: >-
            Invalid or revoked API key, or the key cannot read users for this
            application.
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    detail: You do not have permission to perform this action.
        '429':
          description: >-
            Rate limit exceeded; back off and retry after the interval indicated
            in `Retry-After`.
          content:
            application/json:
              examples:
                Rate limited:
                  value:
                    detail: >-
                      Write request rate limit exceeded. You can make up to 300
                      requests per minute.
                    reference: RL-00000000000040008000000000000001
                    limit: 300
                    remaining: 0
                    reset: 1794358860
                    window_seconds: 60
              schema:
                $ref: '#/components/schemas/RateLimitBudgetError'
          headers:
            Retry-After:
              $ref: '#/components/headers/BudgetRetryAfter'
            X-RateLimit-Scope:
              $ref: '#/components/headers/BudgetXRateLimitScope'
            X-RateLimit-Limit:
              $ref: '#/components/headers/BudgetXRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/BudgetXRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/BudgetXRateLimitReset'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.users.lookup(
                identifiers=["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"],
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.users.lookup({
              identifiers: ["usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"],
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Lookup(ctx, didit.UsersLookupRequest{\n\tIdentifiers: []string{\"usr_8842\", \"maria.o@gmail.com\", \"f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418\", \"usr_7001\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: |-
            import java.util.List;
            import me.didit.Didit;
            import me.didit.types.UsersLookupRequest;

            // Reads DIDIT_API_KEY.
            Didit client = new Didit();

            var result = client.users().lookup(UsersLookupRequest.builder()
                    .identifiers(List.of("usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001"))
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->users->lookup([
                'identifiers' => ['usr_8842', 'maria.o@gmail.com', 'f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418', 'usr_7001'],
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result = didit.users.lookup(identifiers: ["usr_8842",
            "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
            "usr_7001"])

            puts result.to_h
        - lang: csharp
          label: .NET
          source: |-
            using System;
            using System.Text.Json;
            using Didit;

            // Reads DIDIT_API_KEY.
            using var client = new DiditClient();

            var result = await client.Users.LookupAsync(new UsersLookupRequest
            {
                Identifiers = new string[] { "usr_8842", "maria.o@gmail.com", "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "usr_7001" },
            });
            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    UsersLookupRequest:
      type: object
      required:
        - identifiers
      properties:
        identifiers:
          type: array
          items:
            type: string
          description: >-
            Each entry is a `vendor_data` value, a Didit user ID or a verified
            email. Send at most 100,000 entries. Blank entries are dropped and
            duplicates removed, keeping the first, and at most 20,000
            identifiers must remain. Either limit exceeded is a `400` with
            `code: too_many_identifiers`, and an empty list is a `400` too.
          example:
            - usr_8842
            - maria.o@gmail.com
          maxItems: 100000
    UsersLookupResponse:
      type: object
      properties:
        lookup_id:
          type: string
          format: uuid
          description: Pass it as `lookup` to List users.
        requested:
          type: integer
          description: Identifiers read, after blanks and duplicates were removed.
        found:
          type: integer
          description: Identifiers that matched at least one user.
        not_found:
          type: array
          items:
            $ref: '#/components/schemas/UsersLookupNotFound'
        expires_at:
          type: string
          format: date-time
          description: When the result expires (24 hours after the lookup).
      required:
        - lookup_id
        - requested
        - found
        - not_found
        - expires_at
    RateLimitBudgetError:
      type: object
      description: >-
        Returned only for a rate-limit middleware budget refusal. Other 429
        errors, including idempotency conflicts and endpoint-specific caps, do
        not promise these metadata fields.
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: Existing human-readable budget refusal message.
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: >-
            Opaque support reference: RL- followed by 32 lowercase UUID
            hexadecimal characters.
        limit:
          type: integer
          description: Budget for the exceeded scope; equals X-RateLimit-Limit.
        remaining:
          type: integer
          minimum: 0
          description: Remaining budget, clamped to zero; equals X-RateLimit-Remaining.
        reset:
          type: integer
          format: int64
          description: Window reset time in Unix seconds; equals X-RateLimit-Reset.
        window_seconds:
          type: integer
          description: >-
            Fixed-window duration in seconds, not the remaining wait. Honor
            Retry-After before retrying.
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    UsersLookupNotFound:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier that matched no user.
        position:
          type: integer
          minimum: 1
          description: >-
            1-based position in the submitted list, after blanks and duplicates
            were removed.
      required:
        - identifier
        - position
  headers:
    BudgetRetryAfter:
      description: >-
        Seconds to wait, rounded up to the next window. Present on middleware
        budget refusals.
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: >-
        The scope whose budget was exceeded. Present on middleware budget
        refusals.
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: >-
        Budget for the exceeded scope; equals body limit. Present on middleware
        budget refusals.
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: >-
        Remaining budget, clamped to zero; equals body remaining. Present on
        middleware budget refusals.
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: >-
        Reset time in Unix seconds; equals body reset. Present on middleware
        budget refusals.
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your application's API key, from Developers -> API keys in the Business
        Console. The primary key has full access. A named key can be scoped:
        none, read or write per resource, limited to some workflows or to
        approved sessions, to a list of IP addresses, and to an expiry date. 401
        means the key is wrong, revoked or expired; 403 means no key was sent,
        the key has no access to this resource or action, or the request came
        from an address outside its IP list; 404 on a session route means the
        session is outside the key's workflows or statuses. A key without media
        access receives image, video and PDF URLs as null, and a key without
        sessions write receives session links and tokens as null. See
        https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.