APIs CMO API Product Query Filters

This page explains how to filter and look up products in the Connection Management Orchestrator (CMO) API.

There are two ways to select products:

  • GET /{tenant}/product returns a paginated list of products, narrowed by query-string filters.
  • POST /{tenant}/product/find looks up products in bulk by a list of identifiers (ICCID, IMSI, MSISDN, and so on), without pagination.
NOTE
Filters also influence how CMO paginates results across multiple platforms and credentials. See Understanding Pagination for how the effective page size is calculated.

Filtering with GET /product

Pass filters as URL query parameters. The CMO API supports two families of filters:

  • Product-level filters — for example platform, relatedParty.name, customProperty.name, customProperty.value.
  • Identifier filters — for example ICCID, IMSI, MSISDN, serialNumber.
NOTE
Successful list responses use HTTP 206 Partial Content, not 200. This is expected.

Product-level filters

FilterDescription
platformRestrict results to one or more external platforms (for example JASPER, TMSP, STC).
relatedParty.nameRestrict results to products belonging to a specific account name.
customProperty.nameMatch products that have a custom property with the given name.
customProperty.valueMatch products that have a custom property with the given value.
NOTE
Only these four product-level filters are supported. Any other query key — an unsupported one such as status or id, or a mistyped filter name — is silently ignored, so the request returns unfiltered results instead of raising an error.
NOTE
platform values are case-sensitive. Use the platform’s canonical name (for example JASPER, TMSP, STC) exactly as shown; a value like platform=stc will not match.

Identifier filters

Use these to narrow the list to specific connectivity identifiers. Provide multiple values as a comma-separated list. The identifier filter names are case-insensitive: ICCID, iccid, and MSISDN/msisdn are all accepted.

FilterFormatExample
ICCID89 followed by 14–18 digitsICCID=8912345678901234
IMSI6–15 digitsIMSI=234150999999999
MSISDN6–15 digitsMSISDN=491701234567
serialNumber5–22 digits, or a Starlink identifier (SL-DF-...)serialNumber=5507829281
GET /{tenant}/product?ICCID=8912345678901234,8912345678905678
NOTE
When you provide more than one identifier filter (for example ICCID and IMSI), CMO returns products matching any of them.

Combining filters

CMO combines filters using two separators:

  • & means AND. Conditions joined with & must all match. Use it to combine different filters.
  • ; means OR. Conditions separated by ; form alternative groups; a product matches if it satisfies any group.
# JASPER products that also have a custom property named "fleet"  (AND)
GET /{tenant}/product?platform=JASPER&customProperty.name=fleet

# products on JASPER OR TMSP  (OR)
GET /{tenant}/product?platform=JASPER;platform=TMSP

# combine both: (JASPER AND custom property "fleet") OR (any TMSP product)
GET /{tenant}/product?platform=JASPER&customProperty.name=fleet;platform=TMSP
NOTE
Repeating the same key within a group ANDs its values: platform=TMSP&platform=STC requires a product to match both, which for platform rarely matches anything (a product belongs to one platform). To select multiple platforms, use ; (OR) instead: platform=TMSP;platform=STC.

Selecting response fields

Use fields to limit which fields are returned (a comma-separated list). fields=none returns only the minimal identifiers: id, href, and correlationId per entity.

GET /{tenant}/product?platform=JASPER&fields=id,status&pageSize=25&pageNumber=1

Pagination is controlled by pageSize and pageNumber. See Understanding Pagination .

Finding products with POST /product/find

When you already have a set of identifiers and want the matching products, use POST /{tenant}/product/find. This endpoint takes a JSON body with up to five identifier lists and returns every product matching any of them (OR semantics). It does not paginate.

ListContainsFormat
iccidListICCIDs89 + 14–18 digits
imsiListIMSIs6–15 digits
msisdnListMSISDNs6–15 digits
terminalSNListTerminal serial numbers5–22 digits, or Starlink SL-DF-...
iotConnectionProductIdListBusiness product IDsPLATFORM-<id> (for example JASPER-8997112212741433747)

At least one list must be non-empty; the others may be omitted or left as []. Send the request with a JSON body (Content-Type: application/json):

POST /{tenant}/product/find
Content-Type: application/json

{
  "iccidList": ["896732929205668185"],
  "imsiList": ["234150999999999"],
  "msisdnList": ["491701234567"],
  "terminalSNList": ["5507829281"],
  "iotConnectionProductIdList": ["JASPER-8997112212741433747"]
}

Example response:

{
  "entities": [
    {
      "id": "TMSP-8949020160005183930",
      "href": "https://qa.spacegate.telekom.de/.../product/TMSP-8949020160005183930",
      "status": "ACTIVE",
      "connectivityType": "CELLULAR",
      "productCharacteristic": [ { "name": "PLATFORM", "value": "TMSP" } ],
      "relatedParty": [
        { "name": "DT_API_3", "characteristic": [ { "name": "PLATFORM_ACCOUNT", "value": "723" } ], "role": "customer" }
      ],
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}
NOTE
A request can include at most 1000 identifiers. The total number of items across all five lists must not exceed 1000. If it does, the overall HTTP status stays 200 while an error inside errors[] carries 400. Separately, request bodies larger than roughly 1 MB are rejected with a standard 413 Payload Too Large.

Example response when the limit is exceeded:

{
  "entities": [],
  "errors": [
    {
      "type": "Bad Request",
      "status": 400,
      "detail": "Request exceeded the maximum allowed items. Please limit your request to 1000 items or fewer.",
      "externalErrors": [],
      "relatedParty": [],
      "@type": "problem"
    }
  ],
  "correlationId": "..."
}

IMSI and MSISDN misses

NOTE

With POST /product/find, an IMSI or MSISDN that matches no product does not produce a “not found” error, and CMO does not report which IMSIs or MSISDNs were unmatched. Only the products that were found appear in entities[], so a shorter-than-expected result can mean some were not matched.

ICCID, terminal serial number, and iotConnectionProductId misses behave differently: they appear as error entries in errors[] (for example a 404 Product not found), still under an overall HTTP 200.

To detect IMSI or MSISDN misses, compare the identifiers you requested against those present in the response.

See also