Generic Lookup Tables API — API Analysis (API-A)

Concept layer — frozen. The Lookup Tables generic. Nothing here is written by a normal playbook run; a project's own feature analysis is the live document and takes every edit. This layer names no project and links to none — the dependency runs one way, from an application to its concept.

Feature: Lookup Tables · Entity: lookupTable

Paths below are written without any version or gateway prefix: how a project versions and mounts the routes is an application decision, not part of the concept. Success envelope: { data, status, message, requestId }.

---

1. Get Lookup Values

Endpoint: GET /lookup-tables?lookupKey=$lookupKey&active=$active

Description

Returns a map grouped by lookupKey, where each key maps to an array of values.

The shape below is the administration read. A project may project it to a client-facing subset — typically lookupValue, position and attributes, without id, active or the timestamps — where whole catalogues are handed to a client at start-up; say which shape each consumer receives.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
lookupKey	String	No	Filter values by specific key (optional)
active	Boolean	No	Filter by active status (true/false)

Success Response (200 OK)

{
  "data": {
    "lt.locale": [
      {
        "id": "30f02171-1332-4c76-a5b7-0b5c2f1e0f90",
        "lookupValue": "cs-CZ",
        "attributes": {
          "isEuCountry": true
        },
        "position": 1,
        "active": true,
        "createdAt": "2025-04-18T18:00:00Z",
        "updatedAt": "2025-04-18T18:00:00Z"
      },
      {
        "id": "9d601f30-c019-4ac7-bac1-93d9c09c34e1",
        "lookupValue": "en-GB",
        "attributes": {
          "isEuCountry": false
        },
        "position": null,
        "active": true,
        "createdAt": "2025-04-18T18:01:00Z",
        "updatedAt": "2025-04-18T18:01:00Z"
      }
    ],
    "lt.paymentType": [
      {
        "id": "12d8bcd2-bcb0-47fc-8e4c-97eaeb9e879b",
        "lookupValue": "credit_card",
        "attributes": null,
        "position": null,
        "active": true,
        "createdAt": "2025-04-18T18:02:00Z",
        "updatedAt": "2025-04-18T18:02:00Z"
      }
    ]
  },
  "status": 200,
  "message": "Lookup values retrieved and grouped by key.",
  "requestId": "a1e5aef6-bf4f-41c1-89cf-dcc6b190d3e7"
}

---

2. Create Lookup Values

Endpoint: POST /lookup-tables

Description

Creates multiple lookup values in a single request, grouped by lookupKey. Admin feature only.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "data": [
    {
      "lookupKey": "lt.locale",
      "attributes": {
        "isEuCountry": true
      },
      "lookupValue": "fr-FR",
      "position": 1,
      "active": true
    },
    {
      "lookupKey": "lt.locale",
      "attributes": {
        "isEuCountry": false
      },
      "lookupValue": "fr-BE",
      "position": 2,
      "active": true
    }
  ]
}

Success Response (201 Created)

{
  "data": [
    {
      "id": "uuid1",
      "lookupKey": "lt.locale",
      "lookupValue": "fr-FR",
      "attributes": {
        "isEuCountry": true
      },
      "position": 1,
      "active": true,
      "createdAt": "2025-04-18T18:02:00Z",
      "updatedAt": "2025-04-18T18:02:00Z"
    },
    {
      "id": "uuid2",
      "lookupKey": "lt.locale",
      "lookupValue": "fr-BE",
      "attributes": {
        "isEuCountry": false
      },
      "position": 2,
      "active": true,
      "createdAt": "2025-04-18T18:02:00Z",
      "updatedAt": "2025-04-18T18:02:00Z"
    }
  ],
  "status": 201,
  "message": "Lookups created successfully.",
  "requestId": "c7a4f924-8e4e-4192-83f2-3eb8b16e9a25"
}

---

3. Update Lookup Values

Endpoint: PATCH /lookup-tables

Description

Updates multiple lookup values in batch mode. Admin feature only.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "data": [
    {
      "id": "uuid1",
      "lookupValue": "fr-BE",
      "active": false
    },
    {
      "id": "uuid2",
      "position": 2
    }
  ]
}

Success Response (200 OK)

{
  "data": [
    {
      "id": "uuid1",
      "lookupKey": "lt.locale",
      "lookupValue": "fr-BE",
      "attributes": {
        "isEuCountry": true
      },
      "position": 1,
      "active": false,
      "createdAt": "2025-04-18T18:02:00Z",
      "updatedAt": "2025-04-18T18:02:00Z"
    },
    {
      "id": "uuid2",
      "lookupKey": "lt.locale",
      "lookupValue": "fr-FR",
      "attributes": null,
      "position": 2,
      "active": true,
      "createdAt": "2025-04-18T18:02:00Z",
      "updatedAt": "2025-04-18T18:02:00Z"
    }
  ],
  "status": 200,
  "message": "Lookups updated successfully.",
  "requestId": "c7a4f924-8e4e-4192-83f2-3eb8b16e9a25"
}

---

4. Delete Lookup Values

Endpoint: DELETE /lookup-tables

Description

Performs batch soft deletion of multiple lookup values by ID, grouped under their keys. Admin feature only.

Request Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request Body

{
  "data": [
    {
      "id": "uuid1"
    },
    {
      "id": "uuid2"
    }
  ]
}

Success Response (200 OK)

{
  "data": {},
  "status": 200,
  "message": "Lookups deleted.",
  "requestId": "9b6ad239-82df-4c99-a6db-1bb8a19d2c5e"
}