> ## 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 APIで、ベンダーID・DiditユーザーID・メールアドレスを最大20,000件まで1回の呼び出しで照合し、送信した順番どおりにユーザーを返します。



ユーザー照会プロンプト
        プロンプトをクリップボードにコピー



      
      

\<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回の呼び出しでアプリケーションのユーザーに対応付け、一致するユーザーがいなかった識別子を示します。
アカウントのリストがあり、各アカウントの認証ステータスが必要な場合に使用します。たとえば、支払いバッチの受取人、パートナーのアカウント、不正検知クエリの出力などが該当します。## 仕組み1) **照合を実行。** `POST /v3/users/lookup/` に識別子を指定して呼び出します。この呼び出しは読み取りのみを行い、`lookup_id`、件数、一致するユーザーがいなかった識別子を返します。
2) **ユーザーを読み取る。** `lookup_id` を `lookup` として [ユーザーを一覧表示](https://docs.didit.me/ja/management-api/users/list.md) に渡します。返されるのは一致したユーザーのみで、識別子を送信した順序で並びます。## 照合ルール各識別子は、お客様のアプリケーション内で次の順序で照合されます。| 順序 | 照合対象 | ルール |
| - | - | - |
| 1 | `vendor_data` | 完全一致 |
| 2 | Didit ユーザーID | UUID（ユーザーの`didit_internal_id`） |
| 3 | 認証済みメールアドレス | 大文字と小文字を区別しません。1つのメールアドレスが複数のユーザーに一致する場合があり、一致したユーザーはすべて対象になります。 |- 空の項目は除外され、重複は最初の項目を残して削除されます。
- 1回のリクエストで送信できる項目は最大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` | [ユーザー一覧を取得](https://docs.didit.me/ja/management-api/users/list.md)に`lookup`として渡します。 |
| `requested` | 空の値と重複を取り除いた後に読み取られた識別子です。 |
| `found` | 1人以上のユーザーに一致した識別子です。 |
| `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` でページ分割されます。1つのメールアドレスが複数のユーザーに一致する場合は、アカウントが古い順に並びます。
- 結果は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/ja/console/api-keys.md)ごとに設定します。コンソールの[ロールと権限](https://docs.didit.me/ja/console/roles-permissions.md)は、コンソール内でユーザーができる操作を決めるもので、APIトラフィックには評価されません。
コンソールでは、[リストを検索](https://docs.didit.me/ja/entities/users/console.md#リストを照会する)するには、ユーザーの読み取り権限のみが必要です。## 関連情報- [ユーザーを一覧表示](https://docs.didit.me/ja/management-api/users/list.md)
- [Consoleのユーザー](https://docs.didit.me/ja/entities/users/console.md)
- [ユーザーの概要](https://docs.didit.me/ja/entities/users/overview.md)


## OpenAPI

````yaml ja/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.