> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Add existing users to a team
>
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `teams:write` scope (or a broader one that includes it)._
Give up to 50 users of your organization access to another of its teams (workspaces), each with a role of that team (`roleName`). Users are identified by email and get a separate user ID in the team. The acting user needs the permissions to add existing organization members to a team and to assign roles; the organization owner has both.
The response has one entry per user, in request order, each with the `email` it was sent with: the user's `id` in the team, or `error` and `errorDetails` with `id` `0`. A failed entry does not stop the others. A user already in the team comes back as `alreadyInTeam` with their `id` and role unchanged, so retries are safe.
Keys with `*:*` do not include `teams:write`. A user in several teams must name the team in the `X-TEAM-ID` header of access-token calls.
## OpenAPI
````yaml /api-reference/bundled.yaml post /v3/teams/{team_id}/users/bulk
openapi: 3.1.0
info:
version: 3.0.0
title: Reply API
description: API for managing email sequences, contacts, and automation workflows
servers:
- url: https://api.reply.io
security:
- bearerAuth: []
tags:
- name: Contacts
description: Manage individual contacts
- name: Contact Lists
description: Manage contact lists and contact membership
- name: Accounts
description: Manage accounts (companies/organizations)
- name: Account Lists
description: Manage account lists and account membership
- name: Custom Fields
description: Manage custom contact fields
- name: Prompt Actions
description: Save reusable AI prompts and run them on contacts to fill custom fields
- name: Contact Blacklist Rules
description: Manage blacklist rules for domains, emails, and email exceptions
- name: Live Data
description: >-
Find new contacts via Live Data searches and read typeahead values for the
Live Data / Autopilot filter sidebar
- name: Contact Enrichment
description: >-
Enrich contacts with emails, phone numbers, LinkedIn data, and AI-filled
custom fields
- name: Email Validations
description: Estimate and schedule asynchronous email validation jobs
- name: AI SDR Web Search
description: Find contacts via AI-driven web search and review past searches
- name: Sequences
description: Manage email automation sequences
- name: Sequence Steps
description: Manage individual steps in sequences
- name: Sequence Contacts
description: Manage contacts within sequences
- name: Sequence Folders
description: Organize sequences into folders
- name: Email Accounts
description: Manage email accounts used for sending and receiving
- name: Sequence Email Accounts
description: Manage email accounts linked to sequences
- name: LinkedIn Accounts
description: Manage LinkedIn accounts for outreach
- name: Sequence LinkedIn Accounts
description: Manage LinkedIn accounts linked to sequences
- name: Sequence Templates
description: Manage sequence templates
- name: Email Templates
description: Manage email templates and template folders
- name: Voices
description: Manage cloned voices used for AI voice message steps
- name: Schedules
description: Manage email send schedules and timing
- name: Holiday Calendars
description: Manage holiday calendars for scheduling
- name: Inbox
description: >-
Manage inbox threads — list/filter, read state, replies, category
assignment, and meeting-intent flagging
- name: Inbox Categories
description: Manage per-team inbox thread categories and assign threads to them
- name: Direct Outreach
description: >-
Send one-off outreach directly to a contact outside of any sequence —
direct emails and LinkedIn connection requests, messages, InMails, and
voice messages
- name: Tasks
description: Manage tasks and to-do items
- name: Reports
description: >-
Generate and access performance reports across email, calls, tasks,
LinkedIn, and team performance
- name: AI SDR Sequences
description: >-
Manage AI SDR sequences and their AI SDR-specific settings — create, read
settings, partial update, autopilot enable/disable/force-start, approval
mode, sequence structure, and playbook/knowledge-base connections
- name: AI SDR Sequence Structures
description: >-
Browse the sequence structures — reusable outlines of AI SDR sequence
steps — that can be applied to AI SDR sequences
- name: AI SDR Strategist
description: Trigger AI Strategist runs
- name: AI SDR Playbooks
description: >-
Manage AI SDR playbooks — tone, voice, and style guides applied during
personalized message generation
- name: AI SDR Knowledge Bases
description: >-
Manage AI SDR knowledge bases — collections of documents, links, reply
handlers, and reengagement cards that inform the agent's responses
- name: AI SDR Offers
description: >-
Manage AI SDR offers — bundles of company-context inputs (ICP, pain
points, value propositions, etc.) used to personalize outreach
- name: AI SDR Pending Approvals
description: >-
Review, send, regenerate, and provide feedback on AI-generated messages
awaiting human approval
- name: AI SDR Sequence Preview
description: >-
Read and regenerate per-contact previews of the messages a sequence will
send, and provide feedback on preview messages
- name: AI SDR Insights
description: Read AI SDR insights for sequence contacts
- name: AI SDR Intent Signals
description: >-
Read Reply industry IDs and technology slugs used in AI SDR intent-signal
configuration (typeahead)
- name: AI Prompts
description: >-
Manage the AI prompts used to configure sequence steps, and preview the
output a prompt produces
- name: AI SDR Learnings
description: >-
Manage the standing rules that shape how the AI writes — list, read,
create, partially update and delete AI learnings
- name: Registration
description: Register the contact that domain purchases are filed under
- name: Domains
description: Find domains available to buy for outreach
- name: Purchased Domains
description: >-
List the domains your team bought, with their subscription, setup and
renewal state
- name: Mailboxes
description: Add mailboxes to domains your team already bought, priced before you order
- name: User Account
description: Account information and authentication verification
- name: Teams
description: Add existing users of your organization to its teams
- name: Settings
description: Manage team and user settings
- name: Billing
description: Subscription details and monthly active contacts usage
- name: Rate Limits
description: Your API rate limits and current usage
- name: Webhooks
description: Manage webhook subscriptions and inspect delivery history
- name: Background Jobs
description: >-
Track and cancel asynchronous background operations (e.g., email
validation)
- name: Attachments
description: >-
Upload file attachments used across email templates, sequence steps, and
direct emails
paths:
/v3/teams/{team_id}/users/bulk:
post:
tags:
- Teams
summary: Add existing users to a team
description: >-
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `teams:write` scope (or a broader one that includes
it)._
Give up to 50 users of your organization access to another of its teams
(workspaces), each with a role of that team (`roleName`). Users are
identified by email and get a separate user ID in the team. The acting
user needs the permissions to add existing organization members to a
team and to assign roles; the organization owner has both.
The response has one entry per user, in request order, each with the
`email` it was sent with: the user's `id` in the team, or `error` and
`errorDetails` with `id` `0`. A failed entry does not stop the others. A
user already in the team comes back as `alreadyInTeam` with their `id`
and role unchanged, so retries are safe.
Keys with `*:*` do not include `teams:write`. A user in several teams
must name the team in the `X-TEAM-ID` header of access-token calls.
operationId: BulkAddUsersToTeam
parameters:
- name: team_id
in: path
required: true
description: ID of the team (workspace) to add the users to
schema:
type: integer
minimum: 1
requestBody:
required: true
content:
application/json:
schema:
type: object
title: Bulk Add Users To Team Request
description: >-
Users of your organization to add to the team, each with a role
from that team.
additionalProperties: false
required:
- items
properties:
items:
type: array
minItems: 1
maxItems: 50
description: The users to add, 1 to 50 per call.
items:
type: object
additionalProperties: false
required:
- email
- roleName
properties:
email:
type: string
format: email
description: >-
Email of a user who already belongs to any team of
your organization. Case-insensitive; surrounding
spaces are ignored.
roleName:
type: string
description: >-
Name of a role of the target team, matched
case-insensitively.
example:
items:
- email: daniel@example.com
roleName: Team Member
- email: olivia@example.com
roleName: Team Lead
responses:
'200':
description: >-
Array of results, one per submitted user, in request order.
Per-item error codes:
| error | Meaning |
|-------|---------|
| `userNotFound` | No user with this email belongs to your
organization, or the user has no active membership left to add from
|
| `alreadyInTeam` | The user is already a member of the team;
nothing changed. `id` holds their ID in the team |
| `removedFromTeam` | The user was removed from this team earlier
and can't be added back through the API |
| `roleNotFound` | The role is not one of the team's roles |
| `requestInProgress` | Another request for the same user and team
is still running; retry shortly |
| `unknown` | The user could not be added; retry the request |
content:
application/json:
schema:
type: array
items:
type: object
properties:
email:
type: string
description: The email as it was sent in the request item.
id:
type: integer
description: >-
The user's ID in the team, also with `alreadyInTeam`.
`0` when the user was not added for any other reason.
error:
type: string
nullable: true
description: >-
Why the user was not added: `userNotFound`,
`alreadyInTeam`, `removedFromTeam`, `roleNotFound`,
`requestInProgress` or `unknown`. `null` on success.
errorDetails:
type: string
nullable: true
description: Human-readable explanation of `error`; `null` on success
example:
- email: daniel@example.com
id: 10493
error: null
errorDetails: null
- email: olivia@example.com
id: 10471
error: alreadyInTeam
errorDetails: The user is already a member of this team.
- email: noah@example.com
id: 0
error: userNotFound
errorDetails: No user with this email belongs to your organization.
'400':
description: Route parameter or body validation failure
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
errors:
type: array
description: >-
List of field-level validation errors. Always
non-empty when this
envelope is returned. Each entry pins a single
offending field
via JSON Pointer plus a sanitized detail string.
items:
type: object
title: Validation Error
description: A single field-level validation error.
properties:
pointer:
type: string
description: >-
JSON Pointer (RFC 6901) to the offending
field — e.g.
`/steps/0/subject`.
* An empty string (`""`) means the error
applies to the whole
request body (e.g. body is missing or unparseable).
* For route or query parameter failures the
pointer is the parameter
name (e.g. `id`, `top`).
example: /steps/0/subject
detail:
type: string
description: >-
Sanitized, human-readable explanation of
this field's error. One of a
small set of templates — `"Field is
required."`, `"Value has an
invalid type."`, `"Value has an invalid
format."`, `"Request body is
not valid JSON."`, `"The request body is
required and cannot be
empty."` — or a FluentValidator message on
body endpoints.
example: Field is required.
title: Validation Problem
description: >-
Input-validation error response at 400. Returned when the
request body
fails binding, FluentValidator rules, or when route/query
parameter
attribute validation (`[Range]`, `[Required]`) fails.
Route, query, and
body errors are combined into a single `errors[]` array —
clients should
not assume one error per request.
- example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /name
detail: Field is required.
example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /items/0/roleName
detail: '''Role Name'' must not be empty.'
'401':
description: >-
Unauthorized. The response body is empty; check the
`WWW-Authenticate` header for the expected scheme.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- example:
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
'403':
description: >-
Adding users to a team is not enabled for the acting user's team,
the acting user is not part of an organization, or the acting user
lacks the permission to add existing organization members to a team
or to assign roles
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Forbidden
status: 403
detail: You do not have permission to access this resource.
code: sequence.forbidden
examples:
featureDisabled:
summary: Not enabled for the team
value:
title: Forbidden
status: 403
detail: Adding users to a team is not available for your team.
code: teamUser.featureDisabled
organizationRequired:
summary: Organization membership required
value:
title: Forbidden
status: 403
detail: Team users are only available for organization accounts.
code: teamUser.organizationRequired
'404':
description: The team does not exist or belongs to another organization
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Not Found
status: 404
detail: The requested resource was not found.
code: sequence.notFound
example:
title: Not Found
status: 404
detail: Team not found.
code: teamUser.teamNotFound
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 1
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
example:
title: Too Many Requests
status: 429
detail: API calls quota exceeded! maximum admitted 100 per 1m.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate every request with a Bearer token. Pass your Reply API key
in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from the Reply dashboard: **Settings → API Key**.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.