How to Use the Timecloud Public API

Getting Started

• Contact your Timecloud account manager to enable API access for your company.
• You will receive client credentials (a Client ID and Client Secret).
• All API communication happens over HTTPS.

Authentication

1. Call the /oauth/token endpoint with your Client ID and Client Secret.
2. You'll receive a Bearer token.
3. Include this token in the Authorization header of all subsequent requests:
   Authorization: Bearer <your-token>

Date & Time Format

• Request date fields:YYYY-MM-DD (e.g. 2024-01-15)
• Response date-time fields: ISO 8601 UTC (e.g. 2024-01-15T09:30:00.000Z)
• All times are returned in UTC.

Available Endpoints

Below is an overview of what you can manage through the API. Full endpoint details (request/response schemas, query parameters, and error codes) are available in the interactive Swagger documentation provided with your API credentials.

Employees

Tips:

• Assign roles, departments, or default job items by passing arrays of IDs in companyRoles, userGroups, or defaultJobItems.

Company Roles

Note: You cannot delete a role while active employees are still assigned to it. Unassign employees first.

Departments (User Groups)

Notes:

• Departments can be nested. Pass parentGroupId when creating to nest under a parent.
• Deleting a department also removes its sub-departments. Employees are automatically unassigned.
• Deletion is blocked if active job items reference the department.

Roster — Employee View

Tips:

• Set isPublished: true on a shift to publish it immediately. Otherwise, it stays as a draft until you call /publish.
• Use conflictAuthorised: true to bypass overlap checks when you know a double-booking is intentional.
• Filter publish/clear actions by employeeIds or userGroupIds query parameters.

Roster — Shift View

Tips:

• After creating shifts, the response includes shiftMappings so you can map your payload to the created shift IDs.
• Send invitations with draft=true to save without notifying employees.

Attendance & Checkin Pairs

Notes:

• Checkin pairs use upsert via POST: include the checkin _id to update an existing checkin, or omit it to create a new one.
• Writes and deletes are blocked when the attendance day has been manager-approved (signed off).
• Each response returns the fully recalculated attendance record, so you always have up-to-date totals.

Job Items

Company & Shift Templates

Payroll Report

How it works:

• Provide a date range (start-date, end-date), optional employee IDs, and optional department filters.
• Results are paginated by employee. Use the optional page and pageSize fields to control which slice of employees is returned.
• The response returns data (report rows), errors (employees that could not be calculated), and pagination metadata (total, page, pageSize, totalPages).
• Successfully processed employees appear in data. Employees that encountered a processing issue are omitted from data and reported in errors instead.

Pagination:

• page — The page number to retrieve (default: 1).
• pageSize — Number of employees per page (default: 50, maximum: 50).
• Employees are returned in a consistent order. To retrieve all employees, increment page until page exceeds totalPages.
• If page is beyond the last page of results, data returns an empty array with no error.

Response structure:

• data — A two-dimensional array of strings. When data rows exist, the first row contains column headers; subsequent rows contain the timesheet data for each successfully processed employee. When the requested page has no matching data, data is an empty array.
• errors — An array of objects, each describing an employee whose timesheet could not be generated. Each error includes:
  • employeeId — The ID of the affected employee.
  • employeeName — The employee's full name.
  • date — The date (in your company timezone, YYYY-MM-DD) of the shift that caused the issue, or null if not shift-specific.
  • message — A human-readable description of what went wrong.
• total — Total number of employees matching your filters.
• page — The current page number.
• pageSize — The number of employees per page.
• totalPages — The total number of pages available.

Tips:

• Always check the errors array after receiving a response. An empty errors array means all employees on that page were processed successfully.
• If an employee appears in errors, their timesheet lines are excluded from data. Review the error message and correct the underlying issue before re-generating.
• The maximum date range is governed by your company's pay period.
• To fetch a complete report for all employees, loop through pages starting at page=1 and increment until page exceeds totalPages.

Common Integration Patterns

• Sync employees from your HRIS: Use GET /employees to compare, then POST to create or PATCH to update.
• Build a roster: List shift templates, then POST /rosters/employee or POST /rosters/shift to assign shifts. Call /publish when ready.
• Push timesheet data: Use POST /attendances/{id}/checkin-pairs to write clock-in/out records from an external system.
• Archive leavers:PATCH /employees/{id} with {"active": false}.
• Set up your org structure: Create departments via POST /company/groups (nest with parentGroupId), then assign employees.
• Generate payroll reports: Call POST /payroll/providers/{payrollProviderId}/report-builder/generate with your date range. Use page and pageSize to paginate through employees. Process the data rows from each page and handle any entries in errors for employees that could not be calculated.

Error Handling

• 400 — Bad request (missing or invalid fields). Check the response body for details.
• 401 — Unauthorised. Your token may have expired — request a new one.
• 404 — Resource not found. Verify the ID exists.
• 409 — Conflict (e.g. overlapping roster shifts). Use conflictAuthorised: true to override where appropriate.
• 422 — Unprocessable (e.g. writing to a manager-approved attendance day).

Need Help?

Reach out to your Timecloud account manager or contact support@jointimecloud.com for API access, troubleshooting, or integration guidance.