> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vacademy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-organisations

> Partner organisations / centres: their courses, seats, admins and learners.

Each tool below is one switch in **Settings → MCP Server**. Your AI app sees a tool only when it is switched on for your role; every call is checked again on the server.

## `sub_orgs`

**Sub-organisations: view** · Read only

See the institute's sub-organisations (partner organisations / centres): each one's admin, courses, seats used against the cap, plan status, invite link and learners, plus the payment options and roles a new one can be set up with.

| Action | What it does |
| :- | :- |
| `list` | every sub-org with its admin, plan status, seats used / total and invite code. When several match a name, list them and ask which one. |
| `get` | its courses (batches), seats used per course against the cap, admins, the settings it was created with (admin roles, team roles, admin permissions, validity, payment option) and the admin's invite link. |
| `members` | its learners with their courses and status. |
| `create_options` | what sub\_org\_edit(change='create') needs — the institute's payment options (with prices), payment gateways, the roles a sub-org admin can be given and the admin permissions. The courses come from courses(action='list'). |
| `enroll_template` | the CSV columns sub\_org\_enroll takes (with the institute's custom fields) as a header + sample row — hand it to the admin as a .csv file to fill in. |

> **Parameters**
>
> **action** `string` *required*
>
> The action to run: `list`, `get`, `members`, `create_options`, `enroll_template`.
>
> **sub\_org\_id** `string`
>
> get / members: the sub\_org\_id from list.
>
> **query** `string`
>
> list: part of the name. members: name or email.
>
> **include\_inactive** `boolean`
>
> members: also list terminated / expired learners.

> **What your AI app is told about this tool**
>
> ```text theme={null}
> Look up the institute's sub-organisations (partner organisations / centres — call them by the institute's own term from whoami). Read-only. Pick an `action`:
> - list (query?): every sub-org with its admin, plan status, seats used / total and invite code. When several match a name, list them and ask which one.
> - get (sub_org_id): its courses (batches), seats used per course against the cap, admins, the settings it was created with (admin roles, team roles, admin permissions, validity, payment option) and the admin's invite link.
> - members (sub_org_id, query?, include_inactive?): its learners with their courses and status.
> - create_options: what sub_org_edit(change='create') needs — the institute's payment options (with prices), payment gateways, the roles a sub-org admin can be given and the admin permissions. The courses come from courses(action='list').
> - enroll_template: the CSV columns sub_org_enroll takes (with the institute's custom fields) as a header + sample row — hand it to the admin as a .csv file to fill in.
> ```

## `sub_org_edit`

**Sub-organisations: create and change** · Makes changes · Changes live data — the change applies straight away. · Turned on separately (opt-in)

Let the connected AI app create sub-organisations (name, courses, payment option, seats, validity, admin roles), add courses to one or change its seats, validity and roles, and give a new one its admin. It always shows you the change first and makes it only after you confirm. Changes apply right away. It never deletes or deactivates a sub-organisation, never removes a course from one and never changes how its admin pays.

> [!NOTE]
>
> **What keeps it safe:** confirm-gated live write, the admin's explicit choice: creates a sub-org of this institute, adds courses / changes seats, validity and roles of one (add-only for courses), or gives a sub-org without an admin its admin; never deletes or deactivates a sub-org, removes a course or swaps its payment option; every write needs the confirm\_token of a preview of the identical request

| Action | What it does |
| :- | :- |
| `preview` | |
| `apply` | |

> **Parameters**
>
> **action** `string` *required*
>
> The action to run: `preview`, `apply`.
>
> **change** `string` *required*
>
> One of: `create`, `update`, `add_admin`.
>
> **sub\_org\_id** `string`
>
> update / add\_admin: from sub\_orgs(action='list').
>
> **name** `string`
>
> create: the sub-organisation's name.
>
> **courses** `object[]`
>
> create: \[\{course\_id, batch\_id?}]
>
> **add\_courses** `object[]`
>
> update: courses to add, \[\{course\_id, batch\_id?}]
>
> **payment\_option\_id** `string`
>
> create: from create\_options.
>
> **member\_count** `integer`
>
> Learner seats per course.
>
> **validity\_in\_days** `integer`
>
> —
>
> **admin\_roles** `string[]`
>
> —
>
> **team\_roles** `string[]`
>
> —
>
> **admin\_permissions** `string[]`
>
> —
>
> **vendor** `string`
>
> create: payment gateway name (when several).
>
> **admin** `object`
>
> add\_admin: \{full\_name, email, mobile\_number?}
>
> **confirm\_token** `string`
>
> apply: the token preview returned.

> **What your AI app is told about this tool**
>
> ```text theme={null}
> Create a sub-organisation, change its set-up, or give it its admin. Never deletes or deactivates a sub-org and never removes a course from it (dashboard only). Every change is two calls: action='preview' (checks everything, saves nothing, returns what will happen + a confirm_token valid 15 min) → show the admin and get a clear yes → action='apply' with the SAME arguments plus confirm_token. Pick `change`:
> - create: name, courses [{course_id, batch_id? (when the course has several batches)}] (at least one), payment_option_id (from sub_orgs(action='create_options') — ASK which; never pick a price), member_count (learner seats per course — ASK), validity_in_days (ASK), admin_roles [role names the sub-org's admin gets — ASK], team_roles? [roles that admin may give their own team], admin_permissions? (FULL default | CREATE_COURSE), vendor? (payment gateway, when the institute has several and the option is paid). Returns the sub-org and the admin's invite link.
> - update: sub_org_id + any of add_courses [{course_id, batch_id?}], member_count, validity_in_days, admin_roles, team_roles, admin_permissions. The preview shows before → after.
> - add_admin: sub_org_id + admin {full_name, email, mobile_number?}: makes that person the sub-org's admin on all its courses (an account is created when the email has none). Only when the sub-org has no admin yet. Alternative: send the admin the invite link from sub_orgs(action='get').
> ```

## `sub_org_enroll`

**Sub-organisations: add learners** · Makes changes · Changes live data — the change applies straight away. · Turned on separately (opt-in)

Let the connected AI app add learners — one, a list or a CSV — to a sub-organisation's courses. It always shows you a preview (who is added, who is already in and skipped, seats left) and adds them only after you confirm, never past the sub-organisation's seat cap. Adds learners only — never admins — and never removes anyone. It asks whether you want a CSV of the learners' usernames and passwords (a private download link that expires after 30 minutes, never shown in the chat).

> [!NOTE]
>
> **What keeps it safe:** additive + confirm-gated: only ADDS learners (role LEARNER, never admin) to the courses of a sub-org of this institute; skips anyone already active in a course; refuses uploads over the sub-org's seat cap; every write needs the confirm\_token of a preview of the identical request

| Action | What it does |
| :- | :- |
| `preview` | checks everything; nothing is saved. Returns the per-learner plan and a confirm\_token (valid 15 min). |
| `enroll` | does it, learner by learner, and reports each one. |

> **Parameters**
>
> **action** `string` *required*
>
> The action to run: `preview`, `enroll`.
>
> **sub\_org\_id** `string`
>
> From sub\_orgs(action='list').
>
> **csv** `string`
>
> The filled-in enroll\_template as CSV text.
>
> **learners** `object[]`
>
> \[\{learner\_id}] for existing learners and/or new-learner rows.
>
> **batch\_ids** `string[]`
>
> Only these of the sub-org's courses (batch\_ids from sub\_orgs(get)).
>
> **options** `object`
>
> \{credentials\_file: bool}
>
> **confirm\_token** `string`
>
> enroll: the token preview returned.

> **What your AI app is told about this tool**
>
> ```text theme={null}
> Add learners to a sub-organisation — one, a list or a whole CSV — into its courses (all of them unless batch_ids narrows it). Adds LEARNERS only (the sub-org's admin is sub_org_edit(change='add_admin')) and never removes anyone. Steps: sub_orgs(action='list') → sub_orgs(action='get') for its courses and seats → preview → show the admin the outcome (who is added to which course, who is skipped and why, seats left, which emails go out) and get a clear yes → enroll with the SAME arguments plus confirm_token. Pick an `action`:
> - preview (sub_org_id, csv and/or learners, batch_ids?, options): checks everything; nothing is saved. Returns the per-learner plan and a confirm_token (valid 15 min).
> - enroll (same arguments + confirm_token): does it, learner by learner, and reports each one.
> csv: the filled-in sub_orgs(action='enroll_template') as CSV text (header row first). learners: [{learner_id} (an existing learner, from learners(action='find')) | a row with the template columns {email, full_name, mobile_number?, …, custom_fields?: {label: value}}] (max 200 in total). batch_ids: some of the sub-org's course batch_ids (default: all).
> options: {credentials_file: bool — a CSV of every added learner's username + password, delivered as a private download link valid 30 minutes — ASK the admin}. Login-details emails follow Course Settings ('Send credentials') and cannot be switched per upload; the preview says whether they go out and which automations run.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.