Field

[!info] Overview The Field REST API manages dynamic form field configurations for payment recipients in the pkbillms billing system. Fields define UI input controls with validation rules, dependencies, and multilingual support for payment forms.

📋 Table of Contents

Quick Reference

[!abstract] API Configuration
Base URL: /api
Entity Name: Field
Controller: FieldResource
Framework: Spring Boot + JHipster
Auth: Required (Spring Security)
Content-Type: application/json

Endpoints Summary

Method

Endpoint

Description

Status

POST

/api/fields

Create new field

201

PUT

/api/fields/{id}

Full update

200

PATCH

/api/fields/{id}

Partial update

200

GET

/api/fields

Get all with pagination

200

GET

/api/fields/criteria

Get by criteria

200

GET

/api/fields/{id}

Get by ID

200

GET

/api/fields/byRecipient/{id}

Get by recipient

200

GET

/api/fields/count

Count by criteria

200

DELETE

/api/fields/{id}

Delete field

204

DELETE

/api/fields/cascaded/{id}

Cascaded delete

200

Data Models

Field Specifications

Field

Type

Required

Max/Range

DB Column

Description

id

Long

❌ Auto

Primary key

name

String

✅

name

Field name

extId

Long

✅

ext_id

External ID

type

FieldType

✅

ENUM

type

Field type

controlType

ControlType

✅

ENUM

control_type

UI control type

content

String

❌

content

Content type

validation

String

❌

128

validation

Regex pattern

placeholder

String

❌

128

placeholder

Input placeholder

mask

String

❌

256

mask

Input mask

maskSymbol

String

❌

mask_symbol

Mask symbol

lengthMin

Integer

❌

0-256

length_min

Min length

lengthMax

Integer

❌

0-256

length_max

Max length

requireField

String

❌

require_field

Parent field dependency

filterBy

String

❌

filter_by

Filter by field

optional

Boolean

❌

optional

Optional field

output

Boolean

❌

output

Send to server

visibility

Visibility

❌

ENUM

visibility

Visibility state

ord

Integer

❌

ord

Display order

canBeUsedInSearch

Boolean

❌

can_be_used_in_search

Search enabled

requestType

RequestType

❌

ENUM

request_type

Request type

recipient

RecipientDTO

❌

recipient_id

Recipient reference

titles

Set

❌

rel_field__title

Multilingual titles

descriptions

Set

❌

rel_field__description

Multilingual descriptions

values

Set

❌

field_value

Predefined values

prefixes

Set

❌

prefix

Phone/account prefixes

FieldType Enum

public enum FieldType {
    ACCOUNT,  
	AMOUNT,  
	RESPONSE,  
	STATIC,  
	OTHER,  
	INVOICE
}

ControlType Enum

public enum ControlType {
    TEXT,  
	SELECT,  
	HIDDEN  
PRINTER  
MONITOR  
ALLREADONLY
}

Visibility Enum

public enum Visibility {
    HIDDEN,  
	PRINTER,  
	MONITOR,  
	ALL
}

RequestType Enum

public enum RequestType {
    CHECK  
	INFO  
	PAY  
	STATUS  
	CANCEL  
	DEPOSIT  
	RECONCILE  
	CREDIT  
	DEBIT  
	CONFIRM  
	ALL
}

API Endpoints

Create Field

POST /api/fields
Creates a new field configuration.

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "name": "phone_number",
  "extId": 1001,
  "type": "ACCOUNT",
  "controlType": "TEXT",
  "content": "phone",
  "validation": "^\\+998[0-9]{9}$",
  "placeholder": "+998 XX XXX XX XX",
  "mask": "+998 ## ### ## ##",
  "maskSymbol": "#",
  "lengthMin": 13,
  "lengthMax": 13,
  "optional": false,
  "output": true,
  "visibility": "ALL",
  "ord": 1,
  "canBeUsedInSearch": true,
  "requestType": "PAY",
  "recipient": {
    "id": 5
  },
  "titles": [
    {
      "lang": "EN",
      "text": "Phone Number"
    },
    {
      "lang": "RU",
      "text": "Номер телефона"
    },
    {
      "lang": "UZ",
      "text": "Telefon raqami"
    }
  ]
}

[!warning] Validation Rules
id must be null (auto-generated)
name, extId, type, controlType are required
String fields must respect max length constraints
validation must be valid Java regex pattern

Response

✅ Success (201 Created):

