> ## 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.

# Benutzer abfragen API: Liste von IDs prüfen

> Bis zu 20,000 Vendor-IDs, Didit-IDs oder E-Mails in einem Aufruf Benutzern zuordnen und genau diese Benutzer in Ihrer Reihenfolge mit Didit abrufen.



Prompt zum Nachschlagen von Benutzern
        Prompt in die Zwischenablage kopieren



      
      

\<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>



      
      

Einfügen in

Die Look-Up-Users-API von Didit ordnet eine Liste mit bis zu 20.000 Kennungen in einem einzigen Aufruf den Benutzern Ihrer Anwendung zu und zeigt Ihnen an, welche Kennungen keinem Benutzer entsprechen.
Verwenden Sie sie, wenn Sie eine Liste von Konten haben, etwa die Empfänger eines Auszahlungsstapels, die Konten eines Partners oder das Ergebnis einer Betrugsabfrage, und den Verifizierungsstatus jedes einzelnen Kontos benötigen.## So funktioniert es1) **Liste abfragen.** `POST /v3/users/lookup/` mit Ihren Kennungen. Der Aufruf liest nur und liefert eine `lookup_id`, die Anzahlen sowie die Kennungen, denen kein Benutzer zugeordnet wurde.
2) **Benutzer abrufen.** Übergeben Sie die `lookup_id` als `lookup` an [Benutzer auflisten](https://docs.didit.me/de/management-api/users/list.md). Es werden nur die übereinstimmenden Benutzer zurückgegeben, und zwar in der Reihenfolge, in der Sie die Kennungen übermittelt haben.## AbgleichsregelnJede Kennung wird innerhalb Ihrer Anwendung in dieser Reihenfolge abgeglichen:| Reihenfolge | Abgeglichen mit | Regel |
| - | - | - |
| 1 | `vendor_data` | Exakte Übereinstimmung |
| 2 | Didit-Benutzer-ID | Eine UUID, die `didit_internal_id` des Benutzers ist |
| 3 | Verifizierte E-Mail-Adresse | Groß- und Kleinschreibung wird nicht beachtet. Eine E-Mail-Adresse kann mehreren Benutzern zugeordnet sein, und alle diese Benutzer zählen. |- Leere Einträge werden verworfen. Doppelte Einträge werden entfernt, wobei das erste Vorkommen erhalten bleibt.
- Eine Anfrage darf höchstens 100.000 Einträge enthalten. Nachdem leere Einträge und Duplikate entfernt wurden, müssen zwischen 1 und 20.000 Kennungen übrig bleiben. Wird eines der beiden Limits überschritten, gibt die Anfrage `400` mit `code: too_many_identifiers` zurück.
- Die Suche erfolgt ausschließlich in Ihrer Anwendung.## Anfrage```json theme={null}
{
  "identifiers": [
    "usr_8842",
    "maria.o@gmail.com",
    "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
    "usr_7001"
  ]
}
```## Antwort```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"
}
```| Feld | Beschreibung |
| - | - |
| `lookup_id` | Übergeben Sie sie als `lookup` an [Benutzer auflisten](https://docs.didit.me/de/management-api/users/list.md). |
| `requested` | Die gelesenen Kennungen, nachdem leere Einträge und Duplikate entfernt wurden. |
| `found` | Kennungen, die mindestens einem Benutzer entsprechen. |
| `not_found` | Die Kennungen, denen kein Benutzer entspricht, jeweils mit ihrer 1-basierten `position` in der übermittelten, deduplizierten Liste, damit Sie die Liste an der Quelle korrigieren können. |
| `expires_at` | Zeitpunkt, zu dem das Ergebnis abläuft. |## Die gefundenen Benutzer abrufen```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'
```- Benutzer werden in der Reihenfolge ihrer Kennung in Ihrer Liste zurückgegeben und mit `limit` und `offset` paginiert. Wenn eine E-Mail-Adresse mehreren Benutzern zugeordnet ist, werden diese nach Kontoalter aufsteigend aufgelistet, das älteste Konto zuerst.
- Das Ergebnis wird 24 Stunden lang nur für Ihre Anwendung aufbewahrt. Danach gibt `lookup` `404` mit `code: lookup_not_found` zurück: Senden Sie die Liste erneut.## Einen Lookup abrufen`GET /v3/users/lookup/{lookup_id}/` gibt denselben Antworttext zurück wie der Lookup, zusätzlich `identifiers`: die Liste, die Sie übermittelt haben, nachdem leere Einträge und Duplikate entfernt wurden, in der übermittelten Reihenfolge.
Der Endpoint antwortet mit `404` und `code: lookup_not_found`, wenn der Lookup abgelaufen ist, nicht existiert oder zu einer anderen Anwendung gehört.## Errors| Status | Bedeutung |
| - | - |
| `400` | Validierungsfehler: `too_many_identifiers` bei mehr als 100.000 übermittelten Einträgen oder mehr als 20.000 Identifikatoren nach der Bereinigung, oder `{"identifiers": ["Add at least one identifier."]}` bei einer leeren Liste. |
| `401` | Fehlender oder ungültiger `x-api-key`. |
| `403` | Der API-Schlüssel darf für diese Anwendung keine Benutzer lesen. |
| `404` | `lookup_not_found`: Das Lookup ist abgelaufen, existiert nicht oder gehört zu einer anderen Anwendung. |
| `429` | Rate-Limit überschritten. Beachten Sie den `Retry-After`-Header. |## BerechtigungenDer API-Schlüssel benötigt **Lesezugriff** auf Benutzer, und der Endpoint ändert niemals Daten. Ein Schlüssel ohne diese Berechtigung oder ein widerrufener Schlüssel erhält `403`.
Die Scopes eines Schlüssels werden pro Schlüssel in den [API-Schlüsseln](https://docs.didit.me/de/console/api-keys.md) festgelegt. Die [Rollen und Berechtigungen](https://docs.didit.me/de/console/roles-permissions.md) der Console bestimmen, was eine Person in der Console tun darf, und werden für API-Anfragen nicht geprüft.
In der Console benötigt [Liste abfragen](https://docs.didit.me/de/entities/users/console.md#liste-abfragen) nur die Berechtigung, Benutzer zu lesen.## Verwandte Themen- [Benutzer auflisten](https://docs.didit.me/de/management-api/users/list.md)
- [Benutzer in der Console](https://docs.didit.me/de/entities/users/console.md)
- [Übersicht über Benutzer](https://docs.didit.me/de/entities/users/overview.md)


## OpenAPI

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