{ "openapi": "3.0.1", "info": { "title": "Market Basket API", "description": "Requests, tracks and downloads PL CPQ Market Basket rate exports. All paths are tenanted by organization and agency; the caller must hold a profile for the agency in the path.", "version": "v1.0" }, "servers": [ { "url": "https://api.zywave.com" } ], "security": [], "paths": { "/v3/quoting/personalLines/v1/org/{orgId}/agency/{agencyId}/marketBasket/exports": { "post": { "tags": [ "Exports" ], "summary": "Exports — create an export request for the agency (one export per state x rate source x line of business).", "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "$ref": "#/components/parameters/agencyId" } ], "security": [ { "oauth2": [ "api.marketBasket" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "responses": { "202": { "description": "Accepted — the exports are queued for generation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v3/quoting/personalLines/v1/org/{orgId}/agency/{agencyId}/marketBasket/exports/search": { "get": { "tags": [ "Exports" ], "summary": "Exports — search and list the agency's exports, with paging, sorting and filters (status included per export).", "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "$ref": "#/components/parameters/agencyId" }, { "name": "terms", "in": "query", "description": "Free-text search.", "schema": { "type": "string" } }, { "name": "show_expired", "in": "query", "description": "Include expired exports. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "export_type", "in": "query", "description": "Filter by export type. Comma-separated or repeated.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExportType" } } }, { "name": "status", "in": "query", "description": "Filter by status. Comma-separated or repeated.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExportStatus" } } }, { "name": "requested_by", "in": "query", "description": "Filter by requester (user principal id).", "schema": { "type": "string" } }, { "name": "rate_source", "in": "query", "description": "Filter by rate source. Comma-separated or repeated.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RateSource" } } }, { "name": "state", "in": "query", "description": "Filter by 2-letter state code. Comma-separated or repeated.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "lob", "in": "query", "description": "Filter by line of business. Comma-separated or repeated.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LineOfBusiness" } } }, { "name": "export_date_range_start", "in": "query", "description": "Earliest export date (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "export_date_range_end", "in": "query", "description": "Latest export date (inclusive).", "schema": { "type": "string", "format": "date" } }, { "name": "sort_by", "in": "query", "description": "Sort column. Defaults to requested_at.", "schema": { "type": "string", "enum": [ "requested_at", "export_type", "status", "export_date_range", "requested_by", "rate_source", "state", "lob" ], "default": "requested_at" } }, { "name": "sort_direction", "in": "query", "description": "Sort direction. Defaults to desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "page", "in": "query", "description": "One-based page number. Defaults to 1.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Page size. Defaults to 25.", "schema": { "type": "integer", "format": "int32", "default": 25 } } ], "security": [ { "oauth2": [ "api.marketBasket" ] }, { "oauth2": [ "api.marketBasket:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSearchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v3/quoting/personalLines/v1/org/{orgId}/agency/{agencyId}/marketBasket/exports/{exportId}/status": { "get": { "tags": [ "Exports" ], "summary": "Exports — status of a single export (PENDING, PROCESSING, COMPLETE, FAILED).", "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "$ref": "#/components/parameters/agencyId" }, { "$ref": "#/components/parameters/exportId" } ], "security": [ { "oauth2": [ "api.marketBasket" ] }, { "oauth2": [ "api.marketBasket:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v3/quoting/personalLines/v1/org/{orgId}/agency/{agencyId}/marketBasket/exports/{exportId}/download-url": { "get": { "tags": [ "Exports" ], "summary": "Exports — presigned download link for a completed export.", "parameters": [ { "$ref": "#/components/parameters/orgId" }, { "$ref": "#/components/parameters/agencyId" }, { "$ref": "#/components/parameters/exportId" } ], "security": [ { "oauth2": [ "api.marketBasket" ] }, { "oauth2": [ "api.marketBasket:read" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDownloadUrlResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict — the export is not COMPLETE yet (error REPORT_NOT_READY).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportNotReadyProblemDetails" } } } } } } } }, "components": { "parameters": { "orgId": { "name": "orgId", "in": "path", "required": true, "description": "Organization id. Must match the caller's organization.", "schema": { "type": "string", "format": "uuid" } }, "agencyId": { "name": "agencyId", "in": "path", "required": true, "description": "Agency id. The caller must hold a profile for this agency.", "schema": { "type": "integer", "format": "int32" } }, "exportId": { "name": "exportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "ExportType": { "type": "string", "enum": [ "MARKETBASKET", "CARRIER", "BENEFITS_CARRIERS" ] }, "ExportStatus": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETE", "FAILED", "EXPIRED", "CANCELLED" ] }, "RateSource": { "type": "string", "description": "RATEAPI = Rate API, TR = TurboRater, TFW = TurboRater for Websites.", "enum": [ "RATEAPI", "TR", "TFW" ] }, "LineOfBusiness": { "type": "string", "description": "AUTO = Personal Auto, HOME = Homeowners.", "enum": [ "AUTO", "HOME" ] }, "FileFormat": { "type": "string", "enum": [ "CSV_WITH_QUOTES", "CSV", "PARQUET" ] }, "DeliveryMethod": { "type": "string", "enum": [ "DOWNLOAD", "SFTP" ] }, "ExportFrequency": { "type": "string", "enum": [ "ONCE", "RECURRING" ] }, "ExportRatesFor": { "type": "string", "enum": [ "CHOSEN_TIME_PERIOD", "LATEST_ITERATION" ] }, "DateRange": { "type": "object", "required": [ "type", "start_date", "end_date" ], "properties": { "type": { "type": "string", "enum": [ "CUSTOM" ] }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "description": "On or after start_date, and no more than 31 days after it." } } }, "ExportDateRange": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } } }, "ExportRequest": { "type": "object", "required": [ "export_type", "date_range", "rate_sources", "states", "lob", "file_format", "frequency", "export_date" ], "properties": { "export_type": { "$ref": "#/components/schemas/ExportType" }, "date_range": { "$ref": "#/components/schemas/DateRange" }, "rate_sources": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/RateSource" } }, "export_rates_for": { "$ref": "#/components/schemas/ExportRatesFor" }, "include_zero_premium": { "type": "boolean", "default": false }, "states": { "type": "array", "minItems": 1, "description": "2-letter state codes.", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "lob": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LineOfBusiness" } }, "file_format": { "$ref": "#/components/schemas/FileFormat" }, "delivery_method": { "$ref": "#/components/schemas/DeliveryMethod" }, "notify_email": { "type": "boolean", "default": false, "description": "Email the requester when the export is ready." }, "frequency": { "$ref": "#/components/schemas/ExportFrequency" }, "export_date": { "type": "string", "format": "date", "description": "Must be today's date (UTC)." } } }, "ExportItem": { "type": "object", "properties": { "exportId": { "type": "string", "format": "uuid" }, "state": { "type": "string" }, "rate_source": { "type": "string" }, "lob": { "type": "string" }, "date_range": { "$ref": "#/components/schemas/ExportDateRange" }, "export_date": { "type": "string", "format": "date" }, "status": { "$ref": "#/components/schemas/ExportStatus" } } }, "ExportResponse": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "requested_at": { "type": "string", "format": "date-time" }, "exports": { "type": "array", "items": { "$ref": "#/components/schemas/ExportItem" } } } }, "ExportSearchItem": { "type": "object", "properties": { "exportId": { "type": "string", "format": "uuid" }, "export_type": { "$ref": "#/components/schemas/ExportType" }, "state": { "type": "string" }, "rate_source": { "type": "string" }, "lob": { "type": "string" }, "date_range": { "$ref": "#/components/schemas/ExportDateRange" }, "export_date": { "type": "string", "format": "date" }, "delivery_method": { "$ref": "#/components/schemas/DeliveryMethod" }, "status": { "$ref": "#/components/schemas/ExportStatus" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ExportGroup": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "requested_by": { "type": "string", "description": "User principal id of the requester." }, "profile_id": { "type": "string" }, "profile_type": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "exports": { "type": "array", "items": { "$ref": "#/components/schemas/ExportSearchItem" } } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "format": "int32" }, "page_size": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } } }, "ExportSearchResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportGroup" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "ExportStatusResponse": { "type": "object", "properties": { "exportId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/ExportStatus" }, "submittedAt": { "type": "string", "format": "date-time" } } }, "ExportDownloadUrlResponse": { "type": "object", "properties": { "exportId": { "type": "string", "format": "uuid" }, "presigned_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link stops working." } } }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } } }, "ValidationProblemDetails": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } ] }, "ReportNotReadyProblemDetails": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "REPORT_NOT_READY" ] }, "exportStatus": { "$ref": "#/components/schemas/ExportStatus" } } } ] } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://sso.zywave.com/connect/authorize", "scopes": { "api.marketBasket": "View and manage your Market Basket export data", "api.marketBasket:read": "View your Market Basket export data" } } } } } } }