Corebanq Public Docs
Items

Description

Overview

The Items API provides functionality for managing generic items and set items in the system. It supports:

  • Multiple item types
  • Multilingual title and description for generic items
  • Set items for record associations
  • Active/inactive status
  • System items (protected from deletion)
  • Custom sorting order
  • RBAC-based access control

Core Concepts

Item Structure

Each item consists of:

  • ID: UUID identifier for the item
  • Type: Categorizes the item (e.g., "product", "service", "category")
  • Name: Unique identifier within its type
  • Title: Multilingual title in supported languages
  • Description: Multilingual description in supported languages
  • Sort Order: Custom ordering for display purposes
  • Active Status: Whether the item is active or not
  • System: Whether the item is a system item (system items cannot be deleted)

Set Item Structure

Each set item consists of:

  • ID: UUID identifier for the set item
  • Record ID: ID of the associated record
  • Record Type: Type of the associated record
  • Type: Categorizes the set item
  • Name: Name of the set item
  • Active Status: Whether the item is active or not
  • Created/Modified: Timestamps and user tracking

Multilingual Support

Title and description fields support multiple languages. The response language is determined by the Accept-Language header:

{
  "title": {
    "en": "English Title",
    "de": "Deutscher Titel",
    "fr": "Titre Français",
    "it": "Titolo Italiano",
    "cz": "Český název"
  }
}

API Endpoints

Endpoints that return localized fields (typically GET endpoints) can include the Accept-Language header to specify the response language. If omitted, the service falls back to "en".

Create Set Item

POST {{base_url}}/v1/items/set

Create a new set item. The server will generate a UUID for the new set item.

Request Body

{
  "record_id": "string",    // ID of the record this set item is associated with
  "record_type": "string",  // Type of the record
  "type": "string",         // Type of the set item
  "name": "string"          // Name of the set item
}

Response

{
  "id": "uuid-string",
  "record_id": "string",
  "record_type": "string",
  "type": "string",
  "name": "string",
  "created_at": "2025-02-24T12:57:34+01:00",
  "created_by": "user-uuid",
  "modified_at": "2025-02-24T12:57:34+01:00",
  "modified_by": "user-uuid",
  "active": true,
  "metadata": {}
}

Create Item

POST {{base_url}}/v1/items

Create a new item. The server will generate a UUID for the new item.

Request Body:

{
  "type": "product",
  "name": "premium-savings-account",
  "title": {
    "en": "Premium Savings Account",
    "de": "Premium-Sparkonto",
    "fr": "Compte d'épargne Premium",
    "it": "Conto di Risparmio Premium",
    "cz": "Prémiový spořicí účet"
  },
  "description": {
    "en": "High-yield savings account with premium benefits",
    "de": "Hochverzinsliches Sparkonto mit Premium-Vorteilen",
    "fr": "Compte d'épargne à haut rendement avec avantages premium",
    "it": "Conto di risparmio ad alto rendimento con vantaggi premium",
    "cz": "Výnosný spořicí účet s prémiovými výhodami"
  },
  "sort_order": 1,
  "active": true,
  "system": false
}

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "product",
  "name": "premium-savings-account",
  "title": {
    "en": "Premium Savings Account"
  },
  "description": {
    "en": "High-yield savings account with premium benefits"
  },
  "sort_order": 1,
  "active": true,
  "system": false,
  "created_at": "2025-02-23T16:14:05Z",
  "updated_at": "2025-02-23T16:14:05Z"
}

Get Item

GET {{base_url}}/v1/items/{id}

Retrieve an item by its UUID.

Update Item

PUT {{base_url}}/v1/items/{id}

Update an existing item by its UUID. Only the fields that need to be updated should be included in the request.

Request Body:

{
  "title": {
    "en": "Premium Savings Account V2"
  },
  "active": false
}

Delete Item

DELETE {{base_url}}/v1/items/{id}

Delete an item by its UUID.

Note: System items (where system is true) cannot be deleted. Attempting to delete a system item will return a 400 Bad Request error with the message "system items cannot be deleted".

List Items

GET {{base_url}}/v1/items

List all items with pagination support.

Response:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "type": "product",
      "name": "premium-savings-account",
      "title": {
        "en": "Premium Savings Account"
      },
      "description": {
        "en": "High-yield savings account with premium benefits"
      },
      "sort_order": 1,
      "active": true,
      "system": false,
      "created_at": "2025-02-23T16:14:05Z",
      "updated_at": "2025-02-23T16:14:05Z"
    }
  ],
  "total": 1,
  "has_more": false
}

Get Distinct Item Types

GET {{base_url}}/v1/items/types/distinct

Retrieve distinct item types with their counts. This endpoint returns a list of all unique item types and how many active items exist for each type.

