{entityId}¶

Creates a new record of an entity and sets the field values you send. The record goes through the same business logic as a record created in a form. This page is the reference for the operation.

1. At a glance¶


Purpose	Create one record of an entity
Method and path	`POST /api/v1/records/{entityId}`
Typical use	Import a customer from an ERP, create a ticket from a monitoring system
Permissions	Valid token. The "Add Limits" of the API user apply; edit limits do not.
Success	`201 Created`, the new record in the body, its address in the `Location` header
Related	Update a record, Fields and values

2. Request¶

Path parameters¶

Parameter	Meaning	Required
`entityId`	ID of the entity ("Copy ID" in the management view of the entities)	Yes

Body¶

{
  "fields": [
    { "field": "CustomerNumber", "value": "K-1001" },
    { "field": "Name",           "value": "ACME Ltd." },
    { "field": "CreditLimit",    "value": 25000 },
    { "field": "IsActive",       "value": true }
  ]
}

Property	Meaning	Default
`fields`	List of field values, applied in this order	empty list
`fields[].field`	The field – ID, technical name, storage name or display name (see Fields and values)	required
`fields[].value`	The value, matching the field type; `null` empties the field	`null`

The record ID does not have to be sent; nexxcite creates it, as in a form.

3. Response¶

201 Created, with the header Location: /api/v1/records/{entityId}/{recordId} and the saved record in the body:

{
  "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": "5d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f9a", "field": "Name", "storageName": "Name", "type": "String", "value": "ACME Ltd." },
    { "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": "8f9a0b1c-2d3e-4f4a-8b5c-6d7e8f9a0b1c", "field": "CreatedAt", "storageName": "CreatedAt", "type": "DateTime", "value": "2026-10-20T09:15:42" }
  ],
  "relationships": null
}

The response shows the record as it was saved – including the values that business rules calculated. Compare it with what you sent (see section 4).

4. Behaviour¶

nexxcite checks the "Add Limits" of the API user. If they do not admit a new record, the request ends with 403 forbidden.
A new record is prepared exactly as in a form: default value rules fill the record ID, the creation time and other defaults.
The values are applied one after another, in the order of fields. After each value the rules that react to the field run – calculation rules, validations and so on.
The record is saved. Rules that run before saving may still stop the save; required fields are checked.
Rules that run after saving – for example background actions – are started as for a save in a form.

Order of the values¶

The order matters when rules build on each other. Example: A calculation rule fills "Name" from "CustomerNumber" when "CustomerNumber" changes. If you send "Name" first and "CustomerNumber" second, the rule overwrites your "Name". Send "CustomerNumber" first and "Name" second to keep your value.

Values that a validation rule rejects¶

When a validation rule rejects a value, nexxcite puts the previous value back – for a new record the empty or default value – and continues with the next value. The request does not fail because of this as long as the previous value is one the rules accept. Check the response if a value matters. If the previous value is rejected as well (a stored value from before a rule was tightened), the field stays marked as invalid and the save fails with 422 record_not_saved, naming the field in validationErrors.

What stops the save¶

Cause	Result
A field marked as required has no value	`422 record_not_saved`, the fields in `requiredFields`
A rule that runs before saving reports an error	`422 record_not_saved`, the reason in `errorDescription`
A field is still marked as invalid when saving	`422 record_not_saved`, the fields in `validationErrors`

{
  "error": "record_not_saved",
  "errorDescription": "Could not save the record",
  "validationErrors": null,
  "requiredFields": [
    {
      "entityDefId": "6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13",
      "entityRecId": "9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58",
      "relationshipId": null,
      "fields": [ { "fieldDefId": "5d6e7f8a-9b0c-4d1e-8f2a-4b5c6d7e8f9a", "field": "Name" } ]
    }
  ]
}

Nothing is saved when the request fails.

5. Status and error codes¶

HTTP status	`error`	Cause
201	–	The record was created
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 add limits do not admit a new record
404	`entity_not_found`	No entity with this ID
422	`record_not_saved`	Required fields missing, or a rule stopped the save
500	`server_error`, `query_failed`	Unexpected error, see Errors

6. Example¶

curl -i -X POST https://nexxcite.example.com/api/v1/records/6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          { "field": "CustomerNumber", "value": "K-1001" },
          { "field": "Name", "value": "ACME Ltd." },
          { "field": "CreditLimit", "value": "25000.00" },
          { "field": "CustomerSince", "value": "2026-03-04" }
        ]
      }'

HTTP/1.1 201 Created
Location: /api/v1/records/6a1f0c52-3d4e-4b8a-9c71-2f5e8d0b4a13/9b7e2d41-0c5a-4f36-8e12-7d3a6b9c0f58
Content-Type: application/json; charset=utf-8

7. Limitations¶

One record per request. Several requests are not a transaction: if the third of five creates fails, the first two stay.
Related records cannot be created together with the record. Create them with their own request and a field that links them to the parent record.
Files cannot be attached.
A value rejected by a validation rule does not make the request fail (section 4).