Customers

Download schema

Customer entity CRUD and metadata endpoints

Get customer UI metadata

GET

http://localhost:3001

/api/v1/entities/customer/meta

Bearer (JWT)

X-API-Key (header)

Get customer UI metadata › Responses

200

EntityMetaResponse

entity

string · required

Entity key, snake_case singular

translation_key

string · required

snake_case singular i18n prefix

uid

string · required

Column key used as row identity (e.g. uuid)

display_field

string · required

Key of the primary display column

display_name

string · required

Display template (${field} syntax). Defaults to "${display_field}" — materialized by assembleMeta

object[] · required

Root-level field dictionary, transversal to all page types

object[] · required

Derived capability contract — full standard op vocabulary, enabled:false when the route is absent or product-disabled

title_key

string

Optional i18n key overriding the canonical page title (absent → built from system.entities.page_title.* templates)

object

Per-op enabled toggles — may only affect existing ops, never invent them

object

EntityListTable options — absent on form-only metas (e.g. /auth/me/meta)

object

Injected by assembleMeta from entity auditability

GET/api/v1/entities/customer/meta

fetch('http://localhost:3001/api/v1/entities/customer/meta', {
  headers: {
    Authorization: 'Bearer <token>'
  }
})

Example Responses

{
  "entity": "entity",
  "translation_key": "translation_key",
  "title_key": "title_key",
  "uid": "uid",
  "display_field": "display_field",
  "display_name": "display_name",
  "actions_overrides": {
    "key": {
      "enabled": true
    }
  },
  "columns": [
    {
      "key": "key",
      "label_key": "label_key",
      "type": "text",
      "order": 0,
      "sticky": true,
      "audited": true,
      "sortable": true,
      "searchable": true,
      "hideable": true,
      "default_visible": true,
      "filterable": true,
      "badge": {
        "values": {
          "key": {
            "label_key": "label_key",
            "label_text": "label_text",
            "color": "color"
          }
        }
      },
      "datetime_iana_toggle": {
        "record_iana_field": "record_iana_field"
      },
      "tooltip": "tooltip",
      "tooltip_priority": "INFORMATION",
      "tooltip_title": "tooltip_title",
      "show_form_tooltip": true,
      "show_list_tooltip": true
    }
  ],
  "table": {
    "default_view": "table",
    "default_sort": {
      "key": "key",
      "dir": "asc"
    },
    "default_page_size": 0,
    "page_size_options": [
      0
    ],
    "row_custom_actions": [
      {
        "action_name": "action_name",
        "translation_key": "translation_key",
        "icon": "icon",
        "text_color": "text_color",
        "disabled_when_deleted": true,
        "required_permission": "required_permission"
      }
    ]
  },
  "actions": [
    {
      "op": "op",
      "enabled": true,
      "permissions": [
        "string"
      ],
      "sentinel": "_public",
      "endpoint": {
        "method": "method",
        "path": "path"
      }
    }
  ],
  "collaboration": {
    "enabled": true,
    "expose_editing_value": true
  }
}

json

application/json

List customers

GET

http://localhost:3001

/api/v1/entities/customer/list

Bearer (JWT)

X-API-Key (header)

List customers › query Parameters

search

string

search_in

string

CSV of fields to search in (e.g. code,uuid,email)

status

CustomerStatus · enum

Enum values:

ACTIVE

INACTIVE

sort_key

string · enum

Enum values:

updated_at

uuid

code

status

sort_dir

string · enum

Enum values:

asc

desc

page

integer · min: 1

page_size

integer · min: 1 · max: 100

object[]

Advanced filter conditions array

List customers › Responses

200

EntityListResponseCustomer

CustomerDetail[] · required

page

integer · required

page_size

integer · required

total

integer · required

GET/api/v1/entities/customer/list

fetch('http://localhost:3001/api/v1/entities/customer/list', {
  headers: {
    Authorization: 'Bearer <token>'
  }
})

Example Responses

{
  "rows": [
    {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "code": "code",
      "first_name": "first_name",
      "last_name": "last_name",
      "company_name": "company_name",
      "email": "test@example.com",
      "phone": "phone",
      "status": "ACTIVE",
      "status_reason": "status_reason",
      "local_address": "local_address",
      "local_city": "local_city",
      "local_state": "local_state",
      "local_country": "local_country",
      "local_zip": "local_zip",
      "onboarding_at": "2026-04-16T12:01:44.606Z",
      "onboarding_time_zone": "Europe/Rome",
      "created_at": "2026-04-16T12:01:44.606Z",
      "created_by": "created_by",
      "updated_at": "2026-04-16T12:01:44.606Z",
      "updated_by": "updated_by",
      "version": 0,
      "deleted_at": "2026-04-16T12:01:44.606Z",
      "deleted_by": "deleted_by"
    }
  ],
  "page": 0,
  "page_size": 0,
  "total": 0
}

