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

# Update Employee

> Modify an existing employee's details

# Update Employee

Update an existing employee's information. You can modify any combination of the employee's fields.

<Note>
  **Partial Updates**: Only include the fields you want to update. Fields not included in the request body will remain unchanged.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Path Parameters

<ParamField path="employee_id" type="string" required>
  The unique identifier (UUID) of the employee to update

  **Example:** `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

### Body Parameters

<ParamField body="name" type="string">
  Employee's full name (1-255 characters)

  **Example:** `"John Smith Jr."`
</ParamField>

<ParamField body="email" type="string">
  Employee's email address

  **Example:** `"john.smith.new@company.com"`
</ParamField>

<ParamField body="situation" type="string">
  Employment situation

  **Available values:** `active`, `inactive`, `terminated`

  **Example:** `"inactive"`
</ParamField>

<ParamField body="status" type="string">
  Data collection status

  **Available values:** `uploaded`, `loading`

  **Example:** `"uploaded"`
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier (UUID)
</ResponseField>

<ResponseField name="name" type="string | null">
  Employee's full name
</ResponseField>

<ResponseField name="email" type="string | null">
  Employee's email address
</ResponseField>

<ResponseField name="organization_id" type="string">
  Organization UUID
</ResponseField>

<ResponseField name="situation" type="string | null">
  Employment status: `active`, `inactive`, or `terminated`
</ResponseField>

<ResponseField name="status" type="string">
  Data status: `uploaded` or `loading`
</ResponseField>

<ResponseField name="periods" type="array | null">
  List of commuting periods
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the employee was created
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  Timestamp when the employee was last updated
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X PATCH "https://api.dcycle.io/v1/employees/550e8400-e29b-41d4-a716-446655440000" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    -H "Content-Type: application/json" \
    -d '{
      "situation": "inactive"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")
  employee_id = "550e8400-e29b-41d4-a716-446655440000"

  headers = {
      "x-api-key": api_key,
      "x-organization-id": org_id,
      "Content-Type": "application/json"
  }

  # Only include fields to update
  payload = {
      "situation": "inactive"
  }

  response = requests.patch(
      f"https://api.dcycle.io/v1/employees/{employee_id}",
      headers=headers,
      json=payload
  )

  employee = response.json()
  print(f"Updated: {employee['name']}")
  print(f"New situation: {employee['situation']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const apiKey = process.env.DCYCLE_API_KEY;
  const orgId = process.env.DCYCLE_ORG_ID;
  const employeeId = '550e8400-e29b-41d4-a716-446655440000';

  const headers = {
    'x-api-key': apiKey,
    'x-organization-id': orgId,
    'Content-Type': 'application/json'
  };

  // Only include fields to update
  const payload = {
    situation: 'inactive'
  };

  axios.patch(
    `https://api.dcycle.io/v1/employees/${employeeId}`,
    payload,
    { headers }
  )
  .then(response => {
    const employee = response.data;
    console.log(`Updated: ${employee.name}`);
    console.log(`New situation: ${employee.situation}`);
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Smith",
  "email": "john.smith@company.com",
  "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
  "situation": "inactive",
  "status": "uploaded",
  "periods": [...],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-11-24T14:45:00Z"
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

**Solution:** Verify your API key is valid and active.

### 404 Not Found

**Cause:** Employee not found or doesn't belong to your organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "EMPLOYEE_NOT_FOUND",
  "detail": "Employee with id=UUID('...') not found"
}
```

**Solution:** Verify the employee ID is correct and belongs to your organization.

### 422 Validation Error

**Cause:** Invalid field values or extra fields

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["body", "situation"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}
```

**Solution:** Check that all provided values are valid. Only use allowed enum values for `situation` and `status`.

## Use Cases

### Update Employee Situation

Change an employee's employment status:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def update_employee_situation(employee_id, new_situation):
    """Update employee's employment situation"""
    response = requests.patch(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers,
        json={"situation": new_situation}
    )
    return response.json()

# Mark employee as terminated
employee = update_employee_situation(
    "550e8400-e29b-41d4-a716-446655440000",
    "terminated"
)
print(f"{employee['name']} is now {employee['situation']}")
```

### Update Employee Email

Change an employee's email address:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def update_employee_email(employee_id, new_email):
    """Update employee's email address"""
    response = requests.patch(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers,
        json={"email": new_email}
    )
    return response.json()

employee = update_employee_email(
    "550e8400-e29b-41d4-a716-446655440000",
    "john.smith.new@company.com"
)
print(f"Email updated to: {employee['email']}")
```

### Update Multiple Fields

Update several fields at once:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def update_employee(employee_id, updates):
    """Update employee with multiple fields"""
    response = requests.patch(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers,
        json=updates
    )
    return response.json()

employee = update_employee(
    "550e8400-e29b-41d4-a716-446655440000",
    {
        "name": "John Smith Jr.",
        "email": "john.jr@company.com",
        "situation": "active"
    }
)
print(f"Updated: {employee['name']} ({employee['email']})")
```

### Mark Employee as Terminated

Handle employee offboarding:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def offboard_employee(employee_id):
    """Mark employee as terminated during offboarding"""
    response = requests.patch(
        f"https://api.dcycle.io/v1/employees/{employee_id}",
        headers=headers,
        json={
            "situation": "terminated",
            "status": "uploaded"
        }
    )
    return response.json()

# Offboard employee
employee = offboard_employee("550e8400-e29b-41d4-a716-446655440000")
print(f"{employee['name']} has been offboarded")
```

### Bulk Update Employees

Update multiple employees' status:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def bulk_update_situation(employee_ids, new_situation):
    """Update situation for multiple employees"""
    results = {"success": [], "failed": []}

    for emp_id in employee_ids:
        try:
            response = requests.patch(
                f"https://api.dcycle.io/v1/employees/{emp_id}",
                headers=headers,
                json={"situation": new_situation}
            )
            if response.status_code == 200:
                results["success"].append(emp_id)
            else:
                results["failed"].append({"id": emp_id, "error": response.text})
        except Exception as e:
            results["failed"].append({"id": emp_id, "error": str(e)})

    return results

# Mark employees as inactive
employee_ids = [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
]

results = bulk_update_situation(employee_ids, "inactive")
print(f"Updated: {len(results['success'])}")
print(f"Failed: {len(results['failed'])}")
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Employee" icon="user" href="/api-reference/employees/get">
    View employee details
  </Card>

  <Card title="Delete Employee" icon="trash" href="/api-reference/employees/delete">
    Remove an employee
  </Card>

  <Card title="List Employees" icon="list" href="/api-reference/employees/list">
    View all employees
  </Card>

  <Card title="Update Commuting Period" icon="pencil" href="/api-reference/employees/commuting-periods/update">
    Modify commuting data
  </Card>
</CardGroup>