---
title: "Bulk invite users"
method: POST
path: "/v2/organizations/{organization_id}/invites/bulk"
tags: ["invites"]
---

# Bulk invite users

`POST /v2/organizations/{organization_id}/invites/bulk`

## Request

- Base URL: `https://api.hubstaff.com`
- URL: `https://api.hubstaff.com/v2/organizations/{organization_id}/invites/bulk`
- Auth: OAuth 2
  - Authorization code: `https://account.hubstaff.com/authorizations/new`
  - Token URL: `https://account.hubstaff.com/access_tokens` scopes: `hubstaff:read`, `hubstaff:write`
- TypeScript: <https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/docs/v2/organizations/:organization_id/invites/bulk/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates multiple invites at once (max 50 per request).

Returns counts of successful and failed invites (rate-limited invites count as failed), a rate_limited flag, and per-invite results.

Invites are processed sequentially. Individual failures don't stop remaining invites. If rate limit is exceeded, processing stops and remaining invites are marked as rate-limited.

Available roles:
- organization_manager - Organization manager with manager access to specified projects
- project_manager - Organization user with manager access to specified projects
- project_user - Organization user with user access to specified projects
- project_viewer - Organization user with viewer access to specified projects

Common failure reasons:
- validation_error - Invalid email, already a member, or other validation issues
- create_action_error - Business rule violations (plan limits, blacklisted user)
- rate_limited - Rate limit exceeded during processing
- system_error - Unexpected system errors

Note: Invalid project IDs are automatically filtered out. Emails are automatically lowercased.

## Path parameters

- `organization_id` integer, required

## Request body

- PostV2OrganizationsOrganizationIdInvitesBulk: Bulk invite users
  - `invites` object[], required
    - `email` string, required: The email to invite
    - `role` 'organization_manager' | 'project_manager' | 'project_user' | 'project_viewer': The role to invite the user as
    - `pay_rate` number, float: A pay rate to set for the user
    - `project_ids` integer[]: List of project IDs to add the user to after they accept the invite
    - `trackable` boolean: Whether the user can track time
    - `view_only` boolean: Whether the user is in view only mode or not

## Response `201`

Bulk invite results

- BulkInviteResult: BulkInviteResult model
  - `summary` object, required: Invite counts
    - `successful` integer, required: Number of invites created
    - `failed` integer, required: Number of failed invites, rate-limited included
    - `rate_limited` boolean, required: Whether processing stopped on the rate limit
  - `results` object, required: Per-invite results
    - `success` object[], required: Created invites
      - `id` integer, required: Invite ID
      - `email` string, required: Invited email
    - `failed` object[], required: Invites that were not created
      - `email` string, required: Invited email
      - `reason` 'validation_error' | 'create_action_error' | 'rate_limited' | 'system_error', required: Failure reason
      - `message` string, required: Error message
  - `rate_limit` object, required: Organization invite rate limit after this request
    - `remaining` integer, required: Invites left in the current window
    - `reset_in` integer, required: Seconds until the window resets

## Other responses

- `400`: Invalid parameters
- `401`: Unauthorized
- `403`: API access is only for organizations on an active plan
- `404`: Could not find record
- `429`: Rate limit exceeded

## Changes

- **2026-11-06** `c6b90e4e4bdc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/changes/v2/organizations/:organization_id/invites/bulk/post.md)

---

[API](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api.md) - [All operations](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/revisions/c6b90e4e4bdc?raw)