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

# Update user

> PATCH /users/{userId} — update writable member fields

## Endpoint

```http theme={null}
PATCH https://api.routera.io/users/{userId}
```

**Route:** `/users/{userId}`\
**Authentication:** Bearer JWT

Partial update with a **flat** JSON body (not `{ fields: { ... } }`). At least one writable field is required.

## Path parameters

| Parameter | Required | Description    |
| --------- | -------- | -------------- |
| `userId`  | Yes      | User ID (UUID) |

## Request body

| Field                       | Description                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `full_name`                 | Display name                                                                                          |
| `first_name`                | First name                                                                                            |
| `last_name`                 | Last name                                                                                             |
| `phone`                     | Phone number                                                                                          |
| `office_status`             | Whether the member is in office (boolean)                                                             |
| `time_zone`                 | IANA time zone (e.g. `America/New_York`)                                                              |
| `external_id`               | External identifier                                                                                   |
| `working_hours`             | Array of `{ days, start_date, end_date }` (`days` e.g. `Mon - Fri` or `monday`; times as `HH:mm`)     |
| `out_office_dates`          | Array of `{ start_date, end_date }` (ISO date or timestamp); extra keys like `created_by` are ignored |
| `capacity`                  | Capacity configuration                                                                                |
| `can_receive_notifications` | Whether the member can receive notifications                                                          |
| `notification_preferences`  | Notification preference categories                                                                    |
| `role_id`                   | Role UUID that belongs to the authenticated account                                                   |

### Read-only (rejected if present)

`id`, `email`, `calendars`, `archived`, `archived_by`

Unknown or read-only keys return **400**.

```json theme={null}
{
  "full_name": "Jane Doe",
  "phone": "+15551234567",
  "office_status": true,
  "time_zone": "America/New_York",
  "working_hours": [
    {
      "days": "Mon - Fri",
      "start_date": "09:00",
      "end_date": "17:00"
    }
  ],
  "out_office_dates": [
    {
      "start_date": "2026-09-10T00:00:00.000Z",
      "end_date": "2026-09-12T23:59:59.000Z"
    }
  ],
  "role_id": "770e8400-e29b-41d4-a716-446655440002"
}
```

## Response

