> ## 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: حظر المستخدم أو تمييزه
> حظر مستخدم Didit أو تمييزه أو تفعيله. تنتقل الحالة إلى جلسات KYC المقبلة وفحص المعاملات. إدارة المستخدمين بالدفع لكل استدعاء.
موجه تحديث حالة المستخدم
نسخ الموجّه إلى الحافظة
\
\`Goal: Flip ONLY the lifecycle status of a Didit User entity. Use the full PATCH /v3/users/{vendor_data}/ when you also need to touch other fields.
Endpoint: PATCH https://verification.didit.me/v3/users/{vendor_data}/update-status/
Auth header: x-api-key:
Content-Type: application/json
Path param:
\- vendor_data (string, REQUIRED) — free-form string, NOT a UUID. URL-encode.
Request body:
\- status (enum, REQUIRED) — "ACTIVE" | "FLAGGED" | "BLOCKED" (VendorUserStatusChoices, NOT the session enum).
\- reason (string, optional, max 1000): why the status changed. Recorded as the comment of the STATUS_CHANGED entry in the user's activity (comments[].comment), only when the status actually changes. Webhooks do not carry it.
Status semantics:
\- ACTIVE → normal. New sessions allowed for this vendor_data.
\- FLAGGED → still accepted, highlighted in Console for manual review; filterable with ?status=FLAGGED.
\- BLOCKED → terminal. Adds vendor_data to the system blocklist. Subsequent session creations for the same identifier are rejected with a blocklist hit. Flipping back to ACTIVE/FLAGGED removes the blocklist entry automatically.
curl:
curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"status": "BLOCKED", "reason": "Chargeback fraud pattern confirmed"}'
Response 200: full updated UserDetailItem (same shape as GET /v3/users/{vendor_data}/). See /reference/data-models.
Side effects:
\- Toggles the system blocklist entry when entering/leaving BLOCKED.
\- Writes one STATUS_CHANGED entry to the user's comments activity log (actor = API key identity), with reason as its comment.
\- Idempotent — re-sending the same status is a no-op (no extra audit row, no extra blocklist toggle).
Failure modes:
\- 400 — validation:
\{ "status": "This field is required." }
\{ "status": "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" }
\{ "reason": ["Ensure this field has no more than 1000 characters."] }
\- 401 — missing/invalid x-api-key. { "detail": "Authentication credentials were not provided." }
\- 403 — the API key is revoked or is not valid for this application. { "detail": "You do not have permission to perform this action." }
\- 403: a scoped API key without users write. { "detail": "This API key has no write access to people." }
\- 404 — vendor_data not found (or deleted). { "detail": "Not found." }
\- 429 — rate-limited.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
الصق في
## نظرة عامةينقل [كيان المستخدم](https://docs.didit.me/ar/entities/users/overview.md) بين `ACTIVE` و`FLAGGED` و`BLOCKED`. راجع [دورة حياة الكيان](https://docs.didit.me/ar/entities/lifecycle.md) للاطلاع على آلة الحالات كاملة.## متى تستخدمه- **حظر مستخدم** بعد التأكد من وجود احتيال أو خرق للامتثال.
- **وضع علامة على مستخدم** بانتظار المراجعة اليدوية دون حظره حظراً كاملاً.
- **إلغاء الحظر** عن مستخدم بعد معالجة الوضع بنجاح.
- **نقل الإشارات الخارجية**: مثلاً عندما يمنح محرك الاحتيال الخاص بك مستخدماً درجة أعلى من الحد، انقله إلى `FLAGGED` عبر هذه الواجهة.## ملاحظات- القيم الصالحة هي `ACTIVE` و`FLAGGED` و`BLOCKED`. القيم غير الصالحة تُرجع 400.
- مرّر `reason` اختيارياً (حتى 1000 حرف) لتسجيل سبب تغيير الحالة.
يحتفظ Didit به كتعليق على إدخال تغيير الحالة في نشاط الشخص: `comments[].comment` في المستخدم، و**النشاط** في Business Console.
يُسجَّل فقط عندما تتغير الحالة فعلاً.
- تُرفض تلقائياً جميع الجلسات الجديدة وجميع المعاملات الجديدة للمستخدمين في حالة `BLOCKED`.
- يُصدر webhook من نوع `user.status.updated` مع `previous_status` و`status`.
لا يتضمن webhook الحقل `reason`.## الإنفاذ| الحالة | الأثر على الجلسات الجديدة | الأثر على المعاملات الجديدة |
| - | - | - |
| `ACTIVE` | المسار العادي | المسار العادي |
| `FLAGGED` | مسموح بها لكن تُوجَّه إلى `IN_REVIEW` | مسموح بها؛ قد تُصعَّد تلقائياً حسب القواعد |
| `BLOCKED` | رفض تلقائي | رفض تلقائي |## الأذوناتيمكن للمفتاح السري الرئيسي و[مفاتيح API](https://docs.didit.me/ar/console/api-keys.md) ذات الصلاحيات الكاملة استدعاء هذا endpoint في أي وقت.
يحتاج المفتاح ذو الوصول المخصص إلى صلاحية الكتابة على **الأشخاص** (`users`).
لا يستطيع المفتاح المقيّد ببعض سير العمل أو بالجلسات المعتمدة الوصول إلى هذا endpoint.تحدد [الأدوار والأذونات](https://docs.didit.me/ar/console/roles-permissions.md) في Console ما يمكن لعضو الفريق فعله داخل Console.
لا تُقيَّم هذه الأذونات لطلبات مفاتيح API.## ذات صلة- [دورة حياة الكيان](https://docs.didit.me/ar/entities/lifecycle.md)
- [قائمة حظر المستخدمين](https://docs.didit.me/ar/entities/users/blocklist.md)
- [webhooks للكيانات](https://docs.didit.me/ar/entities/webhooks.md)
## OpenAPI
````yaml ar/openapi-25.json PATCH /v3/users/{vendor_data}/update-status/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/users/{vendor_data}/update-status/:
patch:
tags:
- Users
summary: تحديث حالة المستخدم
description: >-
تبديل `status` دورة الحياة فقط للمستخدم: `ACTIVE` أو `FLAGGED` أو
`BLOCKED` (وليس حالات الجلسة). يضيف `BLOCKED` قيمة `vendor_data` إلى
قائمة الحظر في النظام؛ ويؤدي التغيير من `BLOCKED` إلى إزالة هذا الإدخال.
يتم تسجيل كل تغيير كنشاط `STATUS_CHANGED` على المستخدم، مع `reason`
الاختياري كـ `comment` له. لا يؤدي إرسال الحالة الحالية إلى تغيير أي شيء
ولا يسجل أي `reason`. لا يحمل webhook الخاص بـ `user.status.updated`
الحقل `reason`.
operationId: update_user_status
parameters:
- name: vendor_data
in: path
required: true
schema:
type: string
description: معرّفك الفريد للمستخدم.
requestBody:
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EntityStatusUpdateRequest'
- type: object
properties:
reason:
type: string
nullable: true
maxLength: 1000
description: >-
سبب تغيير الحالة. يُسجّل في قيد تغيير الحالة ضمن سجل
نشاط المستخدم (`comments[].comment`، و**Activity** في
Business Console)، فقط عندما تتغير الحالة فعلياً. لا
تتضمنه أحداث webhook.
examples:
Activate:
summary: إعادة تفعيل المستخدم
value:
status: ACTIVE
Flag:
summary: وضع علامة على المستخدم للمراجعة
value:
status: FLAGGED
Block:
summary: حظر المستخدم (إضافته إلى قائمة الحظر الخاصة بالنظام)
value:
status: BLOCKED
Block with reason:
summary: حظر المستخدم وتسجيل السبب
value:
status: BLOCKED
reason: Chargeback fraud pattern confirmed
responses:
'200':
description: تم تحديث حالة المستخدم. تم إرجاع سجل المستخدم الكامل.
content:
application/json:
schema:
$ref: '#/components/schemas/UserDetailItem'
examples:
Blocked:
value:
didit_internal_id: f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418
vendor_data: user-abc-123
display_name: null
full_name: John Michael Doe
date_of_birth: '1990-05-15'
effective_name: John Michael Doe
status: BLOCKED
metadata:
tier: premium
source: website
portrait_image_url: https:///...
session_count: 3
approved_count: 2
declined_count: 0
in_review_count: 1
issuing_states:
- USA
approved_emails:
- john@example.com
approved_phones:
- '+14155551234'
features:
ID_VERIFICATION: Approved
LIVENESS: Approved
FACE_MATCH: Approved
AML: Approved
features_list:
- feature: ID_VERIFICATION
status: Approved
- feature: LIVENESS
status: Approved
- feature: FACE_MATCH
status: Approved
- feature: AML
status: Approved
last_session_at: '2025-06-15T10:30:00Z'
last_activity_at: '2025-06-15T10:30:00Z'
first_session_at: '2025-06-01T08:00:00Z'
tags:
- uuid: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
tag:
uuid: e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b
name: VIP
color: '#2567FF'
description: null
source: custom
created_at: '2025-05-01T09:00:00Z'
updated_at: '2025-05-01T09:00:00Z'
added_by_email: analyst@acme.com
added_by_name: Jane Analyst
created_at: '2025-06-02T11:00:00Z'
comments:
- uuid: c1111111-2222-4333-8444-555555555555
comment_type: STATUS_CHANGED
comment: Chargeback fraud pattern confirmed
actor_email: null
actor_name: null
previous_status: ACTIVE
new_status: BLOCKED
previous_value: null
new_value: null
changed_fields: []
metadata: null
mentioned_emails: []
created_at: '2025-06-15T10:30:00Z'
created_at: '2025-06-01T08:00:00Z'
updated_at: '2025-06-15T10:30:00Z'
'400':
description: حقل `status` مفقود أو غير صالح، أو `reason` يتجاوز 1000 حرف.
content:
application/json:
examples:
Missing status:
value:
status:
- This field is required.
Bad status:
value:
status:
- >-
Invalid status. Valid options are: ACTIVE, FLAGGED,
BLOCKED
Reason too long:
value:
reason:
- Ensure this field has no more than 1000 characters.
'401':
description: >-
لم يتم توفير بيانات اعتماد. الطلبات المرسلة إلى مسارات `/v3/users/*`
بدون رأس `x-api-key` (أو رمز `Authorization: Bearer`) يتم رفضها
بواسطة برمجية المصادقة الوسيطة قبل وصولها إلى الـ API.
content:
application/json:
examples:
Missing credentials:
value:
detail: >-
You must be authenticated with a valid access token to
access this endpoint.
'403':
description: >-
لا يمكن للمفتاح تحديث المستخدمين لهذا التطبيق. يؤدي غياب المفتاح إلى
إرجاع `403`؛ بينما يُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية
`401`.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: >-
لا يوجد مستخدم (غير محذوف) ببيانات `vendor_data` المقدمة لهذا
التطبيق.
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: >-
تم تجاوز حد المعدل؛ تراجع مؤقتاً وأعد المحاولة بعد الفاصل الزمني
الموضح في `Retry-After`.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X PATCH
'https://verification.didit.me/v3/users/user-abc-123/update-status/'
\
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"status": "BLOCKED"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.update_status(
"user-123",
status="ACTIVE",
)
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.updateStatus("user-123", {
status: "ACTIVE",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.UpdateStatus(ctx, \"user-123\", didit.UsersUpdateStatusParams{\n\tStatus: \"ACTIVE\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.EntityStatusUpdateRequest;
import me.didit.types.UsersUpdateStatusParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().updateStatus("user-123",
UsersUpdateStatusParams.builder()
.status(EntityStatusUpdateRequest.Status.of("ACTIVE"))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
users->updateStatus('user-123', [
'status' => 'ACTIVE',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.update_status(
"user-123",
status: "ACTIVE"
)
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.UpdateStatusAsync("user-123", new
UsersUpdateStatusParams
{
Status = "ACTIVE",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
EntityStatusUpdateRequest:
type: object
required:
- status
properties:
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
حالة دورة الحياة الجديدة. يؤدي استخدام `BLOCKED` أيضاً إلى إضافة
`vendor_data` إلى قائمة الحظر الخاصة بالنظام.
UserDetailItem:
type: object
description: >-
تفاصيل المستخدم الكاملة. يوسع UserListItem بالبيانات الوصفية،
والتعليقات، وحقل updated_at.
allOf:
- $ref: '#/components/schemas/UserListItem'
- type: object
properties:
metadata:
type: object
description: >-
بيانات وصفية مخصصة بتنسيق JSON أرفقتها بهذا المستخدم. القيمة
الافتراضية هي `{}`.
tags:
type: array
description: >-
تعيينات العلامات. ملاحظة: في استجابات التفاصيل يكون كل إدخال
كائن *ربط* علامة (`{uuid, tag: {...}, added_by_email,
added_by_name, created_at}`)، على عكس التنسيق المسطح `{uuid,
name, color}` المُستخدم في استجابات القوائم.
items:
type: object
properties:
uuid:
type: string
format: uuid
description: معرّف UUID لتعيين الوسم (وليس الوسم نفسه).
tag:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description:
type: string
nullable: true
source:
type: string
enum:
- didit
- custom
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
added_by_email:
type: string
nullable: true
added_by_name:
type: string
nullable: true
created_at:
type: string
format: date-time
comments:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
comment_type:
type: string
enum:
- COMMENT
- STATUS_CHANGED
- METADATA_UPDATED
- TAG_ADDED
- TAG_REMOVED
- PROFILE_UPDATED
comment:
type: string
nullable: true
actor_email:
type: string
nullable: true
actor_name:
type: string
nullable: true
previous_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
new_status:
type: string
nullable: true
enum:
- ACTIVE
- FLAGGED
- BLOCKED
- null
previous_value:
type: object
nullable: true
description: قيم الحقول السابقة لإدخالات PROFILE_UPDATED.
new_value:
type: object
nullable: true
description: قيم الحقول الجديدة لمدخلات PROFILE_UPDATED.
changed_fields:
type: array
items:
type: string
description: أسماء الحقول التي تم تغييرها بواسطة إدخال PROFILE_UPDATED.
metadata:
type: object
nullable: true
mentioned_emails:
type: array
items:
type: string
created_at:
type: string
format: date-time
description: >-
سجل الأنشطة والتعليقات الخاصة بهذا المستخدم (تغييرات الحالة،
تعديلات الملف التعريفي، الملاحظات اليدوية).
updated_at:
type: string
format: date-time
UserListItem:
type: object
description: مستخدم تم التحقق منه.
properties:
didit_internal_id:
type: string
format: uuid
description: معرّف UUID الداخلي الثابت من Didit لهذا المستخدم.
vendor_data:
type: string
nullable: true
description: >-
معرّفك الفريد لهذا المستخدم (يتم تمريره عند إنشاء الجلسات). يمكن أن
يكون هذا null في حال عدم تقديم معرّف بائع.
display_name:
type: string
nullable: true
description: اسم عرض مخصص تم تعيينه بواسطتك
full_name:
type: string
nullable: true
description: الاسم الكامل المستخرج من المستندات التي تم التحقق منها
date_of_birth:
type: string
format: date
nullable: true
effective_name:
type: string
nullable: true
description: 'أفضل اسم متاح: display_name إذا كان محدداً، وإلا فـ full_name'
status:
type: string
enum:
- ACTIVE
- FLAGGED
- BLOCKED
description: >-
حالة دورة حياة سجل المستخدم (ليست حالة جلسة). القيمة الافتراضية هي
`ACTIVE`، و`FLAGGED` تميز المستخدم للمراجعة اليدوية، و`BLOCKED` تمنع
إنشاء جلسات جديدة لقيمة `vendor_data` هذه.
portrait_image_url:
type: string
nullable: true
description: >-
رابط موقع مسبقاً للصورة الشخصية للمستخدم (تنتهي صلاحيته بعد بضع
ساعات)
session_count:
type: integer
description: العدد الإجمالي لجلسات التحقق لهذا المستخدم
approved_count:
type: integer
description: عدد الجلسات المقبولة
declined_count:
type: integer
description: عدد الجلسات المرفوضة
in_review_count:
type: integer
description: عدد الجلسات قيد المراجعة
issuing_states:
type: array
items:
type: string
description: >-
رموز ISO 3166-1 alpha-3 لدول الإصدار الواردة في مستندات الهوية
المقبولة لهذا المستخدم، مثل `["USA", "ESP"]`. مصفوفة فارغة في حال
عدم وجود أي منها.
approved_emails:
type: array
items:
type: string
description: >-
عناوين البريد الإلكتروني التي تم التحقق منها والمجمعة من الجلسات
المقبولة لهذا المستخدم، على سبيل المثال `["john@example.com"]`.
approved_phones:
type: array
items:
type: string
description: >-
أرقام الهواتف التي تم التحقق منها والمجمعة من الجلسات المقبولة لهذا
المستخدم، على سبيل المثال `["+14155551234"]`.
features:
type: object
description: >-
الحالة المجمعة لكل ميزة عبر جميع جلسات هذا المستخدم. المفاتيح
المحتملة: `ID_VERIFICATION`، `NFC`، `LIVENESS`، `FACE_MATCH`، `POA`،
`QUESTIONNAIRE`، `EMAIL_VERIFICATION`، `PHONE`، `AML`،
`IP_ANALYSIS`، `AGE_ESTIMATION`، `DATABASE_VALIDATION`. القيم
المحتملة: `Approved`، `Declined`، `In Review`، `Not Finished`،
`Resub Requested`.
features_list:
type: array
items:
type: object
properties:
feature:
type: string
status:
type: string
description: >-
البيانات نفسها مثل `features`، كمصفوفة مرتبة من كائنات `{feature,
status}`.
last_session_at:
type: string
format: date-time
nullable: true
description: الطابع الزمني لأحدث جلسة
first_session_at:
type: string
format: date-time
nullable: true
description: الطابع الزمني للجلسة الأولى
last_activity_at:
type: string
format: date-time
nullable: true
description: >-
الطابع الزمني لأحدث نشاط لهذا المستخدم (جلسة، معاملة، تغيير حالة،
تعديل بيانات، إلخ).
tags:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
color:
type: string
description: العلامات المعيّنة لهذا المستخدم
created_at:
type: string
format: date-time
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console.
يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك
إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.