Sync a time entry from an external system

POST 
/integration/time-entries

Idempotently creates a time entry from an external provider (e.g. Illumera). The combination of externalSystem + externalId is used as the idempotency key: a second call with the same pair returns the existing entry (HTTP 200) without creating a duplicate.

Requires an org-scoped API key — project-scoped keys are rejected with scope_violation.

Plan gate: the organisation must have the time_tracking feature enabled; disabled workspaces receive a 402 response with reason: feature_disabled.

Accepts an optional Idempotency-Key header for network-level replay safety.

Request

Header Parameters

Idempotency-Key string

Optional idempotency key (24 h cache). Repeat calls with the same key and path return the cached response.

Body

required

projectIdstringrequired
Align project UUID the time entry belongs to.
Possible values: non-empty
Example: 7b1e2c3d-0000-0000-0000-000000000001
userIdstringrequired
Align user UUID who performed the work.
Possible values: non-empty
Example: 9a8b7c6d-0000-0000-0000-000000000002
workDatestringrequired
ISO date (YYYY-MM-DD) or ISO 8601 datetime string for the day the work occurred.
Example: 2025-01-15
minutesintegerrequired
Duration of the work in minutes (1–1440).
Possible values: >= 1 and <= 1440
Example: 150
billableboolean
Whether the time is billable. Defaults to true.
Example: true
descriptionstring
Free-text description of the work performed (max 2000 chars).
Possible values: <= 2000 characters
Example: Sprint planning session.
entryIdstring
UUID of an existing Align entry/ticket to associate with this time entry. Must belong to the specified project.
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
externalSystemstringrequired
Identifier for the external system originating this time entry (e.g. illumera, jira, harvest).
Possible values: non-empty
Example: illumera
externalIdstringrequired
Stable unique ID for this time entry within the external system. Used as the idempotency key: a second call with the same externalSystem + externalId returns the existing entry without creating a duplicate.
Possible values: non-empty
Example: illumera-te-001

externalMetadata

object

Arbitrary key-value metadata from the external system (e.g. task name, project code). Stored as-is and returned on reads.

property name*any

Arbitrary key-value metadata from the external system (e.g. task name, project code). Stored as-is and returned on reads.

Time entry already existed (idempotent replay). created is false in the response body.

Schema

iduuidrequired
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
organizationIduuidrequired
Example: 7b1e2c3d-0000-0000-0000-000000000001
projectIduuidrequired
Example: 9a8b7c6d-0000-0000-0000-000000000002
userIduuidrequired
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
entryIduuidnullablerequired
Example: null
workDatestringrequired
Example: 2025-01-15
hoursstringrequired
Example: 2.5
minutesintegerrequired
Example: 150
notesstring | nullnullablerequired
Example: Sprint planning session.
billablebooleanrequired
Example: true
sourcestringrequired
Example: illumera
statusstringrequired
Possible values: [draft, submitted, approved, rejected, locked, invoiced]
Example: draft
invoicedbooleanrequired
Example: false
createdAtdate-timerequired
Example: 2025-01-15T08:00:00Z
updatedAtdate-timerequired
Example: 2025-01-15T10:30:00Z
integrationLinkIduuidrequired
UUID of the integration link that was created or matched for externalSystem + externalId.
Example: aa1b2c3d-0000-0000-0000-000000000099
createdbooleanrequired
True when a new time entry was created; false when the existing entry was returned (idempotent replay).
Example: true