Customers

Download schema

Customer entity CRUD and metadata endpoints

Get customer UI metadata

GET

/api/v1/entities/customer/meta

Get customer UI metadata › Responses

200

EntityMetaResponse

entity

string · required

titleKey

string · required

uid

string · required

List row unique identifier column key (e.g. uuid)

defaultView

string · enum · required

Enum values:

table

cards

cards_list

object · required

GET/api/v1/entities/customer/meta

fetch('/api/v1/entities/customer/meta')

Example Responses

{
  "entity": "entity",
  "titleKey": "titleKey",
  "uid": "uid",
  "defaultView": "table",
  "list": {
    "searchPlaceholderKey": "searchPlaceholderKey",
    "defaultSort": {
      "key": "key",
      "dir": "asc"
    },
    "columns": [
      {
        "key": "key",
        "labelKey": "labelKey",
        "type": "type",
        "sortable": true,
        "searchable": true,
        "hideable": true,
        "defaultVisible": true,
        "filterable": true,
        "formDescription": "formDescription",
        "listDescription": "listDescription",
        "tooltip": "tooltip",
        "tooltipPriority": "INFORMATION",
        "tooltipTitle": "tooltipTitle",
        "showFormTooltip": true,
        "showListTooltip": true
      }
    ],
    "stickyColumns": [
      {
        "key": "key",
        "labelKey": "labelKey",
        "type": "type"
      }
    ],
    "auditingColumns": [
      {
        "key": "key",
        "labelKey": "labelKey",
        "type": "type"
      }
    ],
    "viewVisibility": {
      "table": {
        "visible": [
          "string"
        ],
        "hidden": [
          "string"
        ],
        "notDisplayable": [
          "string"
        ],
        "notHideable": [
          "string"
        ]
      },
      "cards": {
        "visible": [
          "string"
        ],
        "hidden": [
          "string"
        ],
        "notDisplayable": [
          "string"
        ],
        "notHideable": [
          "string"
        ]
      },
      "cards_list": {
        "visible": [
          "string"
        ],
        "hidden": [
          "string"
        ],
        "notDisplayable": [
          "string"
        ],
        "notHideable": [
          "string"
        ]
      }
    }
  }
}

json

application/json

List customers

GET

/api/v1/entities/customer/list

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('/api/v1/entities/customer/list')

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

/api/v1/entities/customer

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('/api/v1/entities/customer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  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

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

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('/api/v1/entities/customer/:uuid')

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

/api/v1/entities/customer/meta

Get customer UI metadata › Responses

200

EntityMetaResponse

entity

string · required

titleKey

string · required

uid

string · required

List row unique identifier column key (e.g. uuid)

defaultView

string · enum · required

Enum values:

table

cards

cards_list

object · required

List customers

GET

/api/v1/entities/customer/list

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

/api/v1/entities/customer

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

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

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