Skip to content

Update a record – POST /api/v1/records/{entityId}/{recordId}

Changes field values of an existing record. Only the fields you send are changed; all others keep their values. The change goes through the same business logic as a change in a form. This page is the reference for the operation.

1. At a glance
Purpose Change one existing record
Method and path POST /api/v1/records/{entityId}/{recordId} – there is no PUT or PATCH
Typical use Update the status of an order, write back a result from another system
Permissions Valid token. The record must lie within the "Read Limits" of the API user, and the "Edit Limits" must admit the change.
Success 200 OK, the saved record in the body
Related Create a record, Read a record, Fields and values

2. Request

Path parameters

Parameter Meaning Required
entityId ID of the entity Yes
recordId ID of the record (its "RecId") Yes

Body

The same as for creating a record:

{
  "fields": [
    { "field": "Status", "value": "Shipped" },
    { "field": "ShippedOn", "value": "2026-10-20" }
  ]
}
Property Meaning Default
fields List of field values, applied in this order empty list
fields[].field The field (see Fields and values) required
fields[].value The new value; null empties the field null

3. Response

200 OK with the record as it was saved, in the form described in Fields and values:

{
  "entityDefId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "entityName": "Order",
  "entityRecId": "e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9",
  "fields": [
    { "fieldDefId": "a0b1c2d3-e4f5-4a6b-9c7d-8e9f0a1b2c3d", "field": "Status", "storageName": "Status", "type": "String", "value": "Shipped" },
    { "fieldDefId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5f", "field": "ShippedOn", "storageName": "ShippedOn", "type": "Date", "value": "2026-10-20T00:00:00" },
    { "fieldDefId": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f", "field": "LastModifiedAt", "storageName": "LastModifiedAt", "type": "DateTime", "value": "2026-10-20T10:02:11" }
  ],
  "relationships": null
}

4. Behaviour

  1. The record is read with the "Read Limits" of the API user. A record outside them is reported as 404 record_not_found – exactly as if it did not exist.
  2. The record is opened as in a form: rules that run when a record is opened run.
  3. Before the first value is changed, the "Edit Limits" are checked. If they do not admit the change: 403 forbidden ("You are not allowed to edit this record."). Nothing is changed.
  4. The values are applied one after another, in the order of fields, with the same rules as when creating a record: calculation rules run after each value, and a value that a validation rule rejects is replaced by the previous value without failing the request – unless the previous value is rejected as well; the field then stays invalid and the save fails with 422 record_not_saved.
  5. The record is saved. Required fields and rules that run before saving can still stop the save (422 record_not_saved).

A value that equals the stored value is not a change and does not trigger rules. The edit limits are checked with the first value of the request in any case.

Two systems change the same record

There is no locking and no version check. If two requests change the same record at the same time, the request that saves last determines the stored values of the fields it changed.

5. Status and error codes

HTTP status error Cause
200 – The record was saved
400 field_missing, field_not_found, field_ambiguous A field could not be identified
400 invalid_field_value A value does not fit the type of its field
400 field_without_type The field has no field type and cannot be written
401 – No valid token
403 forbidden The edit limits do not admit the change
404 entity_not_found No entity with this ID
404 record_not_found No record with this ID, or not within the read limits
422 record_not_saved Required fields missing, a field invalid, or a rule stopped the save
500 server_error, query_failed Unexpected error, see Errors

6. Example

curl -X POST https://nexxcite.example.com/api/v1/records/b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e/e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [ { "field": "Status", "value": "Shipped" }, { "field": "ShippedOn", "value": "2026-10-20" } ] }'

Emptying a field:

{ "fields": [ { "field": "BlockedReason", "value": null } ] }

7. Limitations

  • There is no "create or update" in one request. To update a record by a key of your own (for example a customer number), first find its ID with a query.
  • No check whether the record was changed by someone else in the meantime (section 4).
  • Related records and files cannot be changed with the record.