Writing data

Create, update and delete records in the connected system, or run its actions, through one API. You write in the same shape you read, reference related records by name or id, and see exactly what was done in the connected system.

Request

Response

Entities that support writes have create, update, delete and action endpoints. Which ones exist depends on the entity, and the connected system decides which of them it supports. Each platform's Supported data page lists its writes.

Write and poll for the result

Writes are asynchronous. A write is validated, its references are resolved against the data synced for the connection, and then it is queued. You learn the outcome from the write record.

Get a write token

Writes need a connection-scoped token with the connection:data:write scope. A plain client_credentials token is a 403, and so is a connection that has been revoked, deactivated or deleted. See Access tokens.

Send the write

The answer is 202 with {writeId, status: "pending"}. If the write cannot be queued, the answer is a 502, never an optimistic 202.

Send an Idempotency-Key with every write. Then a 502 is safe to retry with the same key: a write that did get queued is not queued twice.

Poll the write record

Poll GET /v4/writes/{writeId} for the outcome. status moves from pending (queued) to running (sent to the connected system) and ends as succeeded, partial or failed.

Reading a write record needs the same connection:data:write scope as the write itself. A writeId that isn't a UUID is a 400, and one from another connection is a 404.

Read the outcome

{
  "writeId": "3f9c2a71-8e4b-4d15-9a06-7b1e2c3d4f58",
  "operation": "work-orders:create",
  "status": "succeeded",
  "synced": true,
  "result": {
    "id": "0192f4b7-1d2e-7c3f-8a4b-5c6d7e8f9a0b",
    "record": { "id": "0192f4b7-1d2e-7c3f-8a4b-5c6d7e8f9a0b", "title": "Replace conveyor belt" }
  },
  "resolvedRefs": [
    { "field": "asset", "given": { "_displayValue": "Pump 3" }, "matchedOn": "_displayValue" }
  ],
  "steps": [{ "n": 1, "kind": "call", "status": "succeeded" }]
}

result.id is the Makini id of the written record. Once synced is true, result.record is the record in the same shape the entity's read endpoint returns. Before that, it is the connected system's own copy of the record.

steps[] is what was done in the connected system.

leftovers[] is what a partial write left behind there.

resolvedRefs[] is what each reference in your request resolved to.

error is the error body on failure (see Errors).

Build the request body

A write body follows the read format: the same field names, nesting and types the entity's read endpoint returns. Of the envelope fields, only code and customFields are writable. The derived fields are left out too: statusCategory, lifecyclePhase, priorityLevel, operationalStatus, isCompleted and itemCount. Setting a derived field is a 422 with MAKINI_FIELD_READ_ONLY, and an unknown field is a 400.

Create

Update

Action

Delete

POST /v4/<entity> takes every writable field. Where an endpoint allows it, a batch is {items: [...]} with up to 100 creates, queued as one write.

The {id} in an update, action or delete path is the record's Makini id.

A relation in a write body is a reference object with exactly one of these keys:

Key	Matches
`id`	The Makini id
`_idValue`	The connected system's own id. It is passed through unverified.
`_displayValue`	The display name among live records

A _displayValue is matched exactly first, then ignoring case and whitespace. A polymorphic relation also needs rel, the entity it points at. A many-relation is an array of references. A bare string where a reference belongs is a 400.

Reasons on an action

Actions such as hold, cancel, reject and complete take a reason. Some systems have a list of reasons to pick from and some keep the reason as text; you send the same thing either way:

{ "reason": { "_displayValue": "Waiting for parts" } }

When the connected system has a reason list, the name is matched against that list. The list is in GET /v4/taxonomies?filter[type]=action-reason; each row's category is the action it belongs to. A name that isn't on the list is a 422 with MAKINI_REF_NOT_FOUND.

When it has no list, the text is stored as written.

A work order's reason reads back as reasonText, and as the reason link when it came from a list.

Retry safely

Send an Idempotency-Key header (up to 128 characters). A repeat with the same key within 24 hours answers 200 with the full write record, the same body GET /v4/writes/{writeId} returns, instead of queueing it again. A repeat with the same key and a different body is a 409 with MAKINI_CONFLICT.

Reference

Errors

Limits

Next steps

Errors

Every error code, and which ones to retry.

Reading data

The record shape a write body follows.

Relations and expand

How relations look when you read them back.

Access tokens

Get the connection-scoped token writes need.

Write and poll for the result#

Build the request body#

Point at related records#

Reasons on an action#

Retry safely#

Reference#

Next steps#

Write and poll for the result

Build the request body

Point at related records

Reasons on an action

Retry safely

Reference

Next steps