Partner API for AI Business Solutions & Security Insights API migration guide from v1.3 to v1.5

Note

This API provides access to the AI Business Solutions & Security Insights report. For all other Partner Center data scenarios, see Partner Center REST APIs.

ASPX API Migration Guide (v1.3 → v1.5)

This guide provides step-by-step instructions to migrate from API version 1.3 to version 1.5. Version 1.5 introduces improvements in performance and efficiency by reducing the number of API calls required and simplifying how data is retrieved.

For the full set of v1.5 endpoints, parameters, response schemas, and sample requests, see the ASPX API Endpoint Reference.

Note

Version v1.3 will reach end of support on August 30, 2026. After this date, it will no longer be available. To maintain uninterrupted service, we recommend moving to v1.5.

Step 1: Replace Grid Calls (Version + Path Updates)

v1.3 v1.5
GET /v1.3/api/opportunities/copilot GET /v1.5/api/opportunities/copilot
GET /v1.3/api/opportunities/categories/{opportunityCategoryId}/Workloads GET /v1.5/api/opportunities/secureproductivity?category={categoryId}
GET /v1.3/api/cloudEndpoints/tenants GET /v1.5/api/opportunities/cloudEndpoints

Valid category/categoryId values are E3Opportunities, E5Opportunities, and E5ExpansionOpportunities.

Note

v1.3's "Workload" opportunities are called Secure Productivity opportunities in v1.5 — same data, new name (reflected in the secureproductivity path segment).

Step 2: Consolidate Filter and Summary Calls

In v1.3, multiple API calls were required to retrieve grid data, summaries, and filters. In v1.5, this can be done in a single request using the include parameter.

Before (v1.3)

GET /v1.3/api/opportunities/copilot?page=1&pageSize=25
GET /v1.3/api/opportunities/copilot/summary
GET /v1.3/api/opportunities/copilot/filters/adoptionStatuses
GET /v1.3/api/opportunities/copilot/filters/tenantCountries

After (v1.5)

GET /v1.5/api/opportunities/copilot?page=1&pageSize=25&include=filters,summaries

Step 3: Optimize Payload with Field Selection

Reduce response size by requesting only the columns you need.

GET /v1.5/api/opportunities/copilot?fields=tenantName,tenantId,copilotLicenses,adoptionStatus

Step 4: Use POST for Large Filter Sets

/opportunities/copilot, /opportunities/secureproductivity, and /opportunities/cloudEndpoints each accept a POST with the identical filter set as JSON in the request body — useful if your filter combination would otherwise exceed URL length limits. Response shape, status codes, and the include parameter behave identically to GET.

POST /v1.5/api/opportunities/copilot
Content-Type: application/json

{ "include": "filters,summaries", "tenantCountries": ["US", "CA", "GB", ...] }

Step 5: Migrate Async/Bulk Exports

In v1.3, large downloads required a separate v1.4 async export endpoint with its own polling loop. In v1.5, this is folded into the same grid endpoint via output=async:

GET /v1.5/api/opportunities/copilot?output=async&format=jsonl&compressAsZip=true

The response returns a requestId. Poll GET /v1.5/api/exports/status/{requestId} until the status is Completed, then download from GET /v1.5/api/exports/download/{requestId} — no separate export endpoint or job type to manage. This applies to all three consolidated endpoints (copilot, secureproductivity, cloudEndpoints).

Note

Sync grid calls (default and output=sync) are subject to a 429 Too Many Requests rate limit under heavy load. Async export mode (output=async) is not rate-limited — this method is preferred for bulk/scheduled data pulls.

Step 6: Use ETag for Freshness Checks

Avoid unnecessary data pulls by validating whether data has changed before issuing grid requests:

  1. GET /v1.5/api/metadata → Save the ETag from the response headers
  2. Next request: GET /v1.5/api/metadata with header If-None-Match: <saved-etag>
  3. If response is 304 Not Modified → Data has not changed; skip grid calls
  4. If response is 200 OK → Data has been refreshed; proceed with grid calls

Support

If you encounter issues with onboarding or API access, contact our support team at: PXPartnerSupport@microsoft.com

Include the following information:

  • Partner name
  • MPN IDs
  • Tenant ID for your program membership
  • A brief description of your problem
  • Last updated on