Proposed changes

Send Jobs, Phase Codes and equipment for an administrator to approve before they go live. A proposal does not change live data. It waits on the admin site until an administrator publishes or declines it. If the company publishes incoming changes automatically (auto-publish), the proposal goes live in the same request.

Use this endpoint instead of the direct write endpoints when your company wants a person to check every change first.

Do not mix proposals and direct writes for the same codes. A published proposal is owned by timecard. A proposal that would change a record that another source system owns is refused with a message that starts owned_by:<owner>. This includes records that your own key wrote directly. A proposal that changes nothing on such a record reads matches_current.

Back to the index · Conventions · Errors

POST /reference-changes

Sends up to 1,000 proposed records for one company. Each record is checked on its own, so one refused record never stops the others. The response has one result per record, in the order sent.

Scope: reference-changes:write. The key must also have a source system. It is recorded as the proposal's origin.

Order of work. Jobs are handled first, then Phase Codes, then equipment. A phase_code can name a Job that is sent earlier in the same request.

Field rules. A field that you leave out keeps the record's current value. A blank string clears a text field. isActive defaults to true.

Request body

A job record

A phase_code record

An equipment record

Example request

curl -X POST "$TIMECARD_BASE_URL/reference-changes" \
  -H "X-API-Key: $TIMECARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyCode": "ACME",
    "dryRun": false,
    "changes": [
      { "entity": "job", "jobCode": "J-2026-120", "name": "Lakeline Parking Lot", "divisionCode": "PAVING" },
      { "entity": "phase_code", "jobCode": "J-2026-120", "phaseCode": "01-100", "description": "Mobilization" },
      { "entity": "equipment", "equipmentCode": "RL-14", "divisionCode": "YARD" }
    ]
  }'

Example response 200 OK

{
  "status": 200,
  "message": "Success: ACME: 2 staged, 0 published, 0 unchanged, 0 already current, 1 refused.",
  "record": {
    "dryRun": false,
    "autoPublished": false,
    "results": [
      {
        "index": 1,
        "entity": "job",
        "key": "J-2026-120",
        "outcome": "staged",
        "changeId": 7311
      },
      {
        "index": 2,
        "entity": "phase_code",
        "key": "J-2026-120/01-100",
        "outcome": "staged",
        "changeId": 7312
      },
      {
        "index": 3,
        "entity": "equipment",
        "key": "RL-14",
        "outcome": "refused",
        "message": "divisionCode YARD is not an active division of ACME."
      }
    ],
    "counts": {
      "staged": 2,
      "unchanged": 0,
      "matchesCurrent": 0,
      "published": 0,
      "refused": 1
    }
  }
}

On a dry run, the message starts Success: dry run, nothing was saved:. Do not parse the message text. It can change.

Outcomes

On a dry run, a record that would be staged reads staged, even when autoPublished is true.

Response fields

Why a record is refused

• It is not valid.
• A divisionCode is not an active division of the company. The message names the code.
• The current record belongs to another source system, and the proposal would change it. The message starts owned_by:<owner>.
• A Job code is already held by a Work Order or a Meet Point.
• Existing equipment has a different divisionCode.
• A Phase Code's Job is not in Matrix TimeCard, not in this request and not proposed.

Records that another source system owns

A proposal for such a record is compared with what Matrix TimeCard shows, with an administrator's changes applied. Text is compared without surrounding spaces, and a blank value is equal to null. If nothing would change, the outcome is matches_current and nothing is staged. So you can send the current values back without a refusal. When an equipment code is in more than one division, the proposal is compared with the record of its own divisionCode.

Errors