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 |
Review, then approve a person’s submitted time |
POST |
/api/v2/approvals/reject |
Return a person’s submitted time for changes |
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.
Send approval_domain: "TIME" on approve and reject to review time only. Independent workspaces require this field; omitting it returns approval_domain_required. In Legacy or Linked workflows, omitting the field retains the combined time-and-expense contract. Explicit TIME always requires a reviewed preflight_fingerprint, including when there are no warnings. Do not send approval_domain to submit, which does not accept it. The submission response’s fingerprint is separate from the approval preflight.
Return Time in the App
In Time → Approval, open the person and choose Submitted in the status filter. Below the entries, click Reject, enter a Reason for rejection, and confirm. Returned time becomes Unsubmitted, ready for correction and resubmission. The confirmation label reflects whether rejection emails are enabled for the workspace.
The Needs review overview opens a broader All Statuses view. That view can show Pending approval checks, but it does not show the Approve or Reject buttons. Choose Submitted on the person’s review page to act on submitted time. A warning does not need to be acknowledged to reject time; approval warnings apply when approving.
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
With approval_domain: "TIME", approves the person’s submitted time in the period, optionally for one project, without changing expense approvals. 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 |
approval_domain |
string | Yes in Independent workflows | Send TIME for time-only review |
from |
string | Yes | Start date |
to |
string | Yes | End date |
project_id |
string | No | Limit approval to one project |
preflight_fingerprint |
string | Required to commit a TIME approval |
preflight.fingerprint from the review response below; omit it only to obtain the review |
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 |
Obtain the Review Fingerprint
There is no separate time-preflight endpoint. Send the intended scope to approve with approval_domain: "TIME" and without preflight_fingerprint. This explicit time-only request returns 409 approval_preflight_required with preflight.fingerprint, counts, blockers, and warnings, and does not approve or otherwise change the time. Keep include_unsubmitted omitted unless you intend to submit and approve unsubmitted time too.
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 '{"approval_domain":"TIME","user_id":"user_id","from":"2026-09-21","to":"2026-09-27"}'
Review the response. To approve, repeat the same scope with its preflight.fingerprint as preflight_fingerprint and every current warning code in acknowledged_warning_codes (or an empty array when there are no warnings). Resolve blockers before approving. To send the time back instead, use the same reviewed scope and fingerprint on reject, as shown below. Do not echo the fingerprint to approve if your intention is rejection.
Fingerprints reflect the selected records and current review context, including the reviewer, workspace, domain, and settings/authority. Keep the same person, period, and optional project when sending the reviewed decision. If the scope or time changes, obtain and review a fresh fingerprint. Never reuse one across people or periods.
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 with approval_domain: "TIME" to submit and approve the person’s unsubmitted and submitted time entries in one transaction, without changing expenses. 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_preflight_required |
Explicit time review needs a fingerprint before committing | Review preflight, then approve with its fingerprint and warning acknowledgments, or reject the same scope with its fingerprint |
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 or approval authority changed while the approval was being saved | Obtain and review the scope again before retrying |
Preflight-required, blocker, warning, and stale-review responses include preflight. A transaction conflict may require a new review request. The rejection endpoint does not provide a replacement preflight; obtain one from the explicit TIME approve request above.
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
With approval_domain: "TIME", returns the person’s submitted time in the period to Unsubmitted for correction and resubmission, without changing expenses. The optional reason is recorded in the audit log and included in the rejection notification when that notification is enabled.
| Field | Type | Required | Description |
|---|---|---|---|
user_id |
string | Yes | Person whose time to reject |
approval_domain |
string | Yes in Independent workflows | Send TIME for time-only review |
from |
string | Yes | Start date |
to |
string | Yes | End date |
project_id |
string | No | Limit to one project |
preflight_fingerprint |
string | Required for TIME |
preflight.fingerprint obtained from the explicit TIME approve request for this same scope |
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 '{"approval_domain":"TIME","user_id":"user_id","from":"2026-09-21","to":"2026-09-27","preflight_fingerprint":"<preflight.fingerprint from the review response>","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.