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

# Users

> Create API users and list users in your organization

## Overview

The Users API allows you to create API users (users that won't have UI access) and list users in your organization. API users can be created with or without Auth0 accounts, and must be assigned to at least one team.

## Create Users

Create one or more API users in bulk. Users must be assigned to at least one team. By default, API users are created without Auth0 accounts (isApiUser: true).

**Endpoint:** `POST /qsi/gather/users`

<ParamField name="users" type="array" required>
  Array of user objects to create
</ParamField>

<ParamField name="users[].firstName" type="string" required>
  User's first name
</ParamField>

<ParamField name="users[].lastName" type="string" required>
  User's last name
</ParamField>

<ParamField name="users[].email" type="string" required>
  User's email address
</ParamField>

<ParamField name="users[].phone" type="string">
  User's phone number (E.164 format)
</ParamField>

<ParamField name="users[].teamIds" type="array" required>
  Array of team IDs the user belongs to (must have at least one)
</ParamField>

<ParamField name="users[].createAuth0Account" type="boolean">
  Whether to create Auth0 account (default: false)
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.prod.qualifi.hr/qsi/gather/users \
      -H "x-api-key: ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "users": [
          {
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@example.com",
            "teamIds": ["team-uuid-1"]
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/users', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        users: [
          {
            firstName: 'John',
            lastName: 'Doe',
            email: 'john.doe@example.com',
            teamIds: ['team-uuid-1']
          }
        ]
      })
    });
    const users = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        'https://api.prod.qualifi.hr/qsi/gather/users',
        headers={
            'x-api-key': api_key,
            'Content-Type': 'application/json'
        },
        json={
            'users': [
                {
                    'firstName': 'John',
                    'lastName': 'Doe',
                    'email': 'john.doe@example.com',
                    'teamIds': ['team-uuid-1']
                }
            ]
        }
    )
    users = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Request theme={null}
  {
    "users": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "teamIds": ["team-uuid-1", "team-uuid-2"],
        "createAuth0Account": false
      },
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane.smith@example.com",
        "teamIds": ["team-uuid-1"],
        "createAuth0Account": true
      }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "users": [
        {
          "id": "user-uuid-1",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com",
          "phone": "+1234567890",
          "isApiUser": true,
          "teamIds": ["team-uuid-1", "team-uuid-2"],
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        },
        {
          "id": "user-uuid-2",
          "firstName": "Jane",
          "lastName": "Smith",
          "email": "jane.smith@example.com",
          "phone": null,
          "isApiUser": false,
          "teamIds": ["team-uuid-1"],
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

<Callout type="warning">
  **CRITICAL**: Every user MUST be assigned to at least one team. The `teamIds`
  array is REQUIRED and must contain at least one valid team ID. All teamIds
  must belong to the organization from the API credential.
</Callout>

## List Users

List users in your organization. Optionally filter by team and include/exclude team associations.

**Endpoint:** `GET /qsi/gather/users`

<ParamField query="teamId" type="string">
  Filter users by team ID
</ParamField>

<ParamField query="includeTeams" type="boolean">
  Include team details in response (default: true)
</ParamField>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://api.prod.qualifi.hr/qsi/gather/users?teamId=team-uuid&includeTeams=true" \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const params = new URLSearchParams({
      teamId: 'team-uuid',
      includeTeams: 'true'
    });

    const response = await fetch(
      `https://api.prod.qualifi.hr/qsi/gather/users?${params}`,
      {
        headers: {
          'x-api-key': apiKey
        }
      }
    );
    const users = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    params = {
        'teamId': 'team-uuid',
        'includeTeams': True
    }
    response = requests.get(
        'https://api.prod.qualifi.hr/qsi/gather/users',
        headers={'x-api-key': api_key},
        params=params
    )
    users = response.json()
    ```
  </Tab>
</Tabs>

### Response with Team Details (includeTeams=true or omitted)

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "users": [
        {
          "id": "user-uuid-1",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com",
          "phone": "+1234567890",
          "isApiUser": true,
          "teams": [
            {
              "id": "team-uuid-1",
              "name": "Engineering Team",
              "displayName": "Engineering",
              "description": "Engineering and development team",
              "organizationId": "org-uuid",
              "createdAt": "2024-01-01T00:00:00Z",
              "updatedAt": "2024-01-01T00:00:00Z"
            },
            {
              "id": "team-uuid-2",
              "name": "Sales Team",
              "displayName": "Sales",
              "description": null,
              "organizationId": "org-uuid",
              "createdAt": "2024-01-01T00:00:00Z",
              "updatedAt": "2024-01-01T00:00:00Z"
            }
          ],
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

### Response without Team Details (includeTeams=false)

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "users": [
        {
          "id": "user-uuid-1",
          "firstName": "John",
          "lastName": "Doe",
          "email": "john.doe@example.com",
          "phone": "+1234567890",
          "isApiUser": true,
          "teamIds": ["team-uuid-1", "team-uuid-2"],
          "organizationId": "org-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## API Users vs Regular Users

**API Users** (`isApiUser: true`):

* Created without Auth0 accounts by default
* Cannot access the UI/dashboard
* Used for API operations and attribution
* Set `createAuth0Account: false` (or omit) when creating

**Regular Users** (`isApiUser: false`):

* Created with Auth0 accounts
* Can access the UI/dashboard
* Set `createAuth0Account: true` when creating

<Callout type="info">
  API users are useful for tracking API operations and attributing actions to
  specific users without requiring UI access. They must still be assigned to at
  least one team.
</Callout>

## Validation Rules

### User-Team Association Requirements

* **CRITICAL**: Every user MUST be assigned to at least one team
* When creating users:
  * `teamIds` array is REQUIRED and must contain at least one valid team ID
  * All teamIds must belong to the organization from the API credential
  * Returns 400 error if validation fails

## Error Responses

<CodeGroup>
  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Missing required fields, empty teamIds array, or invalid data"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Missing or invalid API key / Missing organization context"
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Teams" icon="users" href="/api-reference/teams">
    Learn about creating and managing teams
  </Card>

  <Card title="Credentials" icon="key" href="/api-reference/credentials">
    Learn about API credentials and authentication
  </Card>
</CardGroup>