json

application/json

Create customer

POST

http://localhost:3001

/api/v1/entities/customer

Bearer (JWT)

X-API-Key (header)

Create customer › Request Body

CustomerCreateBody

code

string · maxLength: 20 · required

first_name

string

last_name

string

company_name

string

email

string · email · maxLength: 320

phone

string · maxLength: 64

status

CustomerStatus · enum

Enum values:

ACTIVE

INACTIVE

status_reason

string

local_address

string

local_city

string

local_state

string

local_country

string

local_zip

string

onboarding_at

string · date-time

Onboarding instant (UTC in DB). Send ISO-8601; pair with onboarding_time_zone for display in that IANA zone.

onboarding_time_zone

string · maxLength: 100

IANA time zone id (e.g. Europe/Rome). Required if onboarding_at is set.

Example: Europe/Rome

Create customer › Responses

Created

CustomerCreateResponse

uuid

string · uuid · required

POST/api/v1/entities/customer

fetch('http://localhost:3001/api/v1/entities/customer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <token>'
  },
  body: JSON.stringify({
    code: 'code',
    first_name: 'first_name',
    last_name: 'last_name',
    company_name: 'company_name',
    email: 'test@example.com',
    phone: 'phone',
    status: 'ACTIVE',
    status_reason: 'status_reason',
    local_address: 'local_address',
    local_city: 'local_city',
    local_state: 'local_state',
    local_country: 'local_country',
    local_zip: 'local_zip',
    onboarding_at: '2024-08-25T15:00:00Z',
    onboarding_time_zone: 'Europe/Rome'
  })
})

Example Request Body

{
  "code": "code",
  "first_name": "first_name",
  "last_name": "last_name",
  "company_name": "company_name",
  "email": "test@example.com",
  "phone": "phone",
  "status": "ACTIVE",
  "status_reason": "status_reason",
  "local_address": "local_address",
  "local_city": "local_city",
  "local_state": "local_state",
  "local_country": "local_country",
  "local_zip": "local_zip",
  "onboarding_at": "2024-08-25T15:00:00Z",
  "onboarding_time_zone": "Europe/Rome"
}

json

Example Responses

{
  "uuid": "00000000-0000-0000-0000-000000000000"
}

json

application/json

Get customer detail

GET

http://localhost:3001

/api/v1/entities/customer/{uuid}

Bearer (JWT)

X-API-Key (header)

Get customer detail › path Parameters

uuid

string · uuid · required

Get customer detail › Responses

CustomerDetail

uuid

string · uuid · required

code

string · maxLength: 20 · required

status

CustomerStatus · enum · required

Enum values:

ACTIVE

INACTIVE

created_at

string · date-time · required

DateTime (instant). Serialized as RFC3339 / ISO-8601 string with timezone (Z or +/-HH:MM).

Example: 2026-04-16T12:01:44.606Z

created_by

string · required

updated_at

string · date-time · required

DateTime (instant). Serialized as RFC3339 / ISO-8601 string with timezone (Z or +/-HH:MM).

Example: 2026-04-16T12:01:44.606Z

updated_by

string · required

version

integer · required

first_name

string

last_name

string

company_name

string

email

string · email · maxLength: 320

phone

string · maxLength: 64

status_reason

string

local_address

string

local_city

string

local_state

string

local_country

string

local_zip

string

onboarding_at

string · date-time

Onboarding instant (stored as UTC / timestamptz). Use onboarding_time_zone with Intl in the UI for local wall time (incl. DST).

Example: 2026-04-16T12:01:44.606Z

onboarding_time_zone

string · maxLength: 100

IANA zone captured when onboarding was recorded.

Example: Europe/Rome

deleted_at

string · date-time

DateTime (instant). Serialized as RFC3339 / ISO-8601 string with timezone (Z or +/-HH:MM).

Example: 2026-04-16T12:01:44.606Z

deleted_by

string

GET/api/v1/entities/customer/{uuid}

fetch('http://localhost:3001/api/v1/entities/customer/:uuid', {
  headers: {
    Authorization: 'Bearer <token>'
  }
})

Example Responses

{
  "uuid": "00000000-0000-0000-0000-000000000000",
  "code": "code",
  "first_name": "first_name",
  "last_name": "last_name",
  "company_name": "company_name",
  "email": "test@example.com",
  "phone": "phone",
  "status": "ACTIVE",
  "status_reason": "status_reason",
  "local_address": "local_address",
  "local_city": "local_city",
  "local_state": "local_state",
  "local_country": "local_country",
  "local_zip": "local_zip",
  "onboarding_at": "2026-04-16T12:01:44.606Z",
  "onboarding_time_zone": "Europe/Rome",
  "created_at": "2026-04-16T12:01:44.606Z",
  "created_by": "created_by",
  "updated_at": "2026-04-16T12:01:44.606Z",
  "updated_by": "updated_by",
  "version": 0,
  "deleted_at": "2026-04-16T12:01:44.606Z",
  "deleted_by": "deleted_by"
}

