Skip to content

Fields and values – naming fields and writing values in the REST API

The record and query operations of the REST API refer to fields and send or return values. This page describes how a field is named in a request, how values of each field type are written, and how a record looks in a response. It applies to all record operations and to queries.

1. At a glance

Topic Rule
Naming a field ID, technical name, storage name or display name of the field
Writing a value JSON value matching the field type; null empties the field
Reading a value Typed JSON value plus the field type in type
Unknown field 400 field_not_found

2. Naming a field

Wherever a request names a field – in fields of a write, in a query clause, in sort or in the field list of a query – nexxcite looks for it in this order:

Order Looks for Example Upper/lower case
1 The ID of the field "0d5c8e3a-7b21-4f9e-a6d0-3c4b5e6f7a81" –
2 The technical name "CustomerNumber" must match
3 The "Storage Name" (the column name) "CustNo" must match
4 Technical name or storage name "customernumber" ignored
5 The "Display Name" "Customer number" ignored

The first match wins.

  • A display name is only used when it belongs to exactly one field of the entity. If several fields have the same display name, the request fails with 400 field_ambiguous; the error text lists their technical names.
  • A field that is not found leads to 400 field_not_found, an empty field name to 400 field_missing.

Recommendation: Use the technical name or the storage name. Display names are changed more often and are not guaranteed to be unique. After renaming a field, check the systems that use the API (see Entities and fields).

3. Writing values

The value is converted to the type of the field.

Field type (type) Accepted JSON values Example
Text (String) A string. Other JSON values are stored as their JSON text. "ACME Ltd."
Integer (Int64) A whole number, or a string with a whole number 42, "42"
Double (Double) A number, or a string with a decimal point 1500.5, "1500.50"
Boolean (Boolean) true / false, a number (0 is false, everything else true), or the string "true" / "false" true
Guid (Guid) A string with an ID "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58"
Date (Date) An ISO 8601 date string "2026-03-04"
Date & Time (DateTime) An ISO 8601 date and time string "2026-03-04T14:30:00"
  • null empties the field.
  • Numbers in strings are read with a decimal point, independent of the language settings: "1500.50", not "1500,50".
  • An empty string is not accepted for number, yes/no, ID and date fields – use null.
  • A value that does not fit the type leads to 400 invalid_field_value, for example "abc" for an integer field or 1.5 for an integer field.
  • A text longer than the "Max Length" of a text field is cut off at the maximum length without an error.
  • Values are never evaluated as expressions. "[[sf(CurrentUserId)]]" is stored as this text.
  • A value for a field that the "Field Limits" of the API user do not allow to change is discarded without an error; the field keeps its value. Check the response if a value matters.

Note on date and time: Send date and time values without a time zone (2026-03-04T14:30:00), in the time the installation works with. nexxcite does not convert time zones for you.

4. How a record looks in a response

All record operations return records in the same form:

{
  "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13",
  "entityName": "Customer",
  "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58",
  "fields": [
    { "fieldDefId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "field": "RecId", "storageName": "RecId", "type": "Guid", "value": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58" },
    { "fieldDefId": "0d5c8e3a-7b21-4f9e-a6d0-3c4b5e6f7a81", "field": "CustomerNumber", "storageName": "CustNo", "type": "String", "value": "K-1001" },
    { "fieldDefId": "7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b", "field": "CreditLimit", "storageName": "CreditLimit", "type": "Double", "value": 25000 },
    { "fieldDefId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d", "field": "IsActive", "storageName": "IsActive", "type": "Boolean", "value": true },
    { "fieldDefId": "3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e", "field": "CustomerSince", "storageName": "CustomerSince", "type": "Date", "value": "2026-03-04T00:00:00" },
    { "fieldDefId": "4c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e8f", "field": "Remarks", "storageName": "Remarks", "type": "String", "value": null }
  ],
  "relationships": null
}
Property Meaning
entityDefId, entityName ID and technical name of the entity
entityRecId ID of the record
fields One entry per field of the entity – or per requested field of a query
fields[].fieldDefId, field, storageName ID, technical name and storage name of the field
fields[].type Field type: String, Int64, Double, Boolean, Guid, Date, DateTime
fields[].value The value, typed as in section 3; null when the field is empty – for a date field also when it holds no date. Date fields are returned with the time 00:00:00, for example "2026-03-04T00:00:00".
relationships Related records, only when requested when reading a record (see Read a record); otherwise null

The fields every entity has (record ID, created and changed information) are part of the list like any other field.