HTTP/1.1 201 Created
Location: /api/fields/1

{
  "id": 1,
  "name": "phone_number",
  "extId": 1001,
  "type": "ACCOUNT",
  "controlType": "TEXT",
  "content": "phone",
  "validation": "^\\+998[0-9]{9}$",
  "placeholder": "+998 XX XXX XX XX",
  "mask": "+998 ## ### ## ##",
  "maskSymbol": "#",
  "lengthMin": 13,
  "lengthMax": 13,
  "optional": false,
  "output": true,
  "visibility": "ALL",
  "ord": 1,
  "canBeUsedInSearch": true,
  "requestType": "PAY",
  "recipient": {
    "id": 5,
    "shortName": "MOBILE_OPERATOR"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Phone Number"
    },
    {
      "id": 2,
      "lang": "RU",
      "text": "Номер телефона"
    },
    {
      "id": 3,
      "lang": "UZ",
      "text": "Telefon raqami"
    }
  ],
  "createdBy": "admin",
  "createdDate": "2026-01-29T14:30:00Z",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2026-01-29T14:30:00Z"
}

❌ Error (400 - ID exists):

{
  "status": 400,
  "detail": "A new field cannot already have an ID",
  "message": "error.idexists"
}

Update Field

[!example] PUT /api/fields/{id} Updates an existing field (full update).

Request

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "name": "phone_number",
  "extId": 1001,
  "type": "ACCOUNT",
  "controlType": "TEXT",
  "validation": "^\\+998[0-9]{9}$",
  "optional": false,
  "output": true,
  "visibility": "ALL",
  "ord": 1,
  "requestType": "PAY",
  "recipient": {
    "id": 5
  }
}

[!warning] Validation Rules
id must match path parameter
id must not be null
Field must exist in database

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "phone_number",
  "extId": 1001,
  "type": "ACCOUNT",
  "controlType": "TEXT",
  "validation": "^\\+998[0-9]{9}$",
  "optional": false,
  "output": true,
  "visibility": "ALL",
  "ord": 1,
  "requestType": "PAY",
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2026-01-29T15:00:00Z"
}

❌ Error (400 - Invalid ID):

{
  "status": 400,
  "detail": "Invalid ID",
  "message": "error.idinvalid"
}

❌ Error (400 - Not found):

{
  "status": 400,
  "detail": "Entity not found",
  "message": "error.idnotfound"
}

Partial Update

[!example] PATCH /api/fields/{id} Partially updates field properties.

Request

Headers:

Content-Type: application/merge-patch+json
Authorization: Bearer {token}

Body:

{
  "id": 1,
  "optional": true,
  "visibility": "ALL",
  "ord": 2
}

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

{
  "id": 1,
  "name": "phone_number",
  "optional": true,
  "visibility": "ALL",
  "ord": 2,
  "lastModifiedBy": "admin",
  "lastModifiedDate": "2026-01-29T15:15:00Z"
}

Get All Fields

[!example] GET /api/fields Retrieves all fields with pagination and filtering.

Request

Headers:

Authorization: Bearer {token}

Query Parameters:

Parameter

Type

Required

Description

page

Integer

❌

Page number (default: 0)

size

Integer

❌

Page size (default: 20)

sort

String

❌

Sort field and direction

Example:

GET /api/fields?page=0&size=10&sort=ord,asc

Response

✅ Success (200 OK):

HTTP/1.1 200 OK
X-Total-Count: 50

[
  {
    "id": 1,
    "name": "phone_number",
    "type": "TEXT",
    "controlType": "INPUT",
    "ord": 1,
    "recipient": {
      "id": 5,
      "shortName": "MOBILE_OPERATOR"
    }
  },
  {
    "id": 2,
    "name": "account_number",
    "type": "TEXT",
    "controlType": "INPUT",
    "ord": 2,
    "recipient": {
      "id": 5,
      "shortName": "MOBILE_OPERATOR"
    }
  }
]

FieldCriteria - Advanced Filtering

[!abstract] JHipster Criteria Filtering FieldCriteria provides powerful filtering capabilities for querying fields. All filter parameters support multiple operators for precise data retrieval.

Available Filter Types

String Filters:

Operator

Description

Example

equals

Exact match

name.equals=phone_number

notEquals

Not equal

name.notEquals=account

in

Match any value

name.in=phone,email,login

notIn

Not in list

name.notIn=hidden,temp

contains

Partial match

name.contains=phone

