Attendance

Attendance API – Zoho People check-in/out and attendance reports.

Endpoints covered

  • POST attendance – single check-in / check-out

  • POST attendance/bulkImport – bulk attendance import

  • GET  attendance/getUserReport – attendance report for a period

  • GET  attendance/getAttendanceEntries – daily clock entries

  • GET  attendance/getShiftConfiguration – shift configuration

Scope required: ZOHOPEOPLE.attendance.ALL

Note

The check-in / check-out write endpoints require the authenticated user to have the “Check-in/Check-out” or “Regularize Attendance” permission enabled in Zoho People → Settings → Attendance → Permissions. Read endpoints (getUserReport) work for all roles.

zoho_people.api.attendance.CHECKIN_DATE_FORMAT: str = 'dd/MM/yyyy HH:mm:ss'

Date-time format expected by the check-in / check-out API.

class zoho_people.api.attendance.AttendanceAPI(client)[source]

Bases: object

Read and write attendance records in Zoho People.

Obtain an instance via ZohoPeopleClient.attendance.

Examples

Record a single check-in and check-out:

client.attendance.checkin(
    email_id="mario.rossi@company.com",
    checkin="25/04/2026 09:00:00",
    checkout="25/04/2026 18:00:00",
)

Fetch the monthly attendance report:

report = client.attendance.get_user_report(
    start_date="01/04/2026",
    end_date="30/04/2026",
    date_format="dd/MM/yyyy",
)
Parameters:

client (ZohoPeopleClient)

checkin(checkin, checkout=None, *, emp_id=None, email_id=None, map_id=None, date_format='dd/MM/yyyy HH:mm:ss')[source]

Record a check-in (and optionally a check-out) for an employee.

Parameters:

  • checkin (str) – Check-in datetime string, e.g. "25/04/2026 09:00:00".

  • checkout (str | None) – Check-out datetime string. Omit to record only the entry.

  • emp_id (str | None) – Employee ID (e.g. "EMP001" or "IMP085").

  • email_id (str | None) – Employee e-mail address.

  • map_id (str | None) – Biometric device mapper ID.

  • date_format (str) – Datetime format (default "dd/MM/yyyy HH:mm:ss").

Returns:

Zoho API response.

Return type:

dict

Raises:

ValueError – If none of emp_id, email_id, map_id is provided.

checkout(checkout, *, emp_id=None, email_id=None, map_id=None, date_format='dd/MM/yyyy HH:mm:ss')[source]

Record a standalone check-out (employee already checked in).

Raises:

ValueError – If none of emp_id, email_id, map_id is provided.

Parameters:

  • checkout (str)

  • emp_id (str | None)

  • email_id (str | None)

  • map_id (str | None)

  • date_format (str)

Return type:

dict[str, Any]

bulk_import(records, date_format='yyyy-MM-dd HH:mm:ss')[source]

Import multiple attendance records in a single request.

Zoho processes check-in and check-out as separate entries, so each record should contain either checkIn or checkOut (not both):

records = [
    {"checkIn":  "2026-04-01 09:00:00"},
    {"checkOut": "2026-04-01 18:00:00"},
]
client.attendance.bulk_import(records)
Parameters:

  • records (list[dict[str, Any]]) – List of check-in / check-out dicts.

  • date_format (str) – Datetime format for all records (default "yyyy-MM-dd HH:mm:ss").

Returns:

Import result; may contain an errorDates key on partial failure.

Return type:

dict

get_user_report(start_date, end_date, *, emp_id=None, email_id=None, map_id=None, date_format=None, start_index=0)[source]

Retrieve the attendance report for a date range.

Without an employee identifier the response covers the authenticated user. Paginate with start_index in steps of 100.

Parameters:

  • start_date (str) – Period start (e.g. "01/04/2026").

  • end_date (str) – Period end.

  • date_format (str | None) – Date format if different from the organisation default.

  • start_index (int) – Pagination offset (0, 100, 200, …).

  • emp_id (str | None)

  • email_id (str | None)

  • map_id (str | None)

Returns:

Each item contains employeeDetails and attendanceDetails.

Return type:

list[dict]

get_entries(date, *, emp_id=None, email_id=None, erecno=None, map_id=None, date_format=None)[source]

Retrieve individual clock events (in/out timestamps) for a single day.

Parameters:

  • date (str) – Day string in the organisation’s format or date_format.

  • emp_id (str | None)

  • email_id (str | None)

  • erecno (str | None)

  • map_id (str | None)

  • date_format (str | None)

Returns:

Clock entries with timestamps and metadata.

Return type:

list[dict]

get_shift_configuration(start_date, end_date, *, emp_id=None, email_id=None, map_id=None)[source]

Retrieve the shift configuration for an employee over a period.

Parameters:

  • start_date (str) – Period start in yyyy-MM-dd format.

  • end_date (str) – Period end in yyyy-MM-dd format.

  • emp_id (str | None)

  • email_id (str | None)

  • map_id (str | None)

Returns:

Shift details: name, start/end times, weekends, public holidays.

Return type:

dict