{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":34608,"path":"manufacturing/warranty-claims-SOAP-API.md","title":"Warranty Claims SOAP API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Warranty Claims SOAP API\n\nThe Warranty Claims SOAP API handles incoming repair orders from dealer systems and converts them into warranty claims within the Original Equipment Manufacturer \\(OEM\\)’s platform.\n\nThis API follows [SOAP 1.1 conventions](https://www.w3.org/TR/2000/NOTE-SOAP-20000508/) and uses [Standards for Technology in Automotive Retail \\(STAR\\) XML schemas](https://https://schemas.liquid-technologies.com/star/5.3.4/repairorder_xsd.html/star/5.3.4/?page=processsaleslead_xsd.html) for interoperability across automotive service systems.\n\nThis API enables the exchange of warranty and repair claim information between ServiceNow Manufacturing Commercial Operations \\(MCO\\) and a Dealer Management System \\(DMS\\). Specifically, it allows users to:\n\n- Create and validate warranty claims in the DMS directly from ServiceNow MCO.\n- Query the status of submitted claims, including adjudication and approval outcomes, and retrieve those results back into ServiceNow.\n- Manage repair claim data across three core MCO tables:\n - Repair Claim Case \\[sn\\_repair\\_claim\\_mgmt\\_case\\]\n - Repair Claim Case Line \\[sn\\_repair\\_claim\\_mgmt\\_case\\_line\\]\n - Repair Claim Case Line Charge \\[sn\\_repair\\_claim\\_mgmt\\_case\\_line\\_charge\\]\n- Support STAR XML message formats through configuration‑driven adapters, enabling standards‑based integrations without custom code.\n\nThis documentation is intended for developers, system integrators, and partners implementing a standards-based SOAP integration.\n\n## Standards and conventions\n\nThe API adheres to widely used, publicly documented standards.\n\n|Item|Standard|\n|----|--------|\n|SOAP version|SOAP 1.1 \\(default\\); 1.2 supported for select partners|\n|WSDL|WSDL 1.1|\n|XML schema|XSD 1.0 \\(STAR XML\\)|\n|STAR schema version|5.13.4|\n|Character encoding|UTF-8|\n|Message format|`text/xml`|\n|Protocols|HTTPS over TLS 1.2+; optional Mutual TLS for STAR partners|\n\n## Access and authentication\n\n- Basic Auth \\(username/password\\)\n- Configurable per endpoint for every DMS\n\n## Granular roles and entities\n\nThis SOAP API requires granular roles to access certain MCO features and responsibilities, provide CRU permissions without custom ACLs, and map directly to supported entities. See [Granular roles and entities](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/manufacturing/mco-granular-roles-and-entities.md) for information about supported granular roles.\n\n## Endpoint details\n\nThe Warranty Claims SOAP API is exposed as a scripted SOAP Web service in ServiceNow MCO.\n\n```\nhttps://.service-now.com/sn_mco_integ_RepairClaimSOAPHandler.do?SOAP\n```\n\nWSDL:\n\n```\nhttps://.service-now.com/sn_mco_integ_RepairClaimSOAPHandler.do?WSDL\n```\n\nThe instance name is fixed per OEM environment \\(sandbox, test, production\\).\n\n|URL part|Description|\n|--------|-----------|\n|``|The ServiceNow instance hosting MCO \\(OEM‑specific, fixed per OEM\\).|\n|`sn_mco_integ_`|MCO integration namespace.|\n|`RepairClaimSOAPHandler.do`|Scripted SOAP Web service entry point.|\n|`?SOAP`|SOAP invocation.|\n|`?WSDL`|WSDL contract for client generation.|\n\n## API operation\n\nOperation Name: `ProcessRepairOrder`\n\nProcesses a repair order payload. The operation performs either a create or update action depending on whether a matching business identifier already exists.\n\nThis operation:\n\n- Validates the request against the STAR schema.\n- Validates that values in XML are valid in MCO.\n- Determines whether the repair claim \\(document ID\\) already exists.\n- Creates a new record if no match is found.\n- Updates an existing record if a match is found.\n- Returns a processing status and reference identifier.\n\n## Request structure\n\nThe request body contains a STAR-conforming `ProcessRepairOrder` message wrapped in a SOAP envelope. Key logical elements include:\n\n- Application metadata \\(sender, creation time, destination\\).\n- Process verb indicating the requested action.\n- Repair order header information.\n- Vehicle details.\n- Job, labor, parts, and pricing details.\n- Warranty claim information.\n\nAll elements must conform to the STAR XML schema version indicated in the payload.\n\n## Request parameters\n\n\n
\n\nName\n\n\n\nLabel\n\n\n\nDescription\n\n
\n\nActivity status\n\n\n\nactivity\\_status\n\n\n\nRequired. Indicates the current life-cycle status of the repair claim case line and drives playbook execution.Table: Repair Claim Case Line \\[sn\\_repair\\_claim\\_mgmt\\_case\\_line\\]\n\nValid values:\n\n- Claim details completed \\[claim\\_details\\_completed\\]\n- Claim jobs completed \\[claim\\_jobs\\_completed\\]\n- Claim under review completed \\[claim\\_under\\_review\\_completed\\]\n- Claim job edit completed \\[claim\\_job\\_edit\\_completed\\]\n- Claim summary completed \\[claim\\_summary\\_completed\\]\n- Close case completed \\[close\\_case\\_completed\\]\n\nData type: Choice \\(string\\)\n\n
\n\nActual end\n\n\n\nactual\\_end\n\n\n\nOptional. Date and time when the repair activity was completed.Format: YYYY-MM-DDThh:mm:ss\n\nData type: DateTime \\(string\\)\n\n
\n\nActual start\n\n\n\nactual\\_start\n\n\n\nOptional. Date and time when the repair activity started.Format: YYYY-MM-DDThh:mm:ss\n\nData type: DateTime \\(string\\)\n\n
\n\nAsset\n\n\n\nasset\n\n\n\nRequired. Serial number or asset tag of the claim.Table: Asset \\[alm\\_asset\\]\n\nData type: Reference \\(string\\)\n\n
\n\nCausal part\n\n\n\nproduct\\_model\n\n\n\nRequired. Model number of the part identified as the root cause of the issue.Table: Product model \\[cmdb\\_model\\]\n\nData type: Reference \\(string\\)\n\n
\n\nClaimed amount\n\n\n\nclaimed\\_amount\n\n\n\nOptional. Claimed cost amount for this specific repair claim case line.Data type: Currency \\(string\\)\n\n
\n\nConsumer\n\n\n\nconsumer\n\n\n\nOptional. Consumer or vehicle owner. If consumer ID is unavailable, phone number or email may be provided. Table: Consumer \\[csm\\_consumer\\]\n\nData type: Reference \\(string\\)\n\n
\n\nCorrelation ID\n\n\n\ncorrelation\\_id\n\n\n\nOptional. External correlation identifier used to link this request with upstream or downstream systems.Data type: String\n\n
\n\nDealer\n\n\n\nrequesting\\_service\\_organization\n\n\n\nRequired. Reference to the service organization \\(dealer\\) submitting the request.Internally resolves to a Service Organization \\[sn\\_customer\\_service\\_organization\\] record, matched by Number.\n\nData type: Reference \\(string\\)\n\n
\n\nDeductible amount\n\n\n\ndeductible\\_amount\n\n\n\nOptional. Deductible amount applicable to the repair claim.Data type: Currency \\(string\\)\n\n
\n\nExternal Repair order number\n\n\n\nexternal\\_ro\\_number\n\n\n\nRequired. Repair order number from the external dealer or service system.Data type: String\n\n
\n\nFault code\n\n\n\nfault\\_code\n\n\n\nOptional. Fault or diagnostic code associated with the reported issue.Data type: String\n\n
\n\nInstall base\n\n\n\ninstall\\_base\n\n\n\nOptional. Identifies the product or asset being serviced and is resolved by matching the provided value to an existing Install Base Item in ServiceNow.Table: Install base \\[sn\\_install\\_base\\_item\\]\n\nValid values:\n\n- asset number\n- serial number\n- name\n\nData type: Reference \\(string\\)\n\n
\n\nPart in warranty\n\n\n\nin\\_warranty\n\n\n\nRequired. Flag that indicates whether the affected part is under warranty.Valid values:\n\n- `true`: Affected part is under warranty.\n- `false`: Affected part isn't under warranty.\n\nData type: Boolean\n\n
\n\nVehicle in warranty\n\n\n\nvehicle\\_in\\_warranty\n\n\n\nRequired. Flag that indicates whether the vehicle is under warranty.Valid values:\n\n- `true`: Vehicle is under warranty.\n- `false`: Vehicle isn't under warranty.\n\nData type: Boolean\n\n
\n\nIssue Description\n\n\n\nshort\\_description\n\n\n\nRequired. Brief summary of the issue.Data type: String\n\n
\n\nParent task\n\n\n\nparent\\_task\n\n\n\nRequired. Identifier of an existing parent repair claim case or parent task associated with the request.Table: Task \\[task\\]\n\nData type: Reference \\(string\\)\n\n
\n\nPre-auth case line\n\n\n\npre\\_auth\\_case\\_line\n\n\n\nOptional. Corresponding pre‑authorization repair request, if applicable.Table: Pre‑Auth Repair Request Job \\[sn\\_pre\\_auth\\_repair\\_request\\_job\\], Field: Number\n\nData type: Reference \\(string\\)\n\n
\n\nProduct Usage\n\n\n\nproduct\\_usage\n\n\n\nRequired. Usage reading of the vehicle at time of repair \\(for example, kilometers or miles driven\\).Data type: Number \\(decimal\\)\n\n
\n\nQuantity\n\n\n\nquantity\n\n\n\nRequired. Number of affected or replaced parts.Data type: Number \\(decimal\\)\n\n
\n\nRepair action\n\n\n\nrepair\\_action\n\n\n\nRequired. Action performed to resolve the issue.Valid values:\n\n- Repair \\[REPAIR\\]\n- Replacement \\[REPLACEMENT\\]\n- Software update \\[SOFTWARE\\_UPDATE\\]\n\nData type: Choice \\(string\\)\n\n
\n\nRepair Claim case\n\n\n\nparent\\_case\n\n\n\nRequired. Repair claim case associated with this case line.Table: Customer case \\[sn\\_customerservice\\_case\\]\n\n
\n\nRepair Details\n\n\n\ndetails\n\n\n\nRequired. Detailed description of the issue, diagnostics, and repair performed.Data type: Translated HTML\n\n
\n\nReplacement part\n\n\n\nreplacement\\_part\n\n\n\nConditional. If **repair\\_action** = `replacement`, specifies the name or model number of the replaced part.Table: Product model \\[cmdb\\_model\\]/Name/Model Number\n\nData type: Reference \\(string\\)\n\n
\n\nReported date\n\n\n\nreported\\_date\n\n\n\nRequired. Date and time the vehicle arrived at the dealer or service center.Format: YYYY-MM-DDThh:mm:ss\n\nData type: DateTime\n\n
\n\nSource\n\n\n\nsource\n\n\n\nOptional. Originating system or channel that submitted the repair claim request.Data type: String\n\n
\n\nSubmitted\n\n\n\nsubmitted\\_at\n\n\n\nRequired. Date and time the claim was submitted.Format: YYYY-MM-DDThh:mm:ss\n\nData type: DateTime\n\n
\n\nTotal claimed amount\n\n\n\ntotal\\_claimed\\_amount\n\n\n\nRequired. Total claimed amount for the entire repair claim case.Data type: Currency \\(string\\)\n\n
\n\nType\n\n\n\ntype\n\n\n\nRequired. Type of claim being submitted.Valid values:\n\n- Warranty \\[Warranty\\]\n- Goodwill \\[Goodwill\\]\n- Service contract \\[Servicecontract\\]\n\nData type: Choice \\(string\\)\n\n
\n\nUnit of measure\n\n\n\nunit\\_of\\_measure\n\n\n\nRequired. Unit of measurement for the product usage. For example, kms or miles.Table: Unit of Measure \\[sn\\_prd\\_pm\\_uom\\]\n\nData type: Reference \\(string\\)\n\n
\n\nWork notes\n\n\n\nwork\\_notes\n\n\n\nOptional. Internal notes or comments related to claim processing.Data type: String\n\n
## Example SOAP request\n\n**Note:** Namespaces used in examples follow standard SOAP and STAR conventions.\n\n```\n\n\n\n \n \n \n \n \n \n\n \n \n \n \n\n \n \n \n DealerManagementSystem\n DEALER001\n https://dealer-system.example.com\n 98765\n ST-001\n REGION-01\n US\n en-US\n DMS_v6.1.0\n \n\n 2026-01-09T14:30:45\n a1b2c3d4-e5f6-7890-abcd-ef1234567890\n\n \n OEM_MANUFACTURER\n \n \n\n \n \n \n ADD\n \n\n \n \n \n \n RO-2026-987654qwert\n \n \n\n```\n\nExample SOAP response \\(success\\)\n\n```\n\n\n \n \n success\n Repair order processed successfully\n {\"reference\":\"RPC0001005\"}\n \n \n\n\n```\n\nExample SOAP response \\(validation error\\)\n\n```\n\n \n \n error\n \n VALIDATION ERRORS\n payload=\"[{\\\"field\\\":\\\"asset\\\",\\\"message\\\":\\\"Reference value not found\\\"}]\"\n \n \n \n\n\n```\n\n## Error handling\n\nThe API uses standard SOAP and HTTP mechanisms to report errors like SOAP faults, custom business errors, and HTTP status codes.\n\nSOAP faults are returned when the request can't be parsed or processed at the protocol level, such as when:\n\n- XML is malformed\n- Namespace is incorrect\n- Required SOAP envelope structure missing\n- Authentication failure\n- System-level processing error\n\nExample SOAP Fault:\n\n```\n\n soap:Client\n Invalid SOAP message\n\n\n```\n\n## Custom business errors\n\nBusiness validation errors occur after successful SOAP parsing and indicate issues with request data, such as:\n\n- Missing or invalid references\n- Duplicate repair orders\n- Invalid code values\n- Schema or version mismatches\n\nThese occur after successful SOAP parsing but during business validation. Errors are returned in the operation response with a status of `error` and a descriptive message. Possible errors:\n\n- MANDATORY\\_FIELD\\_MISSING\n- MIN\\_VALUE MAX\\_VALUE INVALID\\_REFERENCE\n- UNSUPPORTED\\_VALIDATION\\_TYPE\n- SOAP\\_ENVELOPE\\_EMPTY\n- IN\\_WARRANTY\\_TRANSFORM\\_FAILED\n- VALIDATION\\_ERRORS\n- INVOKE\\_PROCESSOR\\_FAILED\n- INVALID\\_DATE\\_FORMAT\n- INVALID\\_DATE\\_VALUE\n- INVALID\\_DATETIME\\_FORMAT\n- XML\\_TO\\_JSON\\_FAILED\n- INVALID\\_DATETIME\\_VALUE\n- PAYLOAD\\_PARSING\\_FAILED\n- EMPTY\\_PARSED\\_PAYLOAD\n- INVALID\\_TRANSLATED\\_HTML\\_TYPE\n- MAX\\_LENGTH\\_EXCEEDED\n- MAIN\\_PART\\_MISSING\n- MULTIPLE\\_MAIN\\_PARTS\n\nSample error code:\n\n```\n \nerror \nVALIDATION ERRORS | payload=\"[{\\\"field\\\":\\\"asset\\\",\\\"message\\\":\\\"Reference value not found\\\"}]\" \n \n\n\n```\n\n## HTTP Status Codes\n\n|HTTP Code|Description|\n|---------|-----------|\n|200|OK - Request processed successfully.|\n|400|Bad Request - Invalid or malformed request.|\n|401|Unauthorized - Authentication failure.|\n|403|Forbidden - Access not permitted.|\n|500|Internal Server Error - Unexpected processing failure.|\n\n## Outbound STAR Integration\n\nThis outbound integration sends claim adjudication and payment results from the OEM Now ServiceNow instance to a Dealer Management System \\(DMS\\) using STAR‑compliant XML messages.\n\nThe integration is triggered by a ServiceNow Business Rule on the Repair Claim Case table \\(sn\\_repair\\_claim\\_mgmt\\_case\\) when:\n\n- The claim source is DMS\n- The claim state is one of the following:\n - Approved\n - Partially Approved\n - Rejected\n - Awaiting Information\n\n\n
\n\nName\n\n\n\nLabel\n\n\n\nDescription\n\n
\n\nApproved amount\n\n\n\napproved\\_amount\n\n\n\nRequired. Approved amount for this specific repair claim case line after adjudication.Data type: Currency\n\n
\n\nCorrelation ID\n\n\n\ncorrelation\\_id\n\n\n\nRequired. Unique identifier used to correlate the outbound response with the original inbound repair claim request.Data type: String\n\n
\n\nExternal repair order number\n\n\n\nexternal\\_ro\\_number\n\n\n\nRequired. External repair order number associated with the Repair Claim case, as provided by the dealer system.Data type: String\n\n
\n\nDealer ID\n\n\n\ndealer\\_number\n\n\n\nRequired. Unique identifier of the dealer or service organization that submitted the repair claim.Data type: String\n\n
\n\nReview action\n\n\n\nreview\\_action\n\n\n\nRequired. Action taken by the claims agent during the claim review.Possible values:\n\n- Approve all \\[approve\\_all\\]\n- Reject all \\[reject\\_all\\]\n- Partially approved \\[partially\\_approved\\]\n- Send back \\[send\\_back\\]\n\nData type: Choice \\(string\\)\n\n
\n\nReview comments\n\n\n\nreview\\_comments\n\n\n\nOptional. Comments entered by the claims agent during the review and adjudication process.Data type: Translated Text\n\n
\n\nService organization\n\n\n\nservice\\_organization\n\n\n\nRequired. Name of the dealer or service organization associated with the repair claim.Data type: String\n\n
\n\nState\n\n\n\nstate\n\n\n\nRequired. Overall adjudication state of the Repair Claim case at the time of response.Possible values:\n\n- 0 - Draft\n- 1 - New\n- 2 - Open\n- 5 - Pending review\n- 6 - Awaiting info\n- 8 - Approved\n- 9 - Partially approved\n- 10 - Rejected\n- 3 - Closed complete\n- 7 - Closed incomplete\n- 4 - Closed cancelled\n\nData type: Choice \\(string\\)\n\n
\n\nTotal approved amount\n\n\n\ntotal\\_approved\\_amount\n\n\n\nRequired. Total approved amount for the entire Repair Claim case, aggregated across all case lines.Data type: Currency\n\n
|Status|STAR status code|Decision indicator|\n|------|----------------|------------------|\n|AWAITING\\_INFO|6|R \\(Rejected\\)|\n|APPROVED|8|A \\(Approved\\)|\n|PARTIALLY\\_APROVED|9|A \\(Approved\\)|\n|REJECTED|10|D \\(Denied\\)|\n\nWhen these conditions are met, ServiceNow generates and sends a STAR `ProcessServiceProcessingAdvisory` message to the DMS. The outbound STAR message communicates claim adjudication outcomes, not claim submission data. The message includes:\n\n- The repair order or claim reference\n- Overall claim status\n- Total payable or approved amounts\n- Approved amounts at the individual job or operation level\n\nThe message conforms to the STAR `ProcessServiceProcessingAdvisory` structure and enables the DMS to synchronize claim status and financial reconciliation data.\n\nOutbound sample payload:\n\n```\n\n \n \n Beta Consulting Group Orlando\n DLR0001001\n \n 2026-02-26T11:54:25\n \n \n \n \n \n \n \n \n RO-2026-987654qwe1111\n \n \n \n \n \n 342744.29\n Pending review\n \n \n \n \n \n \n 342744.29\n Pending review\n DIAG-ENG-01A1A1\n \n \n 0.00\n Pending review\n DIAG-ENG-011\n \n \n \n \n \n \n\n```\n\n## Logging and diagnostics\n\nRequests and responses are logged by the service for diagnostic and troubleshooting purposes in accordance with standard ServiceNow operational practices.\n\n## Related specifications\n\n- STAR XML Specifications\n- SOAP 1.1 Specification\n- WSDL 1.1 Specification\n\nRefer to the official STAR and W3C documentation for detailed schema and protocol definitions.\n\n**Parent Topic:**[MCO Integration APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/manufacturing/manufacturing-integrate.md)\n\n"}}