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.