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

# Add users to workspace

> Add tax firm users to a workspace by email addresses

Add tax firm users (preparers, staff, etc.) to their workspace by email addresses. Users are immediately added to the workspace and can sign in right away.

```graphql theme={null}
mutation AddUsersToWorkspace($workspaceId: ID!, $userEmails: [String!]!) {
  addUsersToTheWorkspace(workspaceId: $workspaceId, userEmails: $userEmails) {
    id
    email
    name
    role
  }
}
```

## Arguments

<ParamField path="workspaceId" type="ID!" required>
  Workspace identifier (corresponds to a tax firm). Add users to the workspace that corresponds to their tax firm.
</ParamField>

<ParamField path="userEmails" type="[String!]!" required>
  Array of email addresses for the tax firm's users. You can add multiple users in a single request.
</ParamField>

## Returns

<ResponseField name="addUsersToTheWorkspace" type="[User!]!">
  Array of user objects that were added to the workspace.

  <Expandable title="User">
    <ResponseField name="id" type="ID!">
      User identifier.
    </ResponseField>

    <ResponseField name="email" type="String!">
      User email address.
    </ResponseField>

    <ResponseField name="name" type="String">
      User display name. May be null if not set.
    </ResponseField>

    <ResponseField name="role" type="Role!">
      User role in workspace (e.g., "user").
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://gateway.filed.com/graphql \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <accessToken>" \
    -H "source-platform: my-sample-platform" \
    -d '{
      "query": "mutation AddUsersToWorkspace($workspaceId: ID!, $userEmails: [String!]!) { addUsersToTheWorkspace(workspaceId: $workspaceId, userEmails: $userEmails) { id email name role } }",
      "variables": {
        "workspaceId": "workspace_123456",
        "userEmails": [
          "test-1@firm.filed.com",
          "test-2@firm.filed.com"
        ]
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "addUsersToTheWorkspace": [
        {
          "id": "user_789",
          "email": "test-1@firm.filed.com",
          "name": null,
          "role": "user"
        },
        {
          "id": "user_790",
          "email": "test-2@firm.filed.com",
          "name": null,
          "role": "user"
        }
      ]
    }
  }
  ```
</ResponseExample>

<Note>
  Users are immediately added to the workspace - no email invitations are sent. Users can sign in using their email address right away to access the workspace. If a user already exists, they will be added to the workspace without creating a duplicate account.
</Note>

## Troubleshooting

**Problem**: Tax firm users unable to access workspace after being added

**Solutions**:

* Verify email addresses are valid and correctly formatted
* Check that users haven't already been added to the workspace
* Ensure workspace ID corresponds to the correct tax firm
* Verify you're adding users to the correct workspace for their tax firm
* Confirm users can sign in using their email address - no invitation email is required
* Ensure users are using a valid deep link with the workspace slug format `/w/{workspaceSlug}/` (recommended) or `/w/redirect/` (convenience option)