> ## 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 (KYB) أو ضع عليها علامة أو فعّلها. تنتقل الحالة إلى جلسات KYB المستقبلية وفحص المعاملات. إدارة الشركات بالدفع لكل استدعاء. موجّه تحديث حالة الشركة نسخ الموجّه إلى الحافظة \

\`Goal: Flip ONLY the lifecycle status of a Didit Business (KYB) entity. Use the full PATCH /v3/businesses/{vendor_data}/ when you also need to touch other fields.

Endpoint: PATCH https://verification.didit.me/v3/businesses/{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" (VendorBusinessStatusChoices, NOT the session enum).
\- reason (string, optional, max 1000): why the status changed. Recorded on the status-change entry in the company's Activity in the Business Console, only when the status actually changes. Webhooks do not carry it.

Status semantics:
\- ACTIVE  → normal. New KYB 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 KYB session creations for the same identifier are rejected. Flipping back to ACTIVE/FLAGGED removes the blocklist entry automatically.

curl:
curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/update-status/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"status": "BLOCKED", "reason": "Registry shows the company dissolved"}'

Response 200: full updated BusinessDetailItem (same shape as GET /v3/businesses/{vendor_data}/). See /reference/data-models.

Side effects:
\- Toggles the system blocklist entry when entering/leaving BLOCKED.
\- Writes one status-change entry to the company's activity (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.
\- 403: a scoped API key without businesses write. { "detail": "This API key has no write access to companies." }
\- 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/businesses/overview.md) بين الحالات `ACTIVE` و`FLAGGED` و`BLOCKED`. راجع [دورة حياة الكيان](https://docs.didit.me/ar/entities/lifecycle.md) للاطلاع على آلة الحالات الكاملة.## متى تستخدمه- **حظر** شركة خاضعة للعقوبات أو ثبت احتيالها. - **وضع علامة** على شركة بانتظار المراجعة اليدوية. - **إلغاء الحظر** بعد المعالجة. - **نقل الإشارات الخارجية** من أنظمة الامتثال لديك.## ملاحظات- القيم الصالحة: `ACTIVE`، `FLAGGED`، `BLOCKED`. - مرّر `reason` اختيارياً (بحد أقصى 1000 حرف) لتسجيل سبب تغيّر الحالة. يحتفظ Didit به في إدخال تغيير الحالة ضمن **النشاط** لدى الشركة في Business Console. لا يُسجَّل إلا عندما تتغير الحالة فعلاً. - تُرفض تلقائياً كل جلسات التحقق من الشركات (KYB) الجديدة وكل المعاملات الجديدة الخاصة بشركات `BLOCKED`، بما في ذلك حين تظهر هذه الشركات بصفتها طرفاً مقابلاً. - يُصدر `business.status.updated` مع `previous_status` و`status`. لا يتضمن webhook الحقل `reason`.## الإنفاذ| الحالة | جلسات التحقق من الشركات (KYB) الجديدة | المعاملات التي تشمل هذه الشركة | | - | - | - | | `ACTIVE` | التدفق العادي | التدفق العادي | | `FLAGGED` | تُوجَّه إلى `IN_REVIEW` | قد تُصعَّد تلقائياً عبر القواعد | | `BLOCKED` | مرفوضة تلقائياً | مرفوضة تلقائياً |## الأذوناتيمكن دائماً للسر الأساسي ومفاتيح [مفاتيح API](https://docs.didit.me/ar/console/api-keys.md) ذات الوصول الكامل استدعاء هذا endpoint. يحتاج المفتاح ذو الوصول المخصص إلى صلاحية الكتابة على **الشركات** (`businesses`). لا يمكن للمفتاح المقيَّد ببعض سير العمل أو بالجلسات المعتمدة الوصول إلى هذا endpoint.تحدد [الأذونات والأدوار](https://docs.didit.me/ar/console/roles-permissions.md) في Console ما يمكن لعضو الفريق فعله فيها. لا تُقيَّم هذه الأدوار والأذونات لطلبات مفاتيح API.## ذات صلة- [دورة حياة الكيان](https://docs.didit.me/ar/entities/lifecycle.md) - [قائمة الحظر](https://docs.didit.me/ar/entities/businesses/blocklist.md) - [webhook الكيانات](https://docs.didit.me/ar/entities/webhooks.md) ## OpenAPI ````yaml ar/openapi-25.json PATCH /v3/businesses/{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/businesses/{vendor_data}/update-status/: patch: tags: - Businesses summary: تحديث حالة الشركة description: >- تبديل `status` دورة الحياة فقط للشركة: `ACTIVE` أو `FLAGGED` أو `BLOCKED` (وليس حالات الجلسة). يضيف `BLOCKED` قيمة `vendor_data` إلى قائمة الحظر في النظام؛ ويؤدي التغيير من `BLOCKED` إلى إزالة هذا الإدخال. يتم تسجيل كل تغيير في نشاط الشركة، مع `reason` الاختياري. لا يؤدي إرسال الحالة الحالية إلى تغيير أي شيء ولا يسجل أي `reason`. لا يحمل webhook الخاص بـ `business.status.updated` الحقل `reason`. operationId: update_business_status parameters: - name: vendor_data in: path required: true schema: type: string description: معرّفك الفريد للشركة (سلسلة نصية حرة، وليس UUID). example: company-123 requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/EntityStatusUpdateRequest' - type: object properties: reason: type: string nullable: true maxLength: 1000 description: >- سبب تغيير الحالة. يُسجّل في قيد تغيير الحالة ضمن **Activity** الخاصة بالشركة في Business Console، فقط عندما تتغير الحالة فعلياً. لا تتضمنه أحداث webhook. examples: Flag: summary: وضع علامة على الشركة للمراجعة value: status: FLAGGED Block: summary: حظر الشركة (إضافتها إلى قائمة الحظر الخاصة بالنظام) value: status: BLOCKED Reactivate: summary: إعادة تفعيل الشركة value: status: ACTIVE Block with reason: summary: حظر الشركة وتسجيل السبب value: status: BLOCKED reason: Registry shows the company dissolved responses: '200': description: تم تحديث حالة الشركة. يتم إرجاع سجل الشركة بالكامل. content: application/json: schema: $ref: '#/components/schemas/BusinessDetailItem' examples: Blocked: value: didit_internal_id: a1b2c3d4-e5f6-4890-abcd-ef1234567890 vendor_data: company-123 display_name: null legal_name: Acme Trading Ltd registration_number: '12345678' country_code: GB effective_name: Acme Trading Ltd status: BLOCKED session_count: 2 approved_count: 1 declined_count: 0 in_review_count: 1 features: KYB: Approved features_list: - feature: KYB status: Approved last_session_at: '2026-03-15T10:30:00Z' last_activity_at: '2026-03-15T10:30:00Z' first_session_at: '2026-01-10T08:00:00Z' tags: - uuid: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d name: VIP color: '#2567FF' created_at: '2026-01-10T08:00:00Z' metadata: industry: fintech updated_at: '2026-03-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. '403': description: >- مفتاح API مفقود أو غير صالح أو ملغى، أو لا يمكن للمفتاح تحديث الشركات لهذا التطبيق. يعيد المفتاح المفقود `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/businesses/company-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.businesses.update_status( "company-123", status="FLAGGED", ) 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.businesses.updateStatus("company-123", { status: "FLAGGED", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.UpdateStatus(ctx, \"company-123\", didit.BusinessesUpdateStatusParams{\n\tStatus: \"FLAGGED\",\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.BusinessesUpdateStatusParams; import me.didit.types.EntityStatusUpdateRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.businesses().updateStatus("company-123", BusinessesUpdateStatusParams.builder() .status(EntityStatusUpdateRequest.Status.of("FLAGGED")) .build()); System.out.println(result); - lang: php label: PHP source: |- businesses->updateStatus('company-123', [ 'status' => 'FLAGGED', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.businesses.update_status( "company-123", status: "FLAGGED" ) 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.Businesses.UpdateStatusAsync("company-123", new BusinessesUpdateStatusParams { Status = "FLAGGED", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: EntityStatusUpdateRequest: type: object required: - status properties: status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- حالة دورة الحياة الجديدة. يؤدي استخدام `BLOCKED` أيضاً إلى إضافة `vendor_data` إلى قائمة الحظر الخاصة بالنظام. BusinessDetailItem: type: object description: >- تفاصيل الشركة الكاملة. يمتد من BusinessListItem بإضافة البيانات الوصفية وupdated_at. allOf: - $ref: '#/components/schemas/BusinessListItem' - type: object properties: metadata: type: object description: >- بيانات وصفية مخصصة بتنسيق JSON أرفقتها بهذه الشركة. القيمة الافتراضية هي `{}`. updated_at: type: string format: date-time BusinessListItem: 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: اسم عرض مخصص تم تعيينه بواسطتك legal_name: type: string nullable: true description: الاسم القانوني الرسمي من السجل أو الإدخال اليدوي registration_number: type: string nullable: true description: رقم تسجيل أو تأسيس الشركة country_code: type: string nullable: true description: دولة التأسيس (ISO 3166-1 alpha-2، مثل `GB` أو `US`). effective_name: type: string nullable: true description: 'أفضل اسم متاح: display_name إذا كان محدداً، وإلا فـ legal_name' status: type: string enum: - ACTIVE - FLAGGED - BLOCKED description: >- حالة دورة حياة سجل الشركة (ليست حالة جلسة). القيمة الافتراضية هي `ACTIVE`، و`FLAGGED` تميز السجل للمراجعة اليدوية، و`BLOCKED` تمنع إنشاء جلسات جديدة لقيمة `vendor_data` هذه. session_count: type: integer description: العدد الإجمالي لجلسات التحقق لهذه الشركة approved_count: type: integer description: عدد الجلسات المقبولة declined_count: type: integer description: عدد الجلسات المرفوضة in_review_count: type: integer description: عدد الجلسات قيد المراجعة features: type: object description: >- الحالة المجمعة لكل ميزة عبر جميع جلسات KYB الخاصة بهذه الشركة. المفتاح الوحيد حالياً هو `KYB` (حالة فحص الشركة في السجل). القيم المحتملة: `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.