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.