Wiv MSP Customers and Cases Fetching

Modified on Thu, 25 Sep, 2025 at 9:34 AM

Overview

The MSP API allows you to manage customers and search their cases.
This article provides details about the available endpoints, request parameters, pagination, and example responses.

Prerequisites: Obtaining API Key

Endpoints

[GET] api.wiv.ai/msp/customers

Retrieve a list of all customers managed by the MSP.
Supports field selection for optimized performance.

Authentication

Requires valid API Key authentication credentials.

Query Parameters

Parameter	Type	Description	Example
`fields` (optional)	string	Comma-separated list of fields to include in the response. If omitted, all fields are returned.	`id,name`

Available Fields

Field Name	Response Key	Description
`id`	`customer_id`	Unique customer ID
`name`	`customer_name`	Customer organization name
`users_number`	`users_number`	Number of users in the organization
`active_workflows`	`active_workflows`	Count of active workflows
`cost_impact`	`cost_impact`	Financial cost impact
`realized_savings`	`realized_savings`	Total realized savings
`num_of_integrations`	`num_of_integrations`	Number of integrations
`integration_types`	`integration_types`	Integration types available
`integrations`	`integrations`	Detailed list of integrations
`successful_runs`	`successful_runs`	Successful workflow runs
`failed_runs`	`failed_runs`	Failed workflow runs

Request Examples

All customer data
```
GET /msp/customers
```
Specific fields
```
GET /msp/customers?fields=id,name
```

Error Responses

Status	Example
400 Bad Request	`{"error": "Invalid fields requested"}`
401 Unauthorized	`{"error": "Authentication required"}`
500 Internal Server Error	`{"error": "Internal server error"}`

Performance Considerations

Use field selection to reduce payload size.

[POST] api.wiv.ai/v2/cases/msp/search

Search cases across all MSP customers or for a specific customer. Supports filtering and pagination.

Authentication

Requires valid API Key authentication credentials.

Query Parameters

Parameter	Type	Description	Example
`customer_id`	string	Filter cases for a specific customer.	`?customer_id=org_12345`

Request Body Parameters (JSON)

Parameter	Type	Description
`date_range`	object	Start & end dates
`max_returned_items`	integer	Default: 250
`start_page_key`	object	Pagination key

Request Examples

Search all cases

POST /v2/cases/msp/search Content-Type: application/json 
{}

Specific customer

POST /v2/cases/msp/search?customer_id=CUSTOMER_ID 
Content-Type: application/json 
{
    "max_returned_items": 50
}

With filters and date range

{
    "date_range": {
        "start": "2024-01-01",
        "end": "2024-12-31"
    }
}

Pagination

Large case search results are returned in pages.
The API uses a scroll-based pagination mechanism to deliver results consistently.

How it Works

Initial Request
- Send your search request with max_returned_items (default: 250).
- The response will include data (cases) and a next_page_key object if more results exist.
Fetching Next Page
- Copy the scroll_id from the response next_page_key.
- Provide it in your next request under start_page_key.scroll_id.
End of Results
- When there are no further results, "next_page_key": null is returned.

Request Example (Next Page)

POST /v2/cases/msp/search Content-Type: application/json 
{
    "max_returned_items": 25,
    "start_page_key": {
        "scroll_id": "FGluY2x1ZGVfY29u==..."
    }
}

Response Example (With Next Page Key)

{
    "data": [
        {
            "case_id": "case_12345",
            ....
            "customer_id": "org_12345",
            "customer_name": "Acme Corporation",
            "case_type": "EC2 Stopped Instances"
        }
    ],
    "next_page_key": {
        "scroll_id": "FGluY2x1Z==..."
    }
}

Key Notes

Opaque scroll ID: The scroll_id is an encoded system token. Always use it as returned, without modification.
Consistency: The scroll ensures results are returned in a stable order during the pagination session.
Session scope: New cases created during an active scroll session may not appear until you start a new search.
Performance:
- Use page sizes of 25–100 items for UI-based pagination.
- Use larger page sizes (up to 500) for backend batch processing.

Error Responses

Status	Example
400 Invalid Request	`{"error": "Request body must be a dictionary"}`
401 Unauthorized	`{"error": "Authentication required"}`
500 Internal Server Error	`{"error": "Internal server error"}`

Apply specific date ranges in /cases/msp/search for faster responses.
Always use pagination for large result sets.
Cache frequently accessed queries where possible.

Rate Limits

Standard API rate limits apply. Contact your administrator for details.