doesNotContain

Doesn't contain

name.doesNotContain=test

specified

Field exists/null

validation.specified=true

Numeric Filters (Long, Integer):

Operator

Description

Example

equals

Exact match

id.equals=5

notEquals

Not equal

extId.notEquals=1000

in

Match any value

id.in=1,2,3,4,5

notIn

Not in list

id.notIn=99,100

greaterThan

Greater than

ord.greaterThan=5

lessThan

Less than

ord.lessThan=10

greaterOrEqualThan

Greater or equal

lengthMin.greaterOrEqualThan=10

lessOrEqualThan

Less or equal

lengthMax.lessOrEqualThan=50

specified

Field exists/null

ord.specified=true

Boolean Filters:

Operator

Description

Example

equals

Exact match

optional.equals=true

notEquals

Not equal

output.notEquals=false

specified

Field exists/null

optional.specified=true

Enum Filters (FieldType, ControlType, Visibility, RequestType):

Operator

Description

Example

equals

Exact match

type.equals=TEXT

notEquals

Not equal

type.notEquals=SELECT

in

Match any value

type.in=TEXT,SELECT,DATE

notIn

Not in list

visibility.notIn=HIDDEN

specified

Field exists/null

requestType.specified=true

Get Fields by Criteria

[!example] GET /api/fields/criteria Retrieves fields filtered by recipient short name.

FieldCriteria Parameters

public class FieldCriteria {
    private LongFilter id;
    private StringFilter name;
    private LongFilter extId;
    private FieldTypeFilter type;
    private ControlTypeFilter controlType;
    private StringFilter content;
    private StringFilter validation;
    private StringFilter placeholder;
    private StringFilter mask;
    private StringFilter maskSymbol;
    private IntegerFilter lengthMin;
    private IntegerFilter lengthMax;
    private StringFilter requireField;
    private StringFilter filterBy;
    private BooleanFilter optional;
    private BooleanFilter output;
    private VisibilityFilter visibility;
    private IntegerFilter ord;
    private RequestTypeFilter requestType;
    private LongFilter recipientId;          // Filter by recipient
    private LongFilter titleId;              // Filter by title I18n
    private LongFilter descriptionId;        // Filter by description I18n
    private LongFilter valueId;              // Filter by field value
    private LongFilter prefixId;             // Filter by prefix
}

Common Query Examples

Filter by Recipient:

GET /api/fields?recipientId.equals=5

Filter by Multiple Types:

GET /api/fields?type.in=TEXT,SELECT&recipientId.equals=5

Filter Required Fields for PAY:

GET /api/fields?requestType.equals=PAY&optional.equals=false&recipientId.equals=5

Filter with Validation Pattern:

GET /api/fields?validation.specified=true&recipientId.equals=5

Range Filter:

GET /api/fields?ord.greaterThan=0&ord.lessThan=10&recipientId.equals=5

Search by Name:

GET /api/fields?name.contains=phone&recipientId.equals=5

Visible Fields Only:

GET /api/fields?visibility.equals=ALL&recipientId.equals=5

Fields with Values:

GET /api/fields?valueId.specified=true&recipientId.equals=5

Complex Filter (AND operation):

GET /api/fields?recipientId.equals=5&requestType.equals=PAY&type.in=TEXT,SELECT&optional.equals=false&visibility.equals=ALL&ord.greaterThan=0&sort=ord,asc

Combining Filters

[!tip] Multiple Criteria All criteria are combined with AND logic. Use .in operator for OR logic on same field.

Example:

# AND: Recipient=5 AND Type=TEXT AND Optional=false
GET /api/fields?recipientId.equals=5&type.equals=TEXT&optional.equals=false

# OR (same field): Type=TEXT OR Type=SELECT
GET /api/fields?type.in=TEXT,SELECT&recipientId.equals=5

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/fields/criteria?recipientId=10&page=0&size=10

Response

✅ Success (200 OK):

[
  {
    "id": 1,
    "name": "phone_number",
    "type": "OTHER",
    "recipient": {
      "id": 5,
      "shortName": "MOBILE_OPERATOR"
    }
  }
]

Get Single Field

[!example] GET /api/fields/{id} Retrieves a single field by ID.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/fields/1

Response

✅ Success (200 OK):

