Consumers

Add a Consumer

The /api/consumers endpoint supports adding a new consumer. The following JSON request body is required:

consumer_id - The unique identifier for the consumer. If a consumer already exists, the existing consumer will be returned.

$ curl -s -X POST \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
-H "Content-Type: application/json" \
-d '{"consumer_id":"c87a9242-1afc-43b8-80e0-e4767c6f9c47"}' \
$ZSM_HOST/api/consumers | jq
{
  "consumer": {
    "consumer_id": "c87a9242-1afc-43b8-80e0-e4767c6f9c47",
    "state": "active",
    "created": "2025-01-10 19:54:19.212992 +00:00",
    "modified": "2025-01-10 19:54:19.212992 +00:00"
  },
  "trace_id": "bda80931-4dda-44e7-abd2-1df026b10539"
}

View a Consumer

In the example below c87a9242-1afc-43b8-80e0-e4767c6f9c47 is an example consumer identifier.

$ curl -s \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/consumers/c87a9242-1afc-43b8-80e0-e4767c6f9c47 | jq
{
  "consumer": {
    "consumer_id": "c87a9242-1afc-43b8-80e0-e4767c6f9c47",
    "state": "active",
    "created": "2025-01-10 19:54:19.212992 +00:00",
    "modified": "2025-01-10 19:54:19.212992 +00:00"
  },
  "trace_id": "91ea1b4a-ebfb-4b91-b8be-8bca4ee17d61"
}

Activate Consumer

In the example below c87a9242-1afc-43b8-80e0-e4767c6f9c47 is an example consumer identifier.

No JSON request body is required, and the "/activate" path at the end of the request URL determines the action taken on the consumer.

$ curl -s -X PATCH \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/consumers/c87a9242-1afc-43b8-80e0-e4767c6f9c47/activate | jq
{
  "consumer": {
    "consumer_id": "c87a9242-1afc-43b8-80e0-e4767c6f9c47",
    "state": "active",
    "created": "2025-01-10 19:54:19.212992 +00:00",
    "modified": "2025-01-10 20:05:41.678346 +00:00"
  },
  "trace_id": "1a9ea8e7-ecf1-4924-adcd-642c5df6144f"
}

Suspend Consumer

In the example below c87a9242-1afc-43b8-80e0-e4767c6f9c47 is an example consumer identifier.

No JSON request body is required, and the "/suspend" path at the end of the request URL determines the action taken on the consumer.

$ curl -s -X PATCH \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/consumers/c87a9242-1afc-43b8-80e0-e4767c6f9c47/suspend | jq
{
  "consumer": {
    "consumer_id": "c87a9242-1afc-43b8-80e0-e4767c6f9c47",
    "state": "suspended",
    "created": "2025-01-10 19:54:19.212992 +00:00",
    "modified": "2025-01-10 20:05:51.330682 +00:00"
  },
  "trace_id": "de3760bb-7159-475f-b671-7e38f8e4f3d0"
}

Retrieve Consumers

The /api/consumers endpoint supports retrieving a paginated list of consumers filtered by various criteria. The following optional query parameters are supported:

organization_ids - The organization identifier(s) to filter consumers by.
consumer_ids - The consumer identifier(s) to filter consumers by.
installation_ids - The installation identifier(s) to filter consumers by.
application_ids - The application identifier(s) to filter consumers by.
enrollment_ids - The enrollment identifier(s) to filter consumers by.
state - The state of the consumer(s) to filter by. Valid values are active and suspended.
page - The page number to retrieve. If a page parameter is not provided, all consumers up to the default page_size will be returned. If paging is used, page indexing starts at 1.
page_size - The number of consumers to retrieve per page. Default is 100.
order - The order in which to sort the consumers. Valid values are asc and desc. Default is asc.

NOTE: With curl in some shells, be sure to quote the URL when using query parameters. Otherwise, the & will be interpreted as a request to run the command as a background process.

The application results are automatically filtered based upon the bearer token. If the token was issued to the vendor organization, all consumers will be included. But if the token was issued to a customer, only consumers associated with that customer will be listed.

In the example below, the organization to which the bearer token was issued has only three consumers.

$ curl -s \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
"$ZSM_HOST/api/consumers" | jq
{
  "consumers": [
    {
      "consumer_id": "00000000-0000-4000-b000-000000000002",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "consumer_id": "00000000-0000-4000-b000-00000000000c",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "consumer_id": "00000000-0000-4000-b000-00000000000d",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    }
  ],
  "total": 3,
  "page_size": 100
}

$ curl -s \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
"$ZSM_HOST/api/consumers?page=1&page_size=2" | jq
{
  "consumers": [
    {
      "consumer_id": "00000000-0000-4000-b000-000000000002",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "consumer_id": "00000000-0000-4000-b000-00000000000c",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 2
}

$ curl -s \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
"$ZSM_HOST/api/consumers?page=2&page_size=2" | jq
{
  "consumers": [
    {
      "consumer_id": "00000000-0000-4000-b000-00000000000d",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    }
  ],
  "total": 3,
  "page": 2,
  "page_size": 2
}

Get all Active Consumers Example

$ curl -s \
-H "Authorization: Bearer b59479e0-cd3b-4c00-9a7a-fde7e3e1cc3e" \
$ZSM_HOST/api/consumers?state="active" | jq
{
  "consumers": [
    {
      "consumer_id": "00000000-0000-4000-b000-000000000002",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "consumer_id": "00000000-0000-4000-b000-00000000000c",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    },
    {
      "consumer_id": "00000000-0000-4000-b000-00000000000d",
      "state": "active",
      "created": "2023-06-21 14:17:15.715498 +00:00",
      "modified": "2023-06-21 14:17:15.715498 +00:00"
    }
  ],
  "total": 3,
  "page_size": 100
}

ZSM SaaS Server (v2.3)

Consumers

Add a Consumer

View a Consumer

Activate Consumer

Suspend Consumer

Retrieve Consumers

Get All Consumers

Get all Active Consumers Example