PUT/api/v1/object/field/{objectSlug}/order

Change the order of an object's fields.

Send each field's slug with its new sort_order. Fields you leave out keep their place. The field named name always stays first at 0; any other field sent with 0 gets 1. A field shared into this object is reordered on this object only. The whole list is checked before anything is saved. Returns the object's fields in their new order.

Scope: object.update.

Errors:

400 — a slug is not a field of this object, or no active object has that slug.
422 — the body is invalid, for example a sort_order that is not a number.

Request:

{
  "fields": [
    { "slug": "phone-q8w2e4r6", "sort_order": 1 },
    { "slug": "stage-k2j9h4g7", "sort_order": 2 }
  ]
}

Response 200:

{
  "status": 200,
  "message": "Field order updated successfully",
  "data": [
    {
      "id": 912,
      "name": "stage",
      "slug": "stage-k2j9h4g7",
      "label": "Stage",
      "icon": null,
      "type": "select",
      "required": false,
      "default_value": null,
      "options": {
        "values": [
          {
            "id": "6a1f3c9e-2b7d-4e8a-9f0c-1d2e3f4a5b6c",
            "value": "lead",
            "label": "Lead",
            "color": "#3B82F6"
          }
        ]
      },
      "is_active": true,
      "sort_order": 2,
      "group_slug": null,
      "group_ineligible": false,
      "is_system": false,
      "api_only": false,
      "is_shared": false,
      "shared_with": [],
      "is_visible": true,
      "created_at": "2026-08-02T08:30:00.000Z",
      "updated_at": "2026-09-01T11:15:00.000Z"
    }
  ]
}

Send request

Use the documented inputs to call this endpoint directly.

API serverbase URL

Bearer tokenbearerAuthoptional

Stored only in this browser for the bearerAuth security scheme and reused on every API page in this group.

Parameters

Values are applied to the request and the example on the right.

objectSlugpath · stringrequired

Request body

application/jsonrequired

fieldsarray<object>required

Responses

200application/json

Successful response

{
  "id": 1.5,
  "name": "string",
  "slug": "string",
  "label": "string",
  "icon": "string",
  "type": "string",
  "required": true,
  "default_value": "string",
  "options": "string",
  "is_active": true,
  "sort_order": 1.5,
  "group_slug": "string",
  "group_ineligible": true,
  "is_system": true,
  "api_only": true,
  "is_shared": true,
  "shared_with": "string",
  "is_visible": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

idnumberrequired

namestringrequired

slugstringrequired

labelstringrequired

iconobjectrequired

typestringrequired

requiredbooleanrequired

default_valueobjectrequired

optionsobjectrequired

Archived (deleted-but-still-referenced) options are stripped — see FieldResponseDto.

is_activebooleanrequired

sort_ordernumberrequired

Order within the field's section — and, for a section-less field, within the flat list. For a placed (shared) field this is the placement's position on THIS Unit, not the home definition's order. Same currency as PUT /object/field/order and as positions[] on the section assign call.

group_slugobjectrequired

The field's section on THIS Unit (FRD-34); null ⇒ the implicit "Ungrouped" bucket, which renders last. null on paths that skip stampSections (nothing grouped, or a write-echo response), so the key is always present on the wire.

group_ineligiblebooleanrequired

FRD-34 — this field can never be moved into a section: the record shell renders it (title, assignee, meta block, status/tag chrome) or it is system-defined. Derived on read rather than stored, so it is right for objects seeded before sections existed and on the write-echo responses.

is_systembooleanrequired

api_onlybooleanrequired

Value-write lock — drives the "API only" toggle's state in field settings.

is_sharedbooleanrequired

CFM-2: is_shared/shared_with are computed by FieldQueryService.mergeWithPlacedFields but were stripped here. false/[] on paths that skip the merge (e.g. findBySlug).

shared_withobjectrequired

is_visiblebooleanrequired

Per-Unit visibility of a placed (shared) field on THIS Unit — set by mergeWithPlacedFields from the placement row. Own fields (and paths that skip the merge) default to true; their on/off switch is is_active.

created_atstring · date-timerequired

updated_atstring · date-timerequired

400application/json

Bad request

{
  "status": 1,
  "message": "string",
  "code": "string",
  "data": {}
}

statusintegerrequired

The HTTP status code of the response.

messagestringrequired

What went wrong. Several validation messages are joined with ", ".

codestringoptional

A stable, machine-readable reason. Only some errors set it.

dataobjectoptional

Extra detail about the error. Only some errors set it.

401application/json

Unauthorized

{
  "status": 1,
  "message": "string",
  "code": "string",
  "data": {}
}

statusintegerrequired

The HTTP status code of the response.

messagestringrequired

What went wrong. Several validation messages are joined with ", ".

codestringoptional

A stable, machine-readable reason. Only some errors set it.

dataobjectoptional

Extra detail about the error. Only some errors set it.

500application/json

Internal server error

{
  "status": 1,
  "message": "string",
  "code": "string",
  "data": {}
}

statusintegerrequired

The HTTP status code of the response.

messagestringrequired

What went wrong. Several validation messages are joined with ", ".

codestringoptional

A stable, machine-readable reason. Only some errors set it.

dataobjectoptional

Extra detail about the error. Only some errors set it.