Create Institution

POST/web/v1/workspaces/{workspaceId}/institutions WEB

Creates a new institution under the specified workspace.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token

Request Parameters

Path Parameters

Name	Type	Required	In	Description
workspaceId	string	Required	path	Workspace business ID

Request Body

UserInstitutionCreateRequest:

Name	Type	Required	In	Description
institutionName	string	Required	body	Institution name (max 126 characters)
institutionDescription	string	Optional	body	Institution description (max 255 characters)
institutionRemark	string	Optional	body	Institution remark (max 255 characters)
institutionType	string	Required	body	Institution type enum: SYSTEM, TENANT, PARTNER, CONSUMER
extraConfig	object	Optional	body	Extra configuration containing official profile and social media info
extraConfig.official	object	Optional	body	Official business profile (name, website, email, phone, address, description)
extraConfig.social	object	Optional	body	Social media contacts (telegram, whatsApp, discord, twitter)

Success Response

Success 200

{
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "bizId": "inst_abc123",
    "institutionName": "Acme Corp",
    "institutionDescription": "Main institution",
    "institutionRemark": null,
    "institutionType": "TENANT",
    "institutionStatus": "ACTIVE",
    "extraConfig": null,
    "createdAt": "2026-03-21T00:00:00Z",
    "updatedAt": "2026-03-21T00:00:00Z"
  }
}

Error Responses

Code	Description
4000	Validation error (missing required fields, invalid institution type)
4010	Unauthorized (invalid or missing JWT token)

Notes

• The bizId is auto-generated by the system.
• institutionStatus is set to the initial status upon creation.
• createdBy and updatedBy are populated from the security context.