{
  "id": 1,
  "name": "phone_number",
  "extId": 1001,
  "type": "OTHER",
  "controlType": "TEXT",
  "content": "phone",
  "validation": "^\\+998[0-9]{9}$",
  "placeholder": "+998 XX XXX XX XX",
  "mask": "+998 ## ### ## ##",
  "maskSymbol": "#",
  "lengthMin": 13,
  "lengthMax": 13,
  "optional": false,
  "output": true,
  "visibility": "ALL",
  "ord": 1,
  "canBeUsedInSearch": true,
  "requestType": "PAY",
  "recipient": {
    "id": 5,
    "shortName": "MOBILE_OPERATOR"
  },
  "titles": [
    {
      "id": 1,
      "lang": "EN",
      "text": "Phone Number"
    }
  ],
  "values": [],
  "prefixes": [
    {
      "id": 1,
      "type": "PHONE",
      "value": "+998",
      "output": true
    }
  ]
}

❌ Error (404 - Not found):

{
  "status": 404,
  "detail": "Field not found with ID: 999",
  "message": "error.notfound"
}

Get Fields by Recipient

[!example] GET /api/fields/byRecipient/{id} Retrieves all fields for a specific recipient.

Request

Headers:

Authorization: Bearer {token}

Example:

GET /api/fields/byRecipient/5

Response

✅ Success (200 OK):

[
  {
    "id": 1,
    "name": "phone_number",
    "type": "ACCOUNT",
    "ord": 1
  },
  {
    "id": 2,
    "name": "amount",
    "type": "OTHER",
    "ord": 2,
    "values": [
      {
        "id": 1,
        "value": "50000",
        "amount": 50000
      },
      {
        "id": 2,
        "value": "100000",
        "amount": 100000
      }
    ]
  }
]

Count Fields

[!example] GET /api/fields/count Counts fields matching criteria.

Request

Headers:

Authorization: Bearer {token}

Query Parameters:

Parameter

Type

Required

Description

recipientId

Long

❌

Filter by recipient

requestType

String

❌

Filter by type

Example:

GET /api/fields/count?recipientId=5&requestType=PAY

Response

✅ Success (200 OK):

Delete Field

[!example] DELETE /api/fields/{id} Deletes a field.

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/fields/1

Response

✅ Success (204 No Content):

HTTP/1.1 204 No Content

Cascaded Delete Field

[!example] DELETE /api/fields/cascaded/{id} Deletes a field with all related entities (values, prefixes).

Request

Headers:

Authorization: Bearer {token}

Example:

DELETE /api/fields/cascaded/1

Response

✅ Success (200 OK):

HTTP/1.1 200 OK

Error Handling

Error Response Format

{
  "type": "https://www.jhipster.tech/problem/problem-with-message",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed",
  "path": "/api/fields",
  "message": "error.validation",
  "fieldErrors": [
    {
      "objectName": "fieldDTO",
      "field": "name",
      "message": "must not be null"
    }
  ]
}

HTTP Status Codes

Code

Description

When

200

Successful GET/PUT/PATCH

201

Created

Successful POST

204

No Content

Successful DELETE

400

Bad Request

Validation error

401

Unauthorized

Missing/invalid authentication

403

Forbidden

Insufficient permissions

404

Not Found

Resource doesn't exist

500

Internal Server Error

Server error

Validation Rules

Required Fields

[!check] Mandatory Fields
✅ name - Field name
✅ extId - External ID
✅ type - Field type
✅ controlType - Control type

Field Constraints

Field

Rules

Error Messages

id

Null for POST

"A new field cannot already have an ID"

id

Not null for PUT/PATCH

"Invalid id"

name

@NotNull, @Size(max=64)

"must not be null", "size must be between 0 and 64"

extId

@NotNull

"must not be null"

type

@NotNull

"must not be null"

controlType

@NotNull

"must not be null"

validation

@Size(max=128)

"size must be between 0 and 128"

placeholder

@Size(max=128)

"size must be between 0 and 128"

mask

@Size(max=256)

"size must be between 0 and 256"

maskSymbol

@Size(max=2)

"size must be between 0 and 2"

lengthMin

@Min(0), @Max(256)

"must be between 0 and 256"

lengthMax

@Min(0), @Max(256)

"must be between 0 and 256"

requireField

@Size(max=64)

"size must be between 0 and 64"

filterBy

@Size(max=16)

"size must be between 0 and 16"

Business Rules

[!info] Business Validation
validation must be valid Java regex pattern
mask format: Use # as placeholder symbol
lengthMin must be less than or equal to lengthMax
requireField references another field's name
filterBy references parent field for dependent values