**200** — Updated user object (same shape as get)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "full_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "role": "Administrator",
  "external_id": null,
  "phone": null,
  "office_status": true,
  "working_hours": [
    {
      "days": "Mon - Fri",
      "start_date": "09:00",
      "end_date": "17:00"
    },
    {
      "days": "saturday",
      "start_date": "10:00",
      "end_date": "14:00"
    }
  ],
  "out_office_dates": [
    {
      "start_date": "2026-04-02T12:00:00.000Z",
      "end_date": "2026-04-03T12:00:00.000Z",
      "created_by": "user@example.com"
    }
  ],
  "time_zone": "America/New_York",
  "calendars": {
    "outlook": "user@example.com"
  },
  "capacity": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Leads",
      "current_capacity": 2,
      "max_capacity": 10,
      "assignment_type": "user"
    }
  ],
  "can_receive_notifications": true,
  "notification_preferences": [
    "billing",
    "routing",
    "system"
  ],
  "archived": false
}
```

## Errors

| Status | When                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid path/id, JSON body, unknown/read-only fields, or invalid `role_id` / `time_zone` / `out_office_dates` |
| `401`  | Missing or invalid account context in JWT                                                                     |
| `404`  | Member not found for this account                                                                             |
| `409`  | Cannot update an archived user                                                                                |
| `500`  | Internal server error                                                                                         |


## OpenAPI

````yaml PATCH /users/{userId}
openapi: 3.0.1
info:
  title: Routera API
  description: >-
    Routera v2 REST API. Objects CRUD for contacts, companies, deals, and
    tickets, users and routers APIs, plus router dispatch.
  version: 1.0.0
servers:
  - url: https://api.routera.io
    description: >-
      API Gateway base URL (override with ROUTERA_API_BASE_URL when generating
      docs)
security: []
tags:
  - name: Authentication
    description: Access token issuance
  - name: Contacts
    description: Contact records
  - name: Companies
    description: Company records
  - name: Deals
    description: Deal records
  - name: Tickets
    description: Ticket records
  - name: Users
    description: Account members
  - name: Routers
    description: Router configuration
  - name: Dispatch
    description: Router assignment
paths:
  /users/{userId}:
    patch:
      tags:
        - Users
      summary: Update user
      description: >-
        Partial update of writable user and member_account fields. Unknown or
        read-only keys return 400. Cannot update an archived user (409).
      operationId: updateUser
      parameters:
        - name: userId
          in: path
          required: true
          description: User ID (UUID)
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
            example:
              full_name: Jane Doe
              phone: '+15551234567'
              office_status: true
              time_zone: America/New_York
              working_hours:
                - days: Mon - Fri
                  start_date: '09:00'
                  end_date: '17:00'
              out_office_dates:
                - start_date: '2026-09-10T00:00:00.000Z'
                  end_date: '2026-09-12T23:59:59.000Z'
              role_id: 770e8400-e29b-41d4-a716-446655440002
      responses:
        '200':
          description: Updated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                email: user@example.com
                full_name: Jane Doe
                first_name: Jane
                last_name: Doe
                role: Administrator
                external_id: null
                phone: null
                office_status: true
                working_hours:
                  - days: Mon - Fri
                    start_date: '09:00'
                    end_date: '17:00'
                  - days: saturday
                    start_date: '10:00'
                    end_date: '14:00'
                out_office_dates:
                  - start_date: '2026-04-02T12:00:00.000Z'
                    end_date: '2026-04-03T12:00:00.000Z'
                    created_by: user@example.com
                time_zone: America/New_York
                calendars:
                  outlook: user@example.com
                capacity:
                  - id: 660e8400-e29b-41d4-a716-446655440001
                    name: Leads
                    current_capacity: 2
                    max_capacity: 10
                    assignment_type: user
                can_receive_notifications: true
                notification_preferences:
                  - billing
                  - routing
                  - system
                archived: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Cannot update an archived user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
components:
  schemas:
    UserUpdate:
      type: object
      description: >-
        Partial update body. At least one writable field is required. Unknown or
        read-only keys return 400.
      properties:
        full_name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
        office_status:
          type: boolean
        time_zone:
          type: string
          description: IANA time zone (e.g. America/New_York)
        external_id:
          type: string
          nullable: true
        working_hours:
          type: array
          items:
            $ref: '#/components/schemas/WorkingHour'
          description: Working hour ranges (`days`, `start_date`, `end_date` as `HH:mm`)
        out_office_dates:
          type: array
          items:
            type: object
            required:
              - start_date
              - end_date
            properties:
              start_date:
                type: string
              end_date:
                type: string
          description: >-
            Only start_date and end_date are accepted per entry; extra keys are
            ignored
        capacity:
          type: array
          items:
            type: object
            additionalProperties: true
        can_receive_notifications:
          type: boolean
        notification_preferences:
          type: array
          items:
            type: string
        role_id:
          type: string
          description: Role UUID that belongs to the authenticated account
      example:
        full_name: Jane Doe
        phone: '+15551234567'
        office_status: true
        time_zone: America/New_York
        working_hours:
          - days: Mon - Fri
            start_date: '09:00'
            end_date: '17:00'
        out_office_dates:
          - start_date: '2026-09-10T00:00:00.000Z'
            end_date: '2026-09-12T23:59:59.000Z'
        role_id: 770e8400-e29b-41d4-a716-446655440002
    User:
      type: object
      description: >-
        Account member (user + member_account). Role is the display name string.
        Archived members include archived timestamp and archived_by.
      properties:
        id:
          type: string
          description: User ID (UUID)
        email:
          type: string
        full_name:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        role:
          type: string
          description: Role display name (read-only)
        external_id:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        office_status:
          type: boolean
        working_hours:
          type: array
          items:
            $ref: '#/components/schemas/WorkingHour'
          description: >-
            Working hour ranges. Empty array means available 24/7. Times are
            interpreted in `time_zone`.
          example:
            - days: Mon - Fri
              start_date: '09:00'
              end_date: '17:00'
            - days: saturday
              start_date: '10:00'
              end_date: '14:00'
        out_office_dates:
          type: array
          items:
            $ref: '#/components/schemas/OutOfficeDate'
        time_zone:
          type: string
          description: IANA time zone
          example: America/New_York
        calendars:
          type: object
          additionalProperties:
            type: string
          description: Active calendar configs keyed by provider to email
        capacity:
          type: array
          items:
            $ref: '#/components/schemas/UserCapacity'
        can_receive_notifications:
          type: boolean
        notification_preferences:
          type: array
          items:
            type: string
        archived:
          description: false when active, or ISO timestamp when archived
          oneOf:
            - type: boolean
            - type: string
              format: date-time
        archived_by:
          type: string
          description: Present when archived
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        email: user@example.com
        full_name: Jane Doe
        first_name: Jane
        last_name: Doe
        role: Administrator
        external_id: null
        phone: null
        office_status: true
        working_hours:
          - days: Mon - Fri
            start_date: '09:00'
            end_date: '17:00'
          - days: saturday
            start_date: '10:00'
            end_date: '14:00'
        out_office_dates:
          - start_date: '2026-04-02T12:00:00.000Z'
            end_date: '2026-04-03T12:00:00.000Z'
            created_by: user@example.com
        time_zone: America/New_York
        calendars:
          outlook: user@example.com
        capacity:
          - id: 660e8400-e29b-41d4-a716-446655440001
            name: Leads
            current_capacity: 2
            max_capacity: 10
            assignment_type: user
        can_receive_notifications: true
        notification_preferences:
          - billing
          - routing
          - system
        archived: false
    ApiError:
      type: object
      required:
        - message
        - error
      properties:
        message:
          type: string
        error:
          type: boolean
          enum:
            - true
        field:
          type: string
          description: Field that caused a conflict (409 duplicate responses)
    WorkingHour:
      type: object
      required:
        - days
        - start_date
        - end_date
      properties:
        days:
          type: string
          description: >-
            Day or range: `monday`…`sunday`, `Mon - Fri` / `mon-fri`, `Sat -
            Sun` / `sat-sun`, `saturday`, or `sunday`
          example: Mon - Fri
        start_date:
          type: string
          description: Start time in `HH:mm` (member time zone)
          example: '09:00'
        end_date:
          type: string
          description: End time in `HH:mm` (member time zone)
          example: '17:00'
    OutOfficeDate:
      type: object
      properties:
        start_date:
          type: string
          format: date-time
          description: Range start (ISO 8601)
        end_date:
          type: string
          format: date-time
          description: Range end (ISO 8601); must be >= start_date
        created_by:
          type: string
          description: Email of who created the range (response only)
    UserCapacity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        current_capacity:
          type: integer
        max_capacity:
          type: integer
        assignment_type:
          type: string
          description: e.g. user or team
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT with valid account context.

````