> ## Documentation Index > Fetch the complete documentation index at: https://docs.classquill.com/llms.txt > Use this file to discover all available pages before exploring further. # Bulk Invite Users > Bulk create/invite 1–100 users — students (optionally each with a parent), tutors, and parents — in one call. Each row carries a `type` discriminator. Auth is all-or-nothing: the key must hold every scope the batch's row types require (`students:write` for student/parent rows, `tutors:write` for tutor rows) or the whole request is 403. Provisioning is then per-row and independent — one row's failure never rolls back the others. Each input row maps to one `results[]` entry (same order, by `index`) with a `status`: - `ok` — newly provisioned (`created` = whether a new login was made) - `exists` — already an accepted member of this org (idempotent no-op) - `error` — could not provision (`error` carries a human-readable reason) Honours `Idempotency-Key` (the whole batch result is replayed on retry). ## OpenAPI ````yaml /openapi.json post /v1/users/bulk-invite openapi: 3.1.0 info: title: ClassQuill Public API description: >- REST API for ClassQuill tutoring organisations. Pipe your sessions, invoices, payments, tutor earnings, students, and more into your own tools. Most endpoints are reads; a focused set of writes (each gated by a *:write scope) create or update data, including creating student/tutor/parent accounts. Authenticate every request with an org API key: Authorization: Token token=ei_live_... Mint keys in the ClassQuill app under Settings → Developers. version: 1.0.0 servers: [] security: - ApiKeyAuth: [] tags: - name: General - name: Sessions - name: Tutors - name: Students & Parents - name: Billing - name: Curriculum - name: Coursework - name: Operations - name: Pricing - name: Bookings - name: Blog - name: Reports paths: /v1/users/bulk-invite: post: tags: - Students & Parents summary: Bulk Invite Users description: >- Bulk create/invite 1–100 users — students (optionally each with a parent), tutors, and parents — in one call. Each row carries a `type` discriminator. Auth is all-or-nothing: the key must hold every scope the batch's row types require (`students:write` for student/parent rows, `tutors:write` for tutor rows) or the whole request is 403. Provisioning is then per-row and independent — one row's failure never rolls back the others. Each input row maps to one `results[]` entry (same order, by `index`) with a `status`: - `ok` — newly provisioned (`created` = whether a new login was made) - `exists` — already an accepted member of this org (idempotent no-op) - `error` — could not provision (`error` carries a human-readable reason) Honours `Idempotency-Key` (the whole batch result is replayed on retry). operationId: bulk_invite_users_v1_users_bulk_invite_post parameters: - name: Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkInviteRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BulkInviteResponse' '401': description: Missing, malformed, revoked, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: The credential lacks the scope this endpoint requires. content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: Validation error — `error.details.errors` lists the fields. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: >- Rate limit exceeded — honour Retry-After and the RateLimit-* headers. content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: BulkInviteRequest: properties: users: items: oneOf: - $ref: '#/components/schemas/BulkInviteStudent' - $ref: '#/components/schemas/BulkInviteTutor' - $ref: '#/components/schemas/BulkInviteParent' discriminator: propertyName: type mapping: parent: '#/components/schemas/BulkInviteParent' student: '#/components/schemas/BulkInviteStudent' tutor: '#/components/schemas/BulkInviteTutor' type: array maxItems: 100 minItems: 1 title: Users additionalProperties: false type: object required: - users title: BulkInviteRequest description: >- POST /v1/users/bulk-invite — create/invite 1–100 users (students, tutors, and/or parents) in one call. Each row is provisioned independently: one row's failure never rolls back the others (see the per-row `results`). BulkInviteResponse: properties: results: items: $ref: '#/components/schemas/BulkInviteResultItem' type: array title: Results default: [] summary: $ref: '#/components/schemas/BulkInviteSummary' type: object title: BulkInviteResponse description: >- POST /v1/users/bulk-invite response — `results` is per-row (same order as the request) and `summary` rolls up the counts. ApiError: description: Canonical error envelope for every /v1 error response (4xx/5xx). properties: error: $ref: '#/components/schemas/ApiErrorBody' required: - error title: ApiError type: object BulkInviteStudent: properties: type: type: string const: student title: Type first_name: type: string title: First Name last_name: type: string title: Last Name email: anyOf: - type: string - type: 'null' title: Email send_invite: type: boolean title: Send Invite default: true phone: anyOf: - type: string - type: 'null' title: Phone parent: anyOf: - $ref: '#/components/schemas/ParentInline' - type: 'null' additionalProperties: false type: object required: - type - first_name - last_name title: BulkInviteStudent description: >- A student row in POST /v1/users/bulk-invite (optionally with a parent created + linked atomically). Mirrors POST /v1/students. BulkInviteTutor: properties: type: type: string const: tutor title: Type first_name: type: string title: First Name last_name: type: string title: Last Name email: anyOf: - type: string - type: 'null' title: Email send_invite: type: boolean title: Send Invite default: true phone: anyOf: - type: string - type: 'null' title: Phone bio: anyOf: - type: string - type: 'null' title: Bio teaching_mode: anyOf: - type: string - type: 'null' title: Teaching Mode description: online | in_person | both is_published: anyOf: - type: boolean - type: 'null' title: Is Published additionalProperties: false type: object required: - type - first_name - last_name title: BulkInviteTutor description: >- A tutor (staff) row in POST /v1/users/bulk-invite. Mirrors POST /v1/tutors. BulkInviteParent: properties: type: type: string const: parent title: Type first_name: type: string title: First Name last_name: type: string title: Last Name email: anyOf: - type: string - type: 'null' title: Email send_invite: type: boolean title: Send Invite default: true phone: anyOf: - type: string - type: 'null' title: Phone additionalProperties: false type: object required: - type - first_name - last_name title: BulkInviteParent description: >- A standalone parent row in POST /v1/users/bulk-invite. Mirrors POST /v1/parents. `send_invite` is accepted for shape-parity but a STANDALONE parent is created without an org link, so it is never auto-invited here (the org-scoped invite requires a student link); link them to a student, then call POST /v1/parents/{id}/send-invite. BulkInviteResultItem: properties: index: type: integer title: Index type: type: string title: Type email: anyOf: - type: string - type: 'null' title: Email status: type: string enum: - ok - exists - error title: Status id: anyOf: - type: string - type: 'null' title: Id created: anyOf: - type: boolean - type: 'null' title: Created invited: anyOf: - type: boolean - type: 'null' title: Invited error: anyOf: - type: string - type: 'null' title: Error type: object required: - index - type - status title: BulkInviteResultItem description: >- The outcome of one bulk-invite row, positionally aligned to the request `users` array by `index`. `status`: `ok` = newly provisioned (`created` says whether a new login was made), `exists` = already an accepted member of this org (idempotent no-op), `error` = could not provision (`error` carries the reason). BulkInviteSummary: properties: total: type: integer title: Total default: 0 ok: type: integer title: Ok default: 0 exists: type: integer title: Exists default: 0 errors: type: integer title: Errors default: 0 created: type: integer title: Created default: 0 type: object title: BulkInviteSummary description: >- Roll-up counts for a bulk invite (`ok` + `exists` + `errors` == `total`). ApiErrorBody: description: The `error` object every /v1 error response carries. properties: code: description: >- Stable machine-readable error code: bad_request, unauthorized, forbidden, not_found, conflict, validation_error, rate_limited, or internal_error. examples: - not_found title: Code type: string message: description: Human-readable explanation, safe to surface to end users. examples: - Session not found title: Message type: string status: description: The HTTP status code, repeated in the body. examples: - 404 title: Status type: integer details: additionalProperties: true description: >- Error-specific context. 422 carries the field errors under `errors`; 429 carries `retry_after_seconds`. title: Details type: object required: - code - message - status title: ApiErrorBody type: object ParentInline: properties: first_name: type: string title: First Name last_name: type: string title: Last Name email: anyOf: - type: string - type: 'null' title: Email phone: anyOf: - type: string - type: 'null' title: Phone additionalProperties: false type: object required: - first_name - last_name title: ParentInline description: >- A parent created alongside a student in POST /v1/students. `email` is optional (omit → no-email placeholder parent account). securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: Org API key as `Token token=ei_live_...` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.