Skip to main content
PATCH
/
v1
/
employees
/
{employee_id}
Update Employee
const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', email: '<string>', situation: '<string>', status: '<string>'})
};

fetch('https://api.dcycle.io/v1/employees/{employee_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "name": {},
  "email": {},
  "organization_id": "<string>",
  "situation": {},
  "status": "<string>",
  "periods": {},
  "created_at": {},
  "updated_at": {}
}

​
Update Employee

Update an existing employee’s information. You can modify any combination of the employee’s fields.
Partial Updates: Only include the fields you want to update. Fields not included in the request body will remain unchanged.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Path Parameters

​
employee_id
string
required
The unique identifier (UUID) of the employee to updateExample: 550e8400-e29b-41d4-a716-446655440000

​
Body Parameters

​
name
string
Employee’s full name (1-255 characters)Example: "John Smith Jr."
​
email
string
Employee’s email addressExample: "john.smith.new@company.com"
​
situation
string
Employment situationAvailable values: active, inactive, terminatedExample: "inactive"
​
status
string
Data collection statusAvailable values: uploaded, loadingExample: "uploaded"

​
Response

​
id
string
Unique identifier (UUID)
​
name
string | null
Employee’s full name
​
email
string | null
Employee’s email address
​
organization_id
string
Organization UUID
​
situation
string | null
Employment status: active, inactive, or terminated
​
status
string
Data status: uploaded or loading
​
periods
array | null
List of commuting periods
​
created_at
datetime
Timestamp when the employee was created
​
updated_at
datetime
Timestamp when the employee was last updated

​
Example

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"
  }'

​
Successful Response

{
  "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 
{
  "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 
{
  "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 
{
  "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: 
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: 
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: 
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: 
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: 
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'])}")

Get Employee

View employee details

Delete Employee

Remove an employee

List Employees

View all employees

Update Commuting Period

Modify commuting data