Response:

[
  {
    "type": "mfa",
    "count": 3
  },
  {
    "type": "credential", 
    "count": 5
  },
  {
    "type": "address",
    "count": 2
  }
]

Get Set Items

GET {{base_url}}/v1/items/set

Retrieve a list of set items with support for filtering, sorting, pagination, and stacking.

Query Parameters

search.* (optional): Search parameters using dot-notation where the part after search. is the field name (e.g., search.type, search.name, search.active).

sort (optional): Sort field. Prefix with - for descending order (e.g., sort=-created_at, sort=name).

  • limit (optional): Number of items per page (default: 10, max: 100)
  • offset (optional): Starting position for pagination
  • stack (optional): Field to stack by (record_type or type)
  • distinct (optional): Field to get distinct records by (record_id - gets the latest record per record_id)

Example Request

GET {{base_url}}/v1/items/set?limit=10&offset=0&search.type=RISK_LEVELS&search.active=true&sort=-created_at

Example Request with Distinct (Latest Status per Record)

To get the latest status for each record_id and then filter by name:

GET {{base_url}}/v1/items/set?limit=10&offset=0&search.type=ACCOUNT_CLOSURE_REQUEST&search.active=true&search.name=OPEN&sort=-created_at&distinct=record_id

This query will:

  1. First get the latest record for each record_id (based on created_at DESC)
  2. Then filter those results where name = 'OPEN'
  3. Apply sorting and pagination to the final results

This is useful for historical data where each record has multiple status changes over time, and you want to find records that are currently in a specific state.

Response (Paginated)

{
  "data": [
    {
      "id": "uuid-string",
      "record_id": "string",
      "record_type": "string",
      "type": "string",
      "name": "string",
      "created_at": "2025-02-24T13:19:41+01:00",
      "created_by": "user-uuid",
      "modified_at": "2025-02-24T13:19:41+01:00",
      "modified_by": "user-uuid",
      "active": true,
      "metadata": {}
    }
  ],
  "total": 100,
  "has_more": true
}

Response (Stacked)

{
  "data": {
    "record_type1": [      // Items grouped by record_type or type
      {
        "id": "uuid-string",
        "record_id": "string",
        "record_type": "string",
        "type": "string",
        "name": "string",
        "created_at": "2025-02-24T13:19:41+01:00",
        "created_by": "user-uuid",
        "modified_at": "2025-02-24T13:19:41+01:00",
        "modified_by": "user-uuid",
        "active": true,
        "metadata": {}
      }
    ]
  },
  "total": 100,
  "has_more": false
}

Error Codes

CodeDescription
items.not_foundItem not found
items.name_existsItem with the same name already exists
items.invalid_typeInvalid item type provided
items.invalid_sort_orderSort order is out of range
items.description_emptyDescription must be provided for required languages
items.invalid_inputInvalid input data
items.failed_to_createFailed to create item
items.failed_to_getFailed to retrieve item
items.failed_to_updateFailed to update item
items.failed_to_deleteFailed to delete item
items.system_item_cannot_be_deletedSystem items cannot be deleted
items.failed_to_listFailed to list items
items.invalid_idInvalid item ID
set_items.not_foundSet item not found
set_items.failed_to_createFailed to create set item
set_items.failed_to_listFailed to list set items

RBAC Permissions

The following permissions are required for item operations:

OperationPermission
Createitems.create
Readitems.read
Updateitems.update
Deleteitems.delete

Response Examples

Successful Item Creation

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "product",
  "name": "unique-product-name",
  "title": {
    "en": "Product Title",
    "de": "Produkttitel"
  },
  "description": {
    "en": "Product description",
    "de": "Produktbeschreibung"
  },
  "sort_order": 1,
  "active": true,
  "system": false,
  "created_at": "2025-02-23T16:14:05Z",
  "updated_at": "2025-02-23T16:14:05Z"
}

Error Response

{
  "error": {
    "code": "items.name_exists",
    "message": "Item with this name already exists",
    "params": {
      "name": "unique-product-name"
    }
  }
}

PUTUpdate invoice (v3)

Replace invoice fields using the v3 source/destination selector model. The server always stores the invoice as active=true.

POSTCreate new item

Next Page

On this page

OverviewCore ConceptsItem StructureSet Item StructureMultilingual SupportAPI EndpointsCreate Set ItemRequest BodyResponseCreate ItemGet ItemUpdate ItemDelete ItemList ItemsGet Distinct Item TypesGet Set ItemsQuery ParametersExample RequestExample Request with Distinct (Latest Status per Record)Response (Paginated)Response (Stacked)Error CodesRBAC PermissionsResponse ExamplesSuccessful Item CreationError Response