🔧 cURL Command Reference

Create

curl -X POST http://localhost:8080/api/fields \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "phone_number",
    "extId": 1001,
    "type": "ACCOUNT",
    "controlType": "TEXT",
    "validation": "^\\+998[0-9]{9}$",
    "placeholder": "+998 XX XXX XX XX",
    "optional": false,
    "output": true,
    "visibility": "ALL",
    "ord": 1,
    "requestType": "PAY",
    "recipient": {"id": 5},
    "titles": [{"lang": "EN", "text": "Phone Number"}]
  }'

Update

curl -X PUT http://localhost:8080/api/fields/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": 1,
    "name": "phone_number",
    "extId": 1001,
    "type": "ACCOUNT",
    "controlType": "TEXT",
    "optional": false,
    "output": true,
    "recipient": {"id": 5}
  }'

Partial Update

curl -X PATCH http://localhost:8080/api/fields/1 \
  -H "Content-Type: application/merge-patch+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"id": 1, "optional": true, "ord": 2}'

Get All

curl -X GET "http://localhost:8080/api/fields?page=0&size=10&sort=ord,asc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Criteria

curl -X GET "http://localhost:8080/api/fields/criteria?recipientId.equals=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Single

curl -X GET http://localhost:8080/api/fields/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Get by Recipient

curl -X GET http://localhost:8080/api/fields/byRecipient/5 \
  -H "Authorization: Bearer YOUR_TOKEN"

Count

curl -X GET "http://localhost:8080/api/fields/count?recipientId=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

curl -X DELETE http://localhost:8080/api/fields/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Cascaded Delete

curl -X DELETE http://localhost:8080/api/fields/cascaded/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

PreviousTransaction NextField value

Last updated 1 month ago

hashtag📋 Table of Contents

hashtagQuick Reference

hashtagEndpoints Summary

hashtagData Models

hashtagField Specifications

hashtagFieldType Enum

hashtagControlType Enum

hashtagVisibility Enum

hashtagRequestType Enum

hashtagAPI Endpoints

hashtagCreate Field

hashtagRequest

hashtagResponse

hashtagUpdate Field

hashtagRequest

hashtagResponse

hashtagPartial Update

hashtagRequest

hashtagResponse

hashtagGet All Fields

hashtagRequest

hashtagResponse

hashtagFieldCriteria - Advanced Filtering

hashtagAvailable Filter Types

hashtagGet Fields by Criteria

hashtagFieldCriteria Parameters

hashtagCommon Query Examples

hashtagCombining Filters

hashtagRequest

hashtagResponse

hashtagGet Single Field

hashtagRequest

hashtagResponse

hashtagGet Fields by Recipient

hashtagRequest

hashtagResponse

hashtagCount Fields

hashtagRequest

hashtagResponse

hashtagDelete Field

hashtagRequest

hashtagResponse

hashtagCascaded Delete Field

hashtagRequest

hashtagResponse

hashtagError Handling

hashtagError Response Format

hashtagHTTP Status Codes

hashtagValidation Rules

hashtagRequired Fields

hashtagField Constraints

hashtagBusiness Rules

hashtag🔧 cURL Command Reference

hashtagCreate

hashtagUpdate

hashtagPartial Update

hashtagGet All

hashtagGet by Criteria

hashtagGet Single

hashtagGet by Recipient

hashtagCount

hashtagDelete

hashtagCascaded Delete

📋 Table of Contents

Quick Reference

Endpoints Summary

Data Models

Field Specifications

FieldType Enum

ControlType Enum

Visibility Enum

RequestType Enum

API Endpoints

Create Field

Request

Response

Update Field

Request

Response

Partial Update

Request

Response

Get All Fields

Request

Response

FieldCriteria - Advanced Filtering

Available Filter Types

Get Fields by Criteria

FieldCriteria Parameters

Common Query Examples

Combining Filters

Request

Response

Get Single Field

Request

Response

Get Fields by Recipient

Request

Response

Count Fields

Request

Response

Delete Field

Request

Response

Cascaded Delete Field

Request

Response

Error Handling

Error Response Format

HTTP Status Codes

Validation Rules

Required Fields

Field Constraints

Business Rules

🔧 cURL Command Reference

Create

Update

Partial Update

Get All

Get by Criteria

Get Single

Get by Recipient

Count

Delete

Cascaded Delete