json

application/json

Organizations

Get customer UI metadata

GET

http://localhost:3001

/api/v1/entities/customer/meta

Bearer (JWT)

X-API-Key (header)

Get customer UI metadata › Responses

200

EntityMetaResponse

entity

string · required

Entity key, snake_case singular

translation_key

string · required

snake_case singular i18n prefix

uid

string · required

Column key used as row identity (e.g. uuid)

display_field

string · required

Key of the primary display column

display_name

string · required

Display template (${field} syntax). Defaults to "${display_field}" — materialized by assembleMeta

object[] · required

Root-level field dictionary, transversal to all page types

object[] · required

Derived capability contract — full standard op vocabulary, enabled:false when the route is absent or product-disabled

title_key

string

Optional i18n key overriding the canonical page title (absent → built from system.entities.page_title.* templates)

object

Per-op enabled toggles — may only affect existing ops, never invent them

object

EntityListTable options — absent on form-only metas (e.g. /auth/me/meta)

object

Injected by assembleMeta from entity auditability

List customers

GET

http://localhost:3001

/api/v1/entities/customer/list

Bearer (JWT)

X-API-Key (header)

List customers › query Parameters

search

string

search_in

string

CSV of fields to search in (e.g. code,uuid,email)

status

CustomerStatus · enum

Enum values:

ACTIVE

INACTIVE

sort_key

string · enum

Enum values:

updated_at

uuid

code

status

sort_dir

string · enum

Enum values:

asc

desc

page

integer · min: 1

page_size

integer · min: 1 · max: 100

object[]

Advanced filter conditions array

List customers › Responses

200

EntityListResponseCustomer

CustomerDetail[] · required

page

integer · required

page_size

integer · required

total

integer · required

Create customer

POST

http://localhost:3001

/api/v1/entities/customer

Bearer (JWT)

X-API-Key (header)

Create customer › Request Body

CustomerCreateBody

code

string · maxLength: 20 · required

first_name

string

last_name

string

company_name

string

email

string · email · maxLength: 320

phone

string · maxLength: 64

status

CustomerStatus · enum

Enum values:

ACTIVE

INACTIVE

status_reason

string

local_address

string

local_city

string

local_state

string

local_country

string

local_zip

string

onboarding_at

string · date-time

Onboarding instant (UTC in DB). Send ISO-8601; pair with onboarding_time_zone for display in that IANA zone.

onboarding_time_zone

string · maxLength: 100

IANA time zone id (e.g. Europe/Rome). Required if onboarding_at is set.

Example: Europe/Rome

Create customer › Responses

Created

CustomerCreateResponse

uuid

string · uuid · required

Get customer detail

GET

http://localhost:3001

/api/v1/entities/customer/{uuid}

Bearer (JWT)

X-API-Key (header)

Get customer detail › path Parameters

uuid

string · uuid · required

Get customer detail › Responses

CustomerDetail

uuid

string · uuid · required

code

string · maxLength: 20 · required

status

CustomerStatus · enum · required

Enum values:

ACTIVE

INACTIVE

created_at

string · date-time · required

DateTime (instant). Serialized as RFC3339 / ISO-8601 string with timezone (Z or +/-HH:MM).

Example: 2026-04-16T12:01:44.606Z

created_by

string · required

updated_at

string · date-time · required

DateTime (instant). Serialized as RFC3339 / ISO-8601 string with timezone (Z or +/-HH:MM).

Example: 2026-04-16T12:01:44.606Z

updated_by

string · required

version

integer · required

first_name

string

last_name

string

company_name

string

email

string · email · maxLength: 320

phone

string · maxLength: 64

status_reason

string

local_address

string

local_city

string

local_state

string

local_country

string

local_zip

string

onboarding_at

string · date-time

Onboarding instant (stored as UTC / timestamptz). Use onboarding_time_zone with Intl in the UI for local wall time (incl. DST).

Example: 2026-04-16T12:01:44.606Z

onboarding_time_zone

string · maxLength: 100

IANA zone captured when onboarding was recorded.

Example: Europe/Rome

deleted_at

string · date-time

DateTime (instant). Serialized as RFC3339 / ISO-8601 string with timezone (Z or +/-HH:MM).

Example: 2026-04-16T12:01:44.606Z

deleted_by

string