Timesheet Approvals API
These endpoints run the same approval workflow as Time → Approval in Keito, including its preflight review, notifications, and audit log. They require the Timesheet approvals feature (Pro or Business) to be switched on for the workspace. Detect support through time-approvals-v1 in X-Keito-Features.
Each time entry’s current state is in its approval_status field. See Approval Status.
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v2/approvals/submit |
Submit your own or an authorized teammate’s time for approval |
POST |
/api/v2/approvals/approve |
Approve a person’s submitted time and expenses |
POST |
/api/v2/approvals/reject |
Reject a person’s submitted time and expenses |
Dates are YYYY-MM-DD and inclusive, and a period can cover at most 366 days. Bodies are strict JSON: unknown fields return 400. Every endpoint accepts Idempotency-Key; a 409 response releases the key so you can retry with corrected input.
Permissions
| Identity | Submit | Approve and reject |
|---|---|---|
| Owner or Administrator | Anyone in the workspace | Anyone in the workspace |
| Manager | Own time; assigned teammates with Edit time and expenses | Teammates assigned to them, and time on projects they manage only with the approve time on projects they manage permission |
| Member or contractor | Own time | No |
| Personal read-only sync key | No | No |
A person outside your approval reach returns 403. A person or project from another workspace returns 404. If approvals are not available on the plan or are switched off, the endpoints return 403.
Submit Time
POST /api/v2/approvals/submit
Submits one person’s completed, unsubmitted, and unbilled time in the period, like Submit for approval on the Day and Week views, and notifies their approvers. Omit user_id (or send your own ID) to submit your own time. Owners and Administrators may select another workspace member; managers need Edit time and expenses and a directly assigned teammate. Other cross-person submissions return 403 without changes. A deactivated person’s timesheet is refused; for managed contractors, only manually entered time is submitted. The audit trail records the caller as the submitter.
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string | No | Person to submit for; defaults to the authenticated person and follows the permissions above |
from |
string | Yes | Start date |
to |
string | Yes | End date |
fingerprint |
string | No | Fingerprint from an earlier submit response. If the period has changed since, the request fails with submission_stale. |
curl -X POST https://app.keito.ai/api/v2/approvals/submit \
-H "Authorization: Bearer $KEITO_API_KEY" \
-H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: submit-2026-09-21" \
--data '{"from":"2026-09-21","to":"2026-09-27"}'
A successful response returns submitted_count, submitted_seconds, and fingerprint. A running timer in the period returns 409 with error: "running_timer".
Approve Time
POST /api/v2/approvals/approve
Approves every submitted time entry and expense for one person in the period, optionally for one project. Approved time is locked, and its week refuses new or changed time (approved_timesheet_week_locked) until an approver withdraws the approval in Keito.
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string | Yes | Person whose time to approve |
from |
string | Yes | Start date |
to |
string | Yes | End date |
project_id |
string | No | Limit approval to one project |
preflight_fingerprint |
string | No | Fingerprint from the preflight you reviewed |
acknowledged_warning_codes |
string[] | No | Every warning code from that preflight |
include_unsubmitted |
boolean | No | Submit and approve unsubmitted items too; defaults to false and always requires a reviewed preflight |
curl -X POST https://app.keito.ai/api/v2/approvals/approve \
-H "Authorization: Bearer $KEITO_API_KEY" \
-H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: approve-2026-09-21-user" \
--data '{"user_id":"user_id","from":"2026-09-21","to":"2026-09-27"}'
A successful response returns time_entry_count, expense_count, preflight_fingerprint, and acknowledged_warning_codes. If nothing was submitted in the period, the counts are 0.
Submit and Approve
Set include_unsubmitted: true to submit and approve the person’s unsubmitted and submitted time entries and expenses in one transaction. This uses the same approver reach, audit trail and notifications as Submit and approve in Keito; it does not grant a new approval permission.
First send the intended scope with the flag. Without preflight_fingerprint, the response is 409 approval_preflight_required with the current preflight (or approval_blocked when something blocks approval). Review its counts, blockers and warnings, then retry with preflight.fingerprint as preflight_fingerprint and every warning code in acknowledged_warning_codes. Recheck a stale preflight rather than reusing an old approval.
Approved and billed items, and records still marked rejected, are unchanged. Time rejected by an approver in Keito returns to unsubmitted and is therefore included. A running timer still blocks the operation; a review exceeding 1,000 records returns 400. Without the flag, approval continues to handle submitted items only.
Preflight Review
Approval runs the same preflight review as the app, and the API never skips it:
409 error |
Meaning | What to do |
|---|---|---|
approval_blocked |
Something prevents approval, such as a running timer or unsubmitted time in the period | Resolve the blocker. Blockers cannot be acknowledged. |
approval_warnings_unacknowledged |
The review found warnings, such as hours below expected, time outside working capacity, or overlapping entries | Check the returned preflight, then retry with its fingerprint as preflight_fingerprint and every warning code in acknowledged_warning_codes |
approval_preflight_stale |
The time changed after you reviewed it | Review the fresh preflight in the response and retry |
approval_conflict |
Time changed while the approval was being saved | Retry the request |
Each preflight error includes the current preflight with its fingerprint, blockers, and warnings.
Workspace warning settings apply. Setting Hours below expected or Time outside working capacity to Don’t warn removes the corresponding warning from preflight; sending those codes in acknowledged_warning_codes is still accepted.
Reject Time
POST /api/v2/approvals/reject
Rejects a person’s submitted time and expenses in the period and returns them to the person to correct and resubmit. The reason is included in their notification and the audit log.
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string | Yes | Person whose time to reject |
from |
string | Yes | Start date |
to |
string | Yes | End date |
project_id |
string | No | Limit to one project |
reason |
string | No | Explanation for the person, up to 2000 characters |
curl -X POST https://app.keito.ai/api/v2/approvals/reject \
-H "Authorization: Bearer $KEITO_API_KEY" \
-H "Keito-Account-Id: $KEITO_ACCOUNT_ID" \
-H "Content-Type: application/json" \
--data '{"user_id":"user_id","from":"2026-09-21","to":"2026-09-27","reason":"Please split the Tuesday entry by task."}'
A successful response returns time_entry_count and expense_count.
Withdrawing an approval is available in Keito but not yet through the API.