> ## 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로 vendor ID, Didit 사용자 ID 또는 이메일 최대 20,000개를 한 번의 호출로 사용자에 매칭하고, 보낸 순서대로 해당 사용자를 나열합니다.



사용자 조회 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<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/ko/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` | [사용자 목록 조회](https://docs.didit.me/ko/management-api/users/list.md)에 `lookup` 파라미터로 전달합니다. |
| `requested` | 공백과 중복을 제거한 후 읽은 식별자입니다. |
| `found` | 하나 이상의 사용자와 일치한 식별자입니다. |
| `not_found` | 일치하는 사용자가 없었던 식별자입니다. 각 항목에는 제출되고 중복이 제거된 목록에서의 1부터 시작하는 `position`이 함께 제공되므로, 원본에서 목록을 수정할 수 있습니다. |
| `expires_at` | 결과가 만료되는 시점입니다. |## Read the matched users```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` | 해당 API 키로는 이 애플리케이션의 사용자를 조회할 수 없습니다. |
| `404` | `lookup_not_found`: 조회가 만료되었거나, 존재하지 않거나, 다른 애플리케이션에 속합니다. |
| `429` | 속도 제한을 초과했습니다. `Retry-After` 헤더 값에 따라 대기한 후 다시 요청하십시오. |## 권한API 키에는 사용자에 대한 **읽기** 권한이 있어야 하며, 이 엔드포인트는 데이터를 절대 변경하지 않습니다. 이 권한이 없는 키나 해지된 키는 `403`을 받게 됩니다.
키 범위는 키별로 [API 키](https://docs.didit.me/ko/console/api-keys.md)에서 설정합니다. Console의 [역할 및 권한](https://docs.didit.me/ko/console/roles-permissions.md)은 사용자가 Console에서 할 수 있는 작업을 결정하며, API 트래픽에는 적용되지 않습니다.
Console에서 [목록 조회](https://docs.didit.me/ko/entities/users/console.md#목록-조회)에는 사용자 읽기 권한만 있으면 됩니다.## 관련 문서- [사용자 목록 조회](https://docs.didit.me/ko/management-api/users/list.md)
- [콘솔의 사용자](https://docs.didit.me/ko/entities/users/console.md)
- [사용자 개요](https://docs.didit.me/ko/entities/users/overview.md)


## OpenAPI

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