Create Institution

POST/web/v1/workspaces/{workspaceId}/institutionsWEB

Creates a new institution under the specified workspace.

Authentication

Requires a valid JWT token. Gateway validation: enableJwtToken=true, enableTurnstile=false.

Request Parameters

Path Parameters

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

Request Body

UserInstitutionCreateRequest:

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

Success Response

Success200

{
  "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.