> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/institution-api/user.md).
# User
Sub-account (user) creation and listing.
## Create a sub-account (user)
> Create a sub-account (user) bound to your institution. Idempotent by\
> \`clientId\`.\
> \
> This is a public/self endpoint (no \`userId\` in the payload) but still\
> requires a valid signature and the \`write\` scope.\
> \
> \*\*Errors:\*\*\
> \
> \| Error Code | Description |\
> \|------------|-------------|\
> \| \`P\_PAY\_OPEN\_API\_SUB\_USER\_CREATE\_FORBIDDEN\` | Master account unavailable, caller is itself a sub-account (nesting unsupported), or sub-account limit reached. |\
> \| \`P\_PAY\_OPEN\_API\_SUB\_USER\_ACCOUNT\_CREATE\_FAILED\` | The sub-account was created but not fully set up. \`data.userId\` returns the created id; resend the identical request to complete setup. |
```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"User","description":"Sub-account (user) creation and listing."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/user/create":{"post":{"tags":["User"],"summary":"Create a sub-account (user)","description":"Create a sub-account (user) bound to your institution. Idempotent by\n`clientId`.\n\nThis is a public/self endpoint (no `userId` in the payload) but still\nrequires a valid signature and the `write` scope.\n\n**Errors:**\n\n| Error Code | Description |\n|------------|-------------|\n| `P_PAY_OPEN_API_SUB_USER_CREATE_FORBIDDEN` | Master account unavailable, caller is itself a sub-account (nesting unsupported), or sub-account limit reached. |\n| `P_PAY_OPEN_API_SUB_USER_ACCOUNT_CREATE_FAILED` | The sub-account was created but not fully set up. `data.userId` returns the created id; resend the identical request to complete setup. |\n","operationId":"institutionUserCreate","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientId","email","entityType"],"properties":{"clientId":{"type":"string","description":"Client-defined idempotency key, max 64 chars. Retries must reuse the same value.","maxLength":64},"email":{"type":"string","description":"Email, max 64 chars.","maxLength":64},"entityType":{"type":"string","description":"`CORPORATE` (business) / `INDIVIDUAL` (natural person).","enum":["CORPORATE","INDIVIDUAL"]},"remark":{"type":"string","description":"Note, max 100 chars.","maxLength":100}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"userId":{"type":"string","description":"The created sub-account UUID."}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## List sub-accounts
> List the sub-accounts bound to your institution.\
> \
> This is a public/self endpoint (no \`userId\` parameter) but still requires\
> a valid signature and the \`read\` scope.\
> \
> \`total\` is the total count for pagination. An out-of-range page returns an\
> empty \`list\` with the real \`total\`.
```json
{"openapi":"3.0.3","info":{"title":"Pionex Institution Open API (v2)","version":"2.0.0"},"tags":[{"name":"User","description":"Sub-account (user) creation and listing."}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"ApiKey":[],"Signature":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-APIKEY","description":"Your institution API Key, in the form `webot_xxxxxxxx`. Used to look up\nyour registered public key. Must be accompanied by the `X-Signature`\nheader. See the Authentication section for the full signing algorithm\n(RSA-PSS over SHA-256, or Ed25519) and the canonical-string construction.\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current time in **seconds** (Unix). Required on every signed request and\nparticipates in the signature. Must be within +/-5 seconds of server time.\n","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Success indicator."},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds."},"code":{"type":"string","description":"Error code (present only on failure)."},"message":{"type":"string","description":"Error message (present only on failure)."}}},"SubAccount":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"entityType":{"type":"string","enum":["CORPORATE","INDIVIDUAL"]},"status":{"type":"string"},"remark":{"type":"string"},"createTime":{"type":"integer","format":"int64","description":"Millisecond Unix timestamp."}}}},"responses":{"BadRequest":{"description":"Bad Request - the request body could not be read.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"Unauthorized":{"description":"Unauthorized - authentication failed (missing key, bad signature, etc.).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}},"InternalError":{"description":"Internal or business error. Note that most business failures are returned\nas HTTP `200` with `result: false` and a `code`; this `500` covers\nserver-side internal errors.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"}]}}}}}},"paths":{"/api/v2/institution/users":{"get":{"tags":["User"],"summary":"List sub-accounts","description":"List the sub-accounts bound to your institution.\n\nThis is a public/self endpoint (no `userId` parameter) but still requires\na valid signature and the `read` scope.\n\n`total` is the total count for pagination. An out-of-range page returns an\nempty `list` with the real `total`.\n","operationId":"institutionUsersList","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"page","in":"query","required":false,"description":"Page number, starting from 1.","schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"description":"Page size, default 100, max 500.","schema":{"type":"integer","default":100,"maximum":500}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/SubAccount"}},"total":{"type":"integer","description":"Total count for pagination."}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```