Skip to main content

Smart Holder List Paged

This API allows a Studio (submitter) to retrieve a paginated list of companies (holders) it manages, filtered by their smart activation status.

Why This API Exists​

The TS Archive system supports a concept called smart activation, which enables simplified and automated archival flows for companies managed by a Studio. Each company (holder) can be in a different stage of that activation process.

This API exists so that consumers can retrieve a filtered, paginated snapshot of the holder list as structured JSON. For example, to see which companies are still waiting for certification, which have been validated, or to feed downstream processes that need holder details.

Smart Activation Statuses​

Each holder can be in one of the following statuses:

StatusMeaning
INITIALIZEDSmart activation has been started but not yet submitted for certification.
TOBE_CERTIFIEDSubmitted and awaiting certification.
REJECTEDCertification was rejected.
MISSINGRequired data is incomplete or missing.
VALIDATEDSmart activation has been validated and is active.
VALIDATED_WITH_DRAFTValidated, but a draft modification is pending.
VALIDATED_WITH_DRAFT_TOBE_CERTIFIEDValidated with a draft submitted for re-certification.
VALIDATED_WITH_DRAFT_REJECTEDValidated but the pending draft was rejected.

Use Cases​

Use this API when you need to:

  • Browse a paginated list of holders filtered by smart activation status.
  • Inspect holder details such as tax ID, VAT number, preservation manager, and delegation file.
  • Monitor smart activation progress across all companies managed by a Studio.
  • Build UI views or integrations that require structured JSON holder data with pagination support.

How to Use the API​

Endpoint​

POST /api/v1/config/smart-holder-list-paged

Authentication​

Authentication is required. Refer to the Authentication page for how to obtain and use a valid JWT token.

Allowed security roles: M2M, User, Backoffice

Headers​

All standard headers are required for this request. Refer to the Standard Headers page for the full list and their descriptions.

Request Body​

Content-Type: application/json

The request body must have the following format:

{
  "status_filter": "INITIALIZED",
  "text_search": "string",
  "submitter_uuid": "string",
  "nextPageRequest": {
    "sourcePage": 0
  }
}

Fields:

  • status_filter (string, optional) — Filter holders by smart activation status. Accepted values: INITIALIZED, TOBE_CERTIFIED, REJECTED, MISSING, VALIDATED, VALIDATED_WITH_DRAFT, VALIDATED_WITH_DRAFT_TOBE_CERTIFIED, VALIDATED_WITH_DRAFT_REJECTED. If omitted, all statuses are included.
  • text_search (string, optional) — Free-text search applied against holder name or identifier.
  • submitter_uuid (string, optional) — UUID of the submitter (Studio) whose holders should be retrieved. Required when calling as M2M or Backoffice.
  • nextPageRequest.sourcePage (integer, optional) — Zero-based page index for pagination. Use 0 for the first page; increment to retrieve subsequent pages.

Responses​

200 OK — Paginated holder list returned​

The response body is a JSON object containing the list of holders matching the search criteria, along with pagination information.

{
  "smart_holder_items": [
    {
      "id": "string",
      "description": "string",
      "tax_id": "string",
      "vat_number": "string",
      "preservation_manager_name": "string",
      "preservation_manager_cf": "string",
      "delegation_file": {
        "typology": "string",
        "filename": "string"
      },
      "status": "INITIALIZED",
      "reject_reason": "string",
      "active": true
    }
  ],
  "nextPageRequest": {
    "sourcePage": 0
  },
  "resultSize": 0
}

Response fields:

  • smart_holder_items (array) — List of holders returned for the current page.
    • id (string) — Unique identifier of the holder.
    • description (string) — Display name or description of the holder company.
    • tax_id (string) — Tax identification code of the holder.
    • vat_number (string) — VAT number of the holder.
    • preservation_manager_name (string) — Name of the designated preservation manager.
    • preservation_manager_cf (string) — Fiscal code of the preservation manager.
    • delegation_file.typology (string) — Type of the delegation document.
    • delegation_file.filename (string) — Filename of the delegation document.
    • status (string) — Current smart activation status of the holder.
    • reject_reason (string) — Reason for rejection, if the status is REJECTED or VALIDATED_WITH_DRAFT_REJECTED.
    • active (boolean) — Whether the holder is currently active.
  • nextPageRequest.sourcePage (integer) — Page index to use in the next request to retrieve the following page of results.
  • resultSize (integer) — Total number of results matching the filter criteria.

400 Bad Request​

One or more parameters provided in the request are incorrect, or required parameters are missing.

{
  "timestamp": "2026-02-24T14:16:14.292Z",
  "status": "CONTINUE",
  "code": "string",
  "message": "string"
}

401 Unauthorized​

The provided credentials are not correct.

{
  "timestamp": "2026-02-24T14:16:14.293Z",
  "status": "CONTINUE",
  "code": "string",
  "message": "string"
}

403 Forbidden​

The authenticated caller does not have the required permissions to perform this operation.

{
  "timestamp": "2026-02-24T14:16:14.294Z",
  "status": "CONTINUE",
  "code": "string",
  "message": "string"
}

API Reference​

Use the links below to open the interactive OpenAPI (Swagger) documentation for this endpoint in each environment.

EnvironmentAPI Documentation
Testhttps://archive-config-read.test.teamsystem.digital/swagger-ui/index.html?url=/v3/api-docs#/Archive%20config%20read/getSubmitterSmartHolderListPaged
Productionhttps://archive-config-read.teamsystem.digital/swagger-ui/index.html?url=/v3/api-docs#/Archive%20config%20read/getSubmitterSmartHolderListPaged