customer-requests

Institute Requests

An Institflow account requesting a new institute through the customer portal, and the platform owner's console review queue (approve/refuse). Cloud/control-plane only: answers 404 on a self-hosted install.

2 نقاط النهاية

POST `/api/v1/portal/requests`

Request a new institute. One pending request per account at a time (409 otherwise). Mails every platform owner.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

محتوى الطلب

الاسم	النوع	القيود
instituteNameمطلوب	string	1–200 chars
slugمطلوب	string	3–42 chars
countryمطلوب	string	—
sizeBandمطلوب	enum: "small" \| "medium" \| "large" \| "xlarge"	—
phone	string	—
termsVersionمطلوب	enum: "2026-09-23"	—

مثال

json

{
  "instituteName": "string",
  "slug": "string",
  "country": "string",
  "sizeBand": "small",
  "phone": "+15551234567",
  "termsVersion": "2026-09-23"
}

مثال بأمر curl

curl

curl -X POST "https://your-institute.example/api/v1/portal/requests" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "instituteName": "string",
    "slug": "string",
    "country": "string",
    "sizeBand": "small",
    "phone": "+15551234567",
    "termsVersion": "2026-09-23"
  }'

الاستجابات

201The newly submitted request, pending review.

الاسم	النوع	القيود
idمطلوب	string (uuid)	—
instituteNameمطلوب	string	—
slugمطلوب	string	—
countryمطلوب	string	—
sizeBandمطلوب	enum: "small" \| "medium" \| "large" \| "xlarge"	—
phoneمطلوب	string \| null	—
statusمطلوب	enum: "pending" \| "approved" \| "refused"	—
refusalReasonمطلوب	string \| null	—
tenantIdمطلوب	string (uuid) \| null	—
createdAtمطلوب	string (date-time)	—
updatedAtمطلوب	string (date-time)	—

json

{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "instituteName": "string",
  "slug": "string",
  "country": "string",
  "sizeBand": "small",
  "phone": "+15551234567",
  "status": "pending",
  "refusalReason": "string",
  "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}

400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

تُعيد مغلّف الخطأ المشترك `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

GET `/api/v1/portal/requests/mine`

This account’s own institute requests, newest first.

يتطلّب المصادقةالصلاحيةلا صلاحية إضافية

مثال بأمر curl

curl

curl -X GET "https://your-institute.example/api/v1/portal/requests/mine" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

الاستجابات

200The account’s requests.

json

[
  {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "instituteName": "string",
    "slug": "string",
    "country": "string",
    "sizeBand": "small",
    "phone": "+15551234567",
    "status": "pending",
    "refusalReason": "string",
    "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
    "createdAt": "2026-03-02T09:00:00.000Z",
    "updatedAt": "2026-03-02T09:00:00.000Z"
  }
]