openapi: 3.0.0 info: description: This is the OAS 3.0 specification for the Sophos Business Automation API. version: 1.12.0 contact: name: Sophos IT Integrations email: apis@sophos.com url: 'https://developer.sophos.com' title: Business Automation API tags: - name: Partners description: Manage partner information. - name: Pricing description: Manage pricing information. - name: Quotes description: Manage quotes. security: - bearerAuth: [] servers: - url: 'https://api.central.sophos.com/business-automation/v1' description: Global service in the production environment. paths: /quotes: get: summary: List quotes description: List quotes. Only approved quotes are returned at this time. x-soph-permissions: 'sfdc-quotes:read' operationId: listQuotes tags: - Quotes parameters: - name: X-Distributor-ID in: header description: Distributor ID. required: true schema: type: string - in: query name: type description: Quote type. required: false schema: description: Quote type. type: string enum: - new - amendment - renewal - in: query name: billingCategoryType description: Quote line billing category type. required: false schema: description: Quote line billing category type. type: string enum: - upfront - nonStandard - in: query name: autogenerated description: Whether to include only autogenerated quotes. required: false schema: type: boolean default: false - in: query name: createdByPartner description: >- Filters the response to send only the quotes created by a partner or only the quotes created by a non-partner. required: false schema: type: boolean default: false - in: query name: amendAndExtend description: >- Filters the response to send only the Amend and Extend quotes or only the quotes that are not for Amend and Extend. required: false schema: type: boolean default: false - in: query name: includeNFRQuotes description: >- Filters the response to include Not For Resale (NFR) quotes or to exclude NFR quotes. required: false schema: type: boolean default: false - in: query name: createdMinutesAgo description: Include quotes created within the past specified number of minutes. required: false schema: type: integer minimum: 1 - in: query name: approvedMinutesAgo description: Include quotes approved within the past specified number of minutes. required: false schema: type: integer minimum: 1 - in: query name: approvedFrom description: >- Include quotes approved from the specified datetime up to the current datetime. Can be used in conjunction with approvedTo. required: false schema: type: string format: date-time example: '2023-11-18T12:01:21Z' - in: query name: approvedTo description: >- Include quotes approved up to the specified datetime. Can be used in conjunction with approvedFrom. required: false schema: type: string format: date-time example: '2023-11-18T12:01:21Z' - in: query name: expiresWithinDays description: Include quotes expiring within the next specified number of days. required: false schema: type: integer minimum: 1 - in: query name: page description: Page to fetch starting with `1`. required: false schema: type: integer minimum: 1 - in: query name: pageSize description: Page size to use. required: false schema: type: integer minimum: 1 maximum: 500 responses: '200': description: List of quotes. headers: X-Correlation-ID: description: Header used to correlate requests. required: false schema: type: string format: uuid minLength: 36 maxLength: 36 pattern: >- ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ content: application/json: schema: description: Paged quote summaries. type: object properties: items: type: array items: description: Quote summary. type: object properties: proposalNumber: description: Proposal number. type: string example: Q-00001 type: description: Quote type. type: string enum: - new - amendment - renewal dealregNumber: description: Deal registration number. type: string example: DR20240106-000001 teamingRegNumber: description: Teaming registration number. type: string example: TP-987651 validUntil: description: Date when quote expires in `yyyy-mm-dd` format. type: string format: date example: '2024-02-13' autogenerated: description: >- Indicates whether the quote was autogenerated or manually created. type: boolean example: false amendAndExtend: description: >- Indicates whether the quote was for Amend and Extend. type: boolean example: false pages: type: object description: Page information. required: - current - size - maxSize properties: current: type: integer description: (Optional) The 1-based page number being returned. example: 1 total: type: integer description: (Optional) The total number of pages. example: 3 items: type: integer description: (Optional) The total number of items across all pages. example: 137 size: type: integer description: The size of the page being returned. example: 50 maxSize: type: integer description: The maximum page size that can be requested. example: 500 '400': description: Bad request. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' '500': description: Unexpected error. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' '/quotes/{proposalNumber}': get: summary: Get quote description: Get quote details by proposal number. x-soph-permissions: 'sfdc-quotes:read' operationId: getQuote tags: - Quotes parameters: - in: path name: proposalNumber description: Quote proposal number. required: true schema: type: string - name: X-Distributor-ID in: header description: Distributor ID. required: true schema: type: string responses: '200': description: Details of the requested quote. headers: X-Correlation-ID: description: Header used to correlate requests. required: false schema: type: string format: uuid minLength: 36 maxLength: 36 pattern: >- ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ content: application/json: schema: description: Details of a quote. type: object properties: proposalNumber: description: Proposal number. type: string example: Q-000009 opportunityId: description: Opportunity ID. type: string example: a10Va000006uPrVIAU type: description: Quote type. type: string enum: - new - amendment - renewal dealregNumber: description: Deal registration number. type: string example: DR20240106-000001 teamingRegNumber: description: Teaming registration number. type: string example: TP-987651 validUntil: description: Date when quote expires in `yyyy-mm-dd` format. type: string format: date example: '2024-02-13' paymentTerms: description: Payment terms. type: string example: Net 30 autogenerated: description: >- Indicates whether the quote was autogenerated or manually created. type: boolean example: false createdByPartner: description: Indicates whether the quote was created by a partner. type: boolean example: false amendAndExtend: description: Indicates whether the quote was for Amend and Extend. type: boolean example: false promotionalCodes: description: Promotion codes. type: array items: type: string example: GLOBAL_APX contact: type: object description: 'Contact information for distributor, partner, or end-user.' properties: firstName: type: string description: First name. example: John lastName: type: string description: Last name. example: Smith email: type: string format: email description: Email address. example: john.smith@example.com phone: type: string description: Phone number. example: '9111678231' mobile: type: string description: Mobile number. example: '6311628237' distributor: description: Distributor account company details. type: object properties: name: description: Company name. type: string example: 'Example Disti, Inc.' address: type: object description: 'Address of the distributor, partner, or end-user.' properties: address1: type: string description: Line 1 of the address. example: '1134 Lane, Eastwood' address2: type: string description: Line 2 of the address. example: New York 10001 city: type: string description: City. example: New York state: type: string description: State. example: NY countryCode: type: string description: Two-letter ISO country code. example: US postalCode: type: string description: Postal code. example: '10001' accountNumber: description: Account number. type: string minLength: 1 maxLength: 8 pattern: '^[0-9]+$' example: '12345678' partner: description: Partner account company details. type: object properties: name: description: Company name. type: string example: Acme Corp level: description: Partner level. type: string enum: - select - authorized - silver - gold - platinum example: gold accountNumber: description: Account number. type: string minLength: 1 maxLength: 8 pattern: '^[0-9]+$' example: '12345678' address: type: object description: 'Address of the distributor, partner, or end-user.' properties: address1: type: string description: Line 1 of the address. example: '1134 Lane, Eastwood' address2: type: string description: Line 2 of the address. example: New York 10001 city: type: string description: City. example: New York state: type: string description: State. example: NY countryCode: type: string description: Two-letter ISO country code. example: US postalCode: type: string description: Postal code. example: '10001' contact: type: object description: >- Contact information for distributor, partner, or end-user. properties: firstName: type: string description: First name. example: John lastName: type: string description: Last name. example: Smith email: type: string format: email description: Email address. example: john.smith@example.com phone: type: string description: Phone number. example: '9111678231' mobile: type: string description: Mobile number. example: '6311628237' endUserCustomer: description: End-user account company details. type: object properties: name: description: Company name. type: string example: Acme Corp accountNumber: type: string description: End-user account number. example: '42839221' address: type: object description: 'Address of the distributor, partner, or end-user.' properties: address1: type: string description: Line 1 of the address. example: '1134 Lane, Eastwood' address2: type: string description: Line 2 of the address. example: New York 10001 city: type: string description: City. example: New York state: type: string description: State. example: NY countryCode: type: string description: Two-letter ISO country code. example: US postalCode: type: string description: Postal code. example: '10001' contact: type: object description: >- Contact information for distributor, partner, or end-user. properties: firstName: type: string description: First name. example: John lastName: type: string description: Last name. example: Smith email: type: string format: email description: Email address. example: john.smith@example.com phone: type: string description: Phone number. example: '9111678231' mobile: type: string description: Mobile number. example: '6311628237' quoteLineItems: type: array items: description: Quote line item. type: object properties: productName: description: Product name. type: string example: XGS136 productDescription: description: Product description. type: string example: XGS 136 Email Protection startDate: description: Quote line item start date in ISO format. type: string format: date example: '2024-02-03' endDate: description: Quote line item end date in ISO format. type: string format: date example: '2024-02-03' existingLicenses: description: List of existing license IDs or serial numbers. type: array items: type: string example: C023716784 billingCategory: description: Quote line billing category. type: string example: Upfront sku: description: Sophos Stock Keeping Unit. type: string example: CEAZ1CSMG utmLicenseId: description: UTM license ID. type: string example: D12345678 term: description: Subscription term in months. type: integer example: 36 quantity: description: Product quantity. type: integer example: 10 currencyCode: description: Currency code. type: string example: USD unitMsrp: description: Manufacturer's suggested retail price per unit. type: number example: 180.24 msrp: description: >- Manufacturer's suggested retail price multiplied by the quantity. type: number example: 1802.4 additionalDiscountPercentage: description: Additional discount percentage. type: number example: 0 allowance: description: Allowance. type: number example: 0 specialTotal: description: Special total. type: number example: 1802.4 intermediateTierMargin: description: Intermediate tier margin. type: number example: 0 intermediateTierUnit: description: Intermediate tier unit. type: number example: 0 intermediateTierTotal: description: Intermediate tier total. type: number example: 1802.4 marginPercentage: description: Distributor discount margin percentage. type: number example: 0 unit: description: Unit net price. type: number example: 180.24 total: description: Line item total. type: number example: 1802.4 totals: description: Quote line item totals. type: object properties: currencyCode: description: Currency code. type: string example: USD msrpTotal: description: >- Sum of manufacturer's suggested total retail price for all quote lines. type: number example: 1802.4 specialTotal: description: Sum of special total for all quote lines. type: number example: 1802.4 intermediateTierTotal: description: Sum of intermediate tier total for all quote lines. type: number example: 1802.4 total: description: Sum of line item total for all quote lines. type: number example: 1802.4 '404': description: Can't find quote. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' '500': description: Unexpected error. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' /partners/level: get: summary: Return partner info description: Return partner information. x-soph-permissions: 'partner-info:read' operationId: getPartnerLevelInfo tags: - Partners parameters: - name: X-Distributor-ID in: header description: Distributor ID. required: true schema: type: string - in: query name: billingSubRegion description: Billing sub-region. required: true schema: type: string - in: query name: name description: Partner name. required: false schema: type: string - in: query name: updatedDate description: Date that the partner level was last updated. required: false schema: type: string format: date example: '2023-11-18' - in: query name: ediNumber description: Partner EDI account number. required: false schema: type: string - in: query name: page description: Page to fetch starting with `1`. required: false schema: type: integer minimum: 1 - in: query name: pageSize description: Page size to use. required: false schema: type: integer minimum: 1 maximum: 500 responses: '200': description: Details of the requested partner level data. headers: X-Correlation-ID: description: Header used to correlate requests. required: false schema: type: string format: uuid minLength: 36 maxLength: 36 pattern: >- ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ content: application/json: schema: description: Paged partner information summaries. type: object properties: items: type: array items: description: Partner information summary. type: object properties: accountName: description: Account name. type: string example: Account Test ediAccountNumber: description: EDI account number. type: string example: '9122312443' level: description: Current partner level. type: string example: gold updatedDate: description: Date when the partner level was last updated. type: string format: date example: '2024-02-13' createdDate: description: Date when the record was created. type: string format: date example: '2024-02-13' mspSubType: description: Level of MSP. type: string example: MSP billingCity: description: City that the partner resides in. type: string example: Lindale billingSubRegion: description: Region that the partner resides in. type: string example: USA territory: description: Account territory. type: string example: North America Partners managedBy: description: >- Account owner name, or "unmanaged" if the account owner is included in the configured unmanaged owners list. type: string example: NA West MSP pages: type: object description: Page information. required: - current - size - maxSize properties: current: type: integer description: (Optional) The 1-based page number being returned. example: 1 total: type: integer description: (Optional) The total number of pages. example: 3 items: type: integer description: (Optional) The total number of items across all pages. example: 137 size: type: integer description: The size of the page being returned. example: 50 maxSize: type: integer description: The maximum page size that can be requested. example: 500 '400': description: Bad request. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' '500': description: Unexpected error. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' /pricing: post: summary: Return pricing info description: Return pricing information. x-soph-permissions: 'sfdc-pricing:read' operationId: getPricingInfo tags: - Pricing parameters: - name: X-Distributor-ID in: header description: Distributor ID. required: true schema: type: string requestBody: description: Request object to retrieve pricing information. required: true content: application/json: schema: description: Pricing request. type: object required: - resellerAccountNumber - sector - lines properties: resellerAccountNumber: description: Account number. type: string minLength: 1 maxLength: 8 pattern: '^[0-9]+$' example: '12345678' transactionType: description: Transaction type. type: string enum: - new - renew sector: description: Sector. type: string enum: - corporate - education - government lines: type: array description: List of pricing lines. minItems: 1 maxItems: 6 items: description: Pricing line item request. type: object required: - productName - quantity - term properties: lineId: type: string description: Line ID. minLength: 1 example: LINE-001 productName: type: string description: Product code. minLength: 1 example: CIXA-U36STNDVF quantity: type: integer description: Quantity of the product. minimum: 1 maximum: 5000 example: 10 term: type: integer description: Term of the product in months. minimum: 1 maximum: 60 example: 12 discretionaryDiscountPercent: type: number description: >- Discretionary discount percentage that should be applied to the MSRP. minimum: 0 maximum: 100 example: 15.5 programmeDiscount: description: Programme discount. type: string enum: - dealReg - incumbent - teaming promoCodes: type: array description: List of applied promo codes. maxItems: 3 example: - PROMO10 items: type: string responses: '200': description: List of pricing information. headers: X-Correlation-ID: description: Header used to correlate requests. required: false schema: type: string format: uuid minLength: 36 maxLength: 36 pattern: >- ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$ content: application/json: schema: description: Pricing summary. type: object properties: distributor: description: Distributor account company details. type: object properties: name: description: Company name. type: string example: 'Example Disti, Inc.' address: type: object description: 'Address of the distributor, partner, or end-user.' properties: address1: type: string description: Line 1 of the address. example: '1134 Lane, Eastwood' address2: type: string description: Line 2 of the address. example: New York 10001 city: type: string description: City. example: New York state: type: string description: State. example: NY countryCode: type: string description: Two-letter ISO country code. example: US postalCode: type: string description: Postal code. example: '10001' accountNumber: description: Account number. type: string minLength: 1 maxLength: 8 pattern: '^[0-9]+$' example: '12345678' reseller: description: Partner account company details. type: object properties: name: description: Company name. type: string example: Acme Corp level: description: Partner level. type: string enum: - select - authorized - silver - gold - platinum example: gold accountNumber: description: Account number. type: string minLength: 1 maxLength: 8 pattern: '^[0-9]+$' example: '12345678' address: type: object description: 'Address of the distributor, partner, or end-user.' properties: address1: type: string description: Line 1 of the address. example: '1134 Lane, Eastwood' address2: type: string description: Line 2 of the address. example: New York 10001 city: type: string description: City. example: New York state: type: string description: State. example: NY countryCode: type: string description: Two-letter ISO country code. example: US postalCode: type: string description: Postal code. example: '10001' contact: type: object description: >- Contact information for distributor, partner, or end-user. properties: firstName: type: string description: First name. example: John lastName: type: string description: Last name. example: Smith email: type: string format: email description: Email address. example: john.smith@example.com phone: type: string description: Phone number. example: '9111678231' mobile: type: string description: Mobile number. example: '6311628237' currencyCode: type: string description: Currency ISO code for the pricing information. example: USD sector: description: Sector. type: string enum: - corporate - education - government transactionType: description: Transaction type. type: string enum: - new - renew msrp: type: number description: Pricebook price with applied multipliers. example: 1234.56 specialTotal: type: number description: Customer / End User price of all products. example: 999.99 intermediateTierTotal: type: number description: Reseller price of all products. example: 899.99 total: type: number description: Distributor price of all products. example: 799.99 lines: type: array description: List of pricing lines. items: description: Pricing line item. type: object properties: lineId: type: string description: Line ID. example: LINE-001 productName: type: string description: Product code. example: CIXA-U36STNDVF quantity: type: integer description: Quantity of the product. example: 10 term: type: integer description: Term of the product in months. example: 12 msrp: type: number description: >- Total Pricebook price with applied multipliers for the line. example: 100 unitMsrp: type: number description: >- Unit Pricebook price with applied multipliers for the line. example: 10 discretionaryDiscountPercent: type: number description: Discretionary Discount Percent. example: 15.5 promoDiscountPercentage: type: number description: Promotional Discount Percent. example: 10 promoDiscountAmount: type: number description: Promotional Discount Amount. example: 12.34 intermediateTierMargin: type: number description: Reseller Margin. example: 7.5 marginPercentage: type: number description: Distributor Margin. example: 4 specialUnitPrice: type: number description: Customer / End User Unit Price. example: 15 specialTotal: type: number description: Customer / End User Total Price. example: 150 intermediateTierUnit: type: number description: Reseller Unit Price. example: 13 intermediateTierTotal: type: number description: Reseller Total Price. example: 130 unit: type: number description: Distributor Unit Price. example: 12 total: type: number description: Distributor Total Price. example: 120 sku: type: string description: Sophos Stock Keeping Unit. example: XYZITA00123 messages: type: array description: >- List of info/warning/error messages related to the line item pricing. items: description: Collection of info/warning/error messages. type: object properties: type: description: Message type. type: string enum: - info - warning - error message: type: string description: Message text. example: This is an informational message. promoCodes: type: array description: List of applied promo codes. example: - PROMO10 - DISCOUNT20 items: type: string messages: type: array description: List of info/warning/error messages related to this line. items: description: Collection of info/warning/error messages. type: object properties: type: description: Message type. type: string enum: - info - warning - error message: type: string description: Message text. example: This is an informational message. '400': description: Bad request. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' '500': description: Unexpected error. content: application/json: schema: description: Error object. type: object required: - error properties: error: description: 'Error identifier. For example, notFound.' type: string example: notFound message: description: 'Error message. For example, Object not found.' type: string example: Object not found correlationId: description: Correlation ID or tracking ID. type: string example: f97086bb-22bf-4935-9e57-91b23c0ef118 format: uuid code: description: 'Unique error code. For example, E1348921.' type: string example: E1348921 createdAt: description: Date and time when the error happened in ISO format. type: string format: date-time example: '2024-02-03T14:55:45Z' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT