# Create or update time management entry records (upsert)

**Create or update time management entry records (upsert)**
Records are created if they don't exist, or updated if matched by top-level `systemRef`.
Maximum 100 records per request.
### TimeEntry — linking a project task
Use the optional `taskId` attribute to associate a time entry with a project task.
Accepts a systemRef (`{ "system": "PM", "reference": "<task-pmsRef>" }`), a numeric
Aiwyn id, or a string numeric id (treated as Aiwyn id).
When `taskId` is set and no work code is supplied, the work code is derived from the
linked task's task type (same behavior as the firm portal UI).
### TimeEntry — work code (`code` attribute)
`code` is the **work code** (stored as `entry_code_id`), not the task. It must match
the exact `time_management_entry_code.code` value, or fall back to `task_type.code`.
When both `taskId` and `code` are provided, the explicit `code` wins.
### Resolving task references
Look up tasks before upserting entries:
- `GET /v1/task/{id}` — get a task by Aiwyn id
- `POST /v1/tasks/search` — search tasks (filter by job, assignee, task type, dates)
See `GET /api/v1/entries/schema/TimeEntry` for the full attribute list.
### Example — TimeEntry with project task
`json             {               "records": [                 {                   "type": "TimeEntry",                   "systemRef": {"system": "PM", "reference": "beeye-entry-001"},                   "attributes": {                     "pmsRef": "beeye-entry-001",                     "loggedDate": "2026-06-17T09:00:00",                     "value": 2.5,                     "billable": true,                     "notes": "Worked on tax planning deliverable",                     "clientId": {"system": "PM", "reference": "37584"},                     "jobId": {"system": "PM", "reference": "AIWYN_29059"},                     "loggedStaffId": {"system": "PM", "reference": "12345"},                     "taskId": {"system": "PM", "reference": "AIWYN_98765"}                   }                 }               ]             }             `
### Example — TimeEntry with task and explicit work code
`json             {               "records": [                 {                   "type": "TimeEntry",                   "systemRef": {"system": "PM", "reference": "beeye-entry-002"},                   "attributes": {                     "pmsRef": "beeye-entry-002",                     "loggedDate": "2026-06-17T14:00:00",                     "value": 1.0,                     "clientId": {"system": "PM", "reference": "37584"},                     "jobId": {"system": "PM", "reference": "AIWYN_29059"},                     "loggedStaffId": {"system": "PM", "reference": "12345"},                     "taskId": {"system": "PM", "reference": "AIWYN_98765"},                     "code": "TXBLE30X01"                   }                 }               ]             }             `
**Business Applications:**
- Sync time entries from external time-tracking systems
- Attach project tasks to time entries
- Upsert entries by external system reference

**Real Example:**

```bash
curl --location 'https://{{host}}/api/v1/entries' \
--header 'Authorization: bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "records": [
    {
      "type": "TimeEntry",
      "systemRef": {"system": "PM", "reference": "beeye-entry-001"},
      "attributes": {
        "pmsRef": "beeye-entry-001",
        "loggedDate": "2026-06-17T09:00:00",
        "value": 2.5,
        "billable": true,
        "notes": "Worked on tax planning deliverable",
        "clientId": {"system": "PM", "reference": "37584"},
        "jobId": {"system": "PM", "reference": "AIWYN_29059"},
        "loggedStaffId": {"system": "PM", "reference": "12345"},
        "taskId": {"system": "PM", "reference": "AIWYN_98765"}
      }
    }
  ]
}'
```

Endpoint: POST /api/v1/entries
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `records` (array, required)
    Records

  - `records.type` (string)
    Type

  - `records.systemRef` (object)
    Systemref

  - `records.attributes` (object)
    Attributes

## Response 200 fields (application/json):

  - `data` (object)

  - `data.summary` (object)
    Summary

  - `data.records` (array)
    Records

  - `error` (object)

  - `meta` (object)

  - `meta.success` (boolean)

  - `meta.message` (string)

  - `meta.timestamp` (string)

  - `meta.version` (string)