# Update user

Partially update a user. Only provided fields will be updated.

Endpoint: PATCH /users/{id}
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    Specify lookup type for faster retrieval.
If omitted, defaults to looking up by ID first, then falls back to client key if not found.
Use by=key when you know you're providing a client key for best performance.
    Enum: "id", "key"

## Request fields (application/json):

  - `email` (string)
    User's email address
    Example: "john.doe@example.com"

  - `name` (string,null)
    User's full name
    Example: "John Doe"

  - `phone` (string,null)
    User's phone number
    Example: "+1-555-123-4567"

  - `phoneExt` (string,null)
    Phone extension
    Example: "123"

  - `status` (string)
    User account status:
- PENDING: User invited but has not completed onboarding
- ACTIVE: User account is active and can access the system
- INACTIVE: User account is deactivated
    Enum: "PENDING", "ACTIVE", "INACTIVE"

  - `roles` (array)
    User's roles (replaces all existing roles)
    Enum: "CUSTOMER_REP", "CARRIER_REP", "AR_AP", "COMPLIANCE", "ADMIN"

  - `key` (string,null)
    Client-defined reference identifier
    Example: "ERP-USER-12345"

  - `datUsername` (string,null)
    DAT integration username
    Example: "johndoe_dat"

  - `mcpUsername` (string,null)
    MyCarrierPortal integration username
    Example: "johndoe_mcp"

  - `avatarId` (string,null)
    Profile avatar document ID
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `teams` (array)
    Teams this user belongs to (replaces all existing team memberships)
    Example: [{"id":"123e4567-e89b-12d3-a456-426614174000"},{"key":"TEAM-WEST-COAST"}]

## Response 200 fields (application/json):

  - `object` (string)
    Object type identifier
    Enum: "USER"

  - `id` (string, required)
    Unique user identifier
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `email` (string, required)
    User's email address
    Example: "john.doe@example.com"

  - `name` (string,null)
    User's full name
    Example: "John Doe"

  - `phone` (string,null)
    User's phone number
    Example: "+1-555-123-4567"

  - `phoneExt` (string,null)
    Phone extension
    Example: "123"

  - `status` (string, required)
    User account status:
- PENDING: User invited but has not completed onboarding
- ACTIVE: User account is active and can access the system
- INACTIVE: User account is deactivated
    Enum: "PENDING", "ACTIVE", "INACTIVE"

  - `roles` (array, required)
    User's roles within the organization
    Enum: "CUSTOMER_REP", "CARRIER_REP", "AR_AP", "COMPLIANCE", "ADMIN"

  - `key` (string,null)
    Client-defined reference identifier for this user
    Example: "ERP-USER-12345"

  - `datUsername` (string,null)
    DAT (Load Board) integration username
    Example: "johndoe_dat"

  - `mcpUsername` (string,null)
    MyCarrierPortal integration username
    Example: "johndoe_mcp"

  - `avatarId` (string,null)
    Profile avatar document ID
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `teams` (array)
    Teams this user belongs to

  - `teams.id` (string, required)
    Unique team identifier
    Example: "123e4567-e89b-12d3-a456-426614174000"

  - `teams.name` (string, required)
    Team name
    Example: "Sales Team - West Coast"

  - `teams.key` (string,null)
    Client-defined reference identifier for this team
    Example: "ERP-TEAM-WEST"

  - `teams.createdAt` (string, required)
    Timestamp when team was created
    Example: "2025-01-15T10:00:00Z"

  - `teams.updatedAt` (string, required)
    Timestamp when team was last updated
    Example: "2025-01-15T14:30:00Z"

  - `teams.deletedAt` (string,null)
    Timestamp when team was soft-deleted (null if active)

  - `createdAt` (string, required)
    Timestamp when user was created
    Example: "2025-01-15T10:00:00Z"

  - `updatedAt` (string, required)
    Timestamp when user was last updated
    Example: "2025-01-15T14:30:00Z"

  - `deletedAt` (string,null)
    Timestamp when user was soft-deleted (null if active)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message

## Response 429 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message