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

# Update several Users

> Updates up to 100 Users in one call. Each User is updated on its own: a row that fails is reported with its errors and does not prevent the others from being updated. The whole call is rejected, with no User updated, only when the payload itself is invalid, a UID is unknown, or the caller cannot manage Users.

## Introduction

This endpoint updates several users in one call, for example to move people to a new department or manager, or to sync a field from your HRIS. Use it instead of one [Update a User](/api-reference/user/update-a-user) call per user.

Please note that:

1. You can update up to **100** users per call. To update more, split them into several calls.
2. Each item identifies a user by its `uid` and accepts the same attributes as [Update a User](/api-reference/user/update-a-user). Only the attributes you pass are changed.
3. Each user can appear only once per call.
4. Each user is updated on its own: if one user fails (for example because of an invalid value), the others are still updated. The response tells you, for each user, whether it was updated or why it failed, so you can retry only the failed ones.
5. The whole call is rejected, with no user updated, when the payload is invalid (no items, more than 100 items, an item without `uid`, a `uid` listed twice), when a `uid` does not match any user of your company, or when your role cannot manage users.
6. Fields that are disabled or that your role cannot edit are ignored, as with a single update.
7. The response does not contain the updated users. [Retrieve a User](/api-reference/user/retrieve-a-user) to read their new values.

## Example payload

```json theme={null}
{
  "items": [
    { "uid": "u_ybj0tgd8nmr9", "department": "tv_dep_engineering", "metadata": { "cost_center": "FR-01" } },
    { "uid": "u_k2m9xq4ww1lp", "job_title": "Engineer", "teams": [] },
    { "uid": "u_p0z8c3vb7ndq", "country": "not-a-country" }
  ]
}
```

## Example response

```json theme={null}
{
  "results": [
    { "uid": "u_ybj0tgd8nmr9", "status": "updated", "errors": [] },
    { "uid": "u_k2m9xq4ww1lp", "status": "updated", "errors": [] },
    { "uid": "u_p0z8c3vb7ndq", "status": "error", "errors": ["Country is not included in the list"] }
  ]
}
```

## Usage


## OpenAPI

````yaml patch /v1/users/batch_update
openapi: 3.0.1
info:
  title: Siit Public API
  version: v0
servers:
  - url: https://api.siit.io
security: []
paths:
  /v1/users/batch_update:
    patch:
      tags:
        - User
      summary: Update several Users
      description: >-
        Updates up to 100 Users in one call. Each User is updated on its own: a
        row that fails is reported with its errors and does not prevent the
        others from being updated. The whole call is rejected, with no User
        updated, only when the payload itself is invalid, a UID is unknown, or
        the caller cannot manage Users.
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  description: >-
                    The Users to update, each identified by its UID and carrying
                    the same attributes as the single User update.
                  items:
                    allOf:
                      - type: object
                        properties:
                          uid:
                            type: string
                            description: The UID of the User
                        required:
                          - uid
                      - $ref: '#/components/schemas/user_write'
                  minItems: 1
                  maxItems: 100
              required:
                - items
      responses:
        '200':
          description: 'Successful: each item reports whether its User was updated'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch_updated_users_object'
        '400':
          description: >-
            Invalid payload: no items, too many items, an item without UID or a
            UID listed twice
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_object'
        '403':
          description: The role of the token owner cannot manage Users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_object'
        '404':
          description: A UID does not match any User of the company
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_object'
      security:
        - bearer: []
components:
  schemas:
    user_write:
      type: object
      description: >-
        Request body for creating or updating a User. Pass UIDs (not objects)
        for relationship fields.
      properties:
        birthday_date:
          type: string
          format: date
          description: date formatted as ISO 8601 (e.g. "2020-12-15")
          nullable: true
        city:
          type: string
          nullable: true
        contract_type:
          type: string
          nullable: true
          enum:
            - contract
            - expat
            - fulltime
            - intern
            - parttime
            - temporary
        country:
          type: string
          description: 'ISO3166 alpha-2 country code (e.g: "PT")'
          nullable: true
        employee_number:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        gender:
          type: string
          enum:
            - female
            - male
            - non_binary
            - other
            - prefer_not_to_disclose
          nullable: true
        hire_date:
          type: string
          format: date
          description: date formatted as ISO 8601 (e.g. "2020-12-15")
          nullable: true
        job_leave_date:
          type: string
          format: date
          description: date formatted as ISO 8601 (e.g. "2020-12-15")
          nullable: true
        job_start_date:
          type: string
          format: date
          description: date formatted as ISO 8601 (e.g. "2020-12-15")
          nullable: true
        job_title:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        last_working_date:
          type: string
          format: date
          description: date formatted as ISO 8601 (e.g. "2020-12-15")
          nullable: true
        metadata:
          type: object
          description: >-
            Arbitrary key/value pairs attached to the User (max 10 keys, string
            values of at most 255 characters). Passed keys are merged into the
            existing metadata: absent keys are preserved, passing a key with an
            empty or null value removes it, and passing metadata as an empty
            string removes all keys.
          maxProperties: 10
          additionalProperties:
            type: string
            maxLength: 255
        preferred_language:
          type: string
          description: A language in IETF format (en-US, pt-PT, fr-FR...)
          nullable: true
        probation_end_date:
          type: string
          format: date
          description: date formatted as ISO 8601 (e.g. "2020-12-15")
          nullable: true
        work_phone:
          type: string
          nullable: true
        department:
          type: string
          description: >-
            The department this user belongs to. Pass the UID of the related
            object.
          nullable: true
        legal_entity:
          type: string
          description: >-
            The legal entity this user belongs to. Pass the UID of the related
            object.
          nullable: true
        office_location:
          type: string
          description: >-
            The office location of this user. Pass the UID of the related
            object.
          nullable: true
        report_to:
          type: string
          description: The manager of this user. Pass the UID of the related object.
          nullable: true
        teams:
          type: array
          description: >-
            Teams this user belongs to. Pass an array of UIDs of the related
            objects.
          items:
            type: string
          nullable: true
    batch_updated_users_object:
      type: object
      properties:
        results:
          type: array
          description: >-
            The outcome of each item, in the order they were sent. Entries are
            outcomes, not Users: fetch a User to read its updated attributes.
          items:
            type: object
            properties:
              uid:
                type: string
                description: The UID of the User
              status:
                type: string
                enum:
                  - updated
                  - error
              errors:
                type: array
                items:
                  type: string
                description: Why the User was not updated, empty when status is updated.
            required:
              - uid
              - status
              - errors
    errors_object:
      type: object
      properties:
        error:
          type: string
        troubleshoot:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````