SaveDataField

Sets the values and remarks of data fields: the fields your company adds to records such as bills, invoices and assets, which users fill in on the record’s Data tab. One request sets one or more fields of one record. For the events and data fields of work orders, use SaveSeqData instead.

How to sign in and read the response: Authentication, Responses.

POST /api/v1/SaveDataField
Token: your-token
Content-Type: application/json

{
  "Ref": "bill",
  "RefID": 109827,
  "Fields": [
    { "Code": "COSTCTR", "Value": "CC-410", "Remarks": "" },
    { "Code": "PAYDUE", "Value": "2026-10-30T00:00:00" }
  ]
}

Field	Required	Meaning
Ref	Yes	The kind of record, from the table below. Not case-sensitive.
RefID	Yes	The record’s ID, a whole number.
Fields	Yes	The fields to set: an array of at least one entry.

Each entry of Fields:

Field	Required	Meaning
Code	Yes	The data field’s code, as on the Data Field Definitions page. Not case-sensitive.
Value	Yes	The new value, as text: see Values. It cannot be empty or null: this endpoint does not clear a value.
Remarks	No; yes for an asset	The remarks. An empty string clears them. Left out, the remarks stay as they are, except on an asset, where you must always send Remarks.

TrakIT reads these fields by name, so the names are case-sensitive: Ref, RefID, Fields, Code, Value and Remarks, exactly as written here.

Records

Ref	The record, and when its fields can be set	Its data fields
asset	An active asset.	Assets, shown on the Asset Data tab
bill	A bill that is not finalised.	Bills, shown on the Data tab
invoice	An invoice that is not approved.	Invoices, shown on the Data tab
receipt	A receipt that is not finalised.	Receipts, shown on the Data tab
payment	A payment that is not finalised.	Payments, shown on the Data tab
quotation	A quotation in Draft or Under Revision.	Quotations, shown on the Data tab
location	A location.	Locations, shown on the Data tab
yardmove	A yard move that is not executed yet.	Yard Moves: only the fields set up for [ All Move Types ], shown on the Data tab

For a record of a company, only the fields for that company can be set. Use receipt for a receipt and payment for a payment: each has its own fields.

Values

Data type	Send
Number	A number, with . for decimals. TrakIT rounds it to the field’s Decimal Precision.
Date	The date and time in UTC, as yyyy-MM-ddTHH:mm:ss, without a time zone suffix. TrakIT keeps the minutes. See Dates.
Text	Any text, or for a field with an item list, an item of the list. For several items, separate them with line breaks (\n).
Hyperlink	A web address. TrakIT adds http:// when it has no scheme.
Phone	Up to 15 characters: digits, an optional leading +, and an area code in brackets if needed.
Entity	The name, code or registration number of an entity of the field’s Entity Type. If no entity matches it exactly, TrakIT takes the first entity whose name or code contains it, so send a value that matches one entity exactly. TrakIT stores the text you send: send the entity’s name as TrakIT shows it.

Computed fields cannot be set: TrakIT works them out.

Rules

TrakIT first checks the request and the record:

Rule	Info when it fails
The body is a JSON object.	Payload is missing
Ref is given.	Parameter Ref is missing
RefID is given, as a number.	Parameter RefID is missing, Parameter RefID must be a number
Fields is given, with at least one entry.	Parameter Fields is missing, No field data found
An asset exists and is active.	No such asset, Asset not active
A bill exists and is not finalised.	No such bill, Bill is finalised
A receipt or a payment exists and is not finalised.	No such receipt, No such payment, Transaction is finalised
A location exists.	No such location
An invoice exists and is not approved.	No such invoice, Invoice is approved
A quotation exists and is in Draft or Under Revision.	No such quotation, Quotation data cannot be changed
A yard move exists and is not executed.	No such move, Move is already executed

With any other Ref, every field comes back Code not found.

Then TrakIT checks and saves each field on its own, in the order sent. A field that fails does not stop the others. Its Result in the response is one of these:

Rule	Field Result when it fails
The entry has a Code and a Value.	Code is missing (the result’s Code is then -), Value Field is missing
The record has a data field with this code.	Code not found
The field is active.	Field is not Active; for an asset, Code/Field is not Active
The value is not null, and for an asset not empty.	Invalid Value
The field is not computed.	Field is a computed field; for an asset, Update to Computed Fields is not allowed
A date is a date.	Invalid Date; for an asset, Invalid Date/Time
A field with an item list gets items of the list, no more than the field allows.	Value does not belong to the list of items, Value not from list, Value '...' not from list, Max ... items only
A number is numeric, of at most 18 characters.	Value must be numeric, Value too big; for an asset, Invalid value, Value too big!
An amount is numeric.	Value must be numeric.
An entity is found.	Entity ID missing
A hyperlink is a valid web address.	Data specified is not a valid URL
A phone number has at most 15 characters, of the form above.	Phone number is too long, Not a phone number
Other text does not start with =, + or @, and has no < followed by a letter.	Value has possible html tags or disallowed text
The value matches the field’s pattern, if TrakIT Support set one.	Validation: ..., with the pattern’s description
The value passes the field’s check, if TrakIT Support set one. Not for assets.	The check’s own message, or SQL Validation Error. Please contact Support.
A Unique field’s value is not used on another record. Not for assets.	Value already exists
The remarks have at most 5,000 characters (2,000 for an asset), and do not start with =, + or @ or have < followed by a letter.	Remarks cannot exceed 5000 characters., Remarks has possible html tags Or disallowed text; for an asset, Remarks cannot exceed 2000 characters., Remarks has possible html tags or disallowed text
The custom validations that TrakIT Support may set for Data Fields > Update pass. Not for assets. See Validations & actions.	The validation’s own message
The value or the remarks differ from what is saved.	No Change

Response

When the record passes its checks, Code is 1, whatever happened to each field. RetInfo has one result for each entry of Fields, in the order sent. For records other than assets, RowsAffected is the number of fields saved; for an asset it is always 0, so count the Success results instead. Identity and Scalar are not used.

{
  "Code": 1,
  "Info": "",
  "RetInfo": [
    { "Code": "COSTCTR", "Result": "Success" },
    { "Code": "PAYDUE", "Result": "No Change" }
  ],
  "RowsAffected": 1,
  "Scalar": null,
  "Identity": 0
}

Field	Meaning
Code	The field’s code.
Result	Success when the field was saved, No Change when the value and remarks were already saved, or why it was not saved, from the rules.

Notes

• After the fields are saved, TrakIT recalculates the record’s computed data fields.
• For records other than assets, the custom actions that TrakIT Support may set for Data Fields > Update run after each field saved.
• Values saved here are not copied to work orders, even for asset and yard move fields set to copy them.
• Sending the same fields again returns No Change and changes nothing, so a retry is safe.