> ## 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: التحقق من قائمة المعرّفات

> استعلم عن حتى 20,000 معرّف بائع أو معرّف مستخدم في Didit أو بريد إلكتروني في طلب واحد، وأعد المستخدمين بالترتيب الذي أرسلته.



موجّه البحث عن المستخدمين
        نسخ الموجّه إلى الحافظة



      
      

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



      
      

الصق في

تربط واجهة API للبحث عن المستخدمين من Didit قائمة تضم حتى 20,000 معرّف بمستخدمي تطبيقك في استدعاء واحد، وتُخبرك بالمعرّفات التي لم تطابق أي مستخدم.
استخدمها عندما تملك قائمة بالحسابات، مثل المستفيدين في دفعة تحويلات، أو حسابات أحد الشركاء، أو نتائج استعلام احتيال، وتحتاج إلى حالة التحقق لكل منها.## كيف يعمل1) **ابحث في القائمة.** `POST /v3/users/lookup/` مع المعرّفات الخاصة بك. هذا الاستدعاء للقراءة فقط، ويعيد `lookup_id` والأعداد والمعرّفات التي لم تطابق أي مستخدم.
2) **اقرأ المستخدمين.** مرّر `lookup_id` بوصفه `lookup` إلى [قائمة المستخدمين](https://docs.didit.me/ar/management-api/users/list.md). يعيد هذا الاستدعاء المستخدمين المطابقين فقط، بالترتيب نفسه الذي أرسلت به المعرّفات.## قواعد المطابقةتُطابَق كل معرّف داخل تطبيقك، بالترتيب التالي:| الترتيب | تُطابَق مع | القاعدة |
| - | - | - |
| 1 | `vendor_data` | مطابقة تامة |
| 2 | معرّف مستخدم Didit | 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/ar/management-api/users/list.md). |
| `requested` | المعرّفات التي قُرئت، بعد حذف القيم الفارغة والتكرارات. |
| `found` | المعرّفات التي طابقت مستخدمًا واحدًا على الأقل. |
| `not_found` | المعرّفات التي لم تطابق أي مستخدم، ولكل منها `position` يبدأ العد من 1 في القائمة المرسلة بعد إزالة التكرارات، حتى تتمكن من تصحيح القائمة من مصدرها. |
| `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` | خطأ في التحقق: `too_many_identifiers` عند إرسال أكثر من 100,000 إدخال، أو أكثر من 20,000 معرّف بعد التنظيف، أو `{"identifiers": ["Add at least one identifier."]}` عند إرسال قائمة فارغة. |
| `401` | مفتاح `x-api-key` مفقود أو غير صالح. |
| `403` | لا يمكن لمفتاح API هذا قراءة المستخدمين لهذا التطبيق. |
| `404` | `lookup_not_found`: انتهت صلاحية عملية البحث، أو لا وجود لها، أو أنها تابعة لتطبيق آخر. |
| `429` | تجاوز حد المعدل. احترم قيمة `Retry-After`. |## الأذوناتيحتاج مفتاح API إلى إذن **القراءة** للمستخدمين، ولا يُغيّر endpoint أي بيانات أبداً. ويُرجع أي مفتاح بدون هذا الإذن، أو أي مفتاح ملغى، الاستجابة `403`.
تُحدَّد نطاقات المفتاح لكل مفتاح على حدة في [مفاتيح API](https://docs.didit.me/ar/console/api-keys.md)، أما [الأدوار والأذونات](https://docs.didit.me/ar/console/roles-permissions.md) في لوحة التحكم فتحدد ما يمكن للشخص فعله داخل لوحة التحكم، ولا تُقيَّم في حركة مرور API.
في لوحة التحكم، يحتاج [البحث عن قائمة](https://docs.didit.me/ar/entities/users/console.md#البحث-عن-قائمة) إلى إذن قراءة المستخدمين فقط.## ذات صلة- [سرد المستخدمين](https://docs.didit.me/ar/management-api/users/list.md)
- [المستخدمون في وحدة التحكم](https://docs.didit.me/ar/entities/users/console.md)
- [نظرة عامة على المستخدمين](https://docs.didit.me/ar/entities/users/overview.md)


## OpenAPI

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