Skip to main content

​
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

​
Get Customers

[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

ParameterTypeDescriptionExample
fields (optional)stringComma-separated list of fields to include in the response. If omitted, all fields are returned.id,name

​
Available Fields

Field NameResponse KeyDescription
idcustomer_idUnique customer ID
namecustomer_nameCustomer organization name
users_numberusers_numberNumber of users in the organization
active_workflowsactive_workflowsCount of active workflows
cost_impactcost_impactFinancial cost impact
realized_savingsrealized_savingsTotal realized savings
num_of_integrationsnum_of_integrationsNumber of integrations
integration_typesintegration_typesIntegration types available
integrationsintegrationsDetailed list of integrations
successful_runssuccessful_runsSuccessful workflow runs
failed_runsfailed_runsFailed workflow runs

​
Request Examples

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

​
Error Responses

StatusExample
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.

​
Search MSP Cases

[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

ParameterTypeDescriptionExample
customer_idstringFilter cases for a specific customer.?customer_id=org_12345

​
Request Body Parameters (JSON)

ParameterTypeDescription
date_rangeobjectStart & end dates
max_returned_itemsintegerDefault: 250
start_page_keyobjectPagination key

​
Request Examples

  1. Search all cases
POST /v2/cases/msp/search
Content-Type: application/json

{}
  1. Specific customer
POST /v2/cases/msp/search?customer_id=CUSTOMER_ID
Content-Type: application/json

{
    "max_returned_items": 50
}
  1. 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

  1. 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.
  2. 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.
  3. 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

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

​
Best Practices

  • 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.