Service Partners Integration with Scalepoints ClaimShop

Introduction

This page describes on how to integrate Scalepoint's ClaimShop repair & valuation webservice with Service Partner's webservice. In order to share information about repair or valuation tasks, we exchange JSON documents containing all information about the task.

Authentication

To ensure that a specific task is coming from a certain Service Partner, we use a pre-shared key. This is basically a string in the form of a GUID, which only Scalepoint and the Service Partner knows about. It must be specified in every request to Scalepoints webservices. This pre-shared key will be sent using form-data. Similarly if the Service Partner will be providing a webservice for Scalepoint to call, Scalepoint will use this key on all requests to the webservice.

Integrations

In order to share information about repair or valuation tasks, we exchange JSON documents containing all information about the task. This exchange of information will be done in both ways, from scalepoint to service partner and vice versa

Overview

There are 3 Scalepoint endpoints:

  1. S1 (Required) – endpoint for task feedback and invoices
  2. S2 – endpoint for posting statuses (statuses can be arbitrary)
  3. S3 – endpoint for posting messages

And there should be 3 endpoints implemented on the Service Partner side

  1. SP1 (Required) – endpoint for posting repair tasks
  2. SP2 (Required) – endpoint for posting statuses
  3. SP3 – endpoint for posting messages

The process is the following:

  1. Scalepoint (S) sends a repair task with data about the damage items and customer to Service partner (SP) endpoint SP1
  2. SP evaluate the repair cost (it can be predefined or SP can request a damage item for valuation)
  3. During the valuation and repair process SP can send statuses about the current state of the process (to S2 endpoint). Statuses can be arbitrary. It is not required, but it will give more information about the process for the Scalepoint
  4. When SP is ready to provide a repair cost it sends a so called task feedback to Scalepoint (S1 endpoint) with the repair price or with reject reason if an item cannot be repaired. In most cases task feedback can be sent just right after receiving repair task, since task will provide all the needed data about the damage item. But it also can be sent later. Feedback can be sent more than once – the last feedback will be taken into account.
  5. Scalepoint receives a task feedback and approves it (or rejects) by sending corresponding status to Service partner endpoint SP2.
  6. After receiving approval SP does the repair
  7. After repair was implemented SP sends invoice to Scalepoint (endpoint S1). Invoice can be sent more than once. Only last invoice will be taken into account.
  8. Scalepoint approves the invoice
Integrating from Service Partner to Scalepoint

Integration between Scalepoint and external service partner will happen via REST Web service. For this purpose Scalepoint provide 3 different web service URLs. With the web service URLs external service partner able to publish below 3 different things.

  1. Publish modified repair & valuation tasks
  2. Publish the status of the task
  3. Publish a chat message

By using above 3 different web services a Service partner could call one of the web service URL when something changed on Service partner side. Detailed description about these 3 different web service URLs functionality are described below.

Integrating from Scalepoint to Service Partner

In order to send the repair and valuation tasks to Service partner, Scalepoint would expect that you provide us these 3 different web service URL’s. Before we start doing the integrations we need to exchange these 3 different web service URLS from Scalepoint to Service Partner and Service Partner to Scalepoint. We have clear description on how we publish tasks, statuses and chat messages. So it is very important that your Web services are able to accept Scalepoint tasks. Detailed description could be found below on how we publish tasks, statuses and chat messages.

Integrations from Service Partner to Scalepoint

When a task is completed, comments are made or otherwise modified, it should be sent back to Scalepoint. For this process we have a web service where the Service Partner can send their modified task documents.

Posting task feedback to Scalepoint

Posting feedback containing service lines and payment invoice to Scalepoint

| Request details | |--------|--- | | Url | https://hostname/repairValuation/country/ws/v3.1/task_feedback.action| | Hostname | The hostname part will vary depending on environment. Scalepoint will supply specific hostname for production and test environments. | | Country | The country part will vary depending on country of operation. Scalepoint will supply the correct country value. | | Method | POST |

| Request Headers | | --- |--- | | Content-Type | multipart/form-data | | Accept | application/JSON |

| Request form data | | --- |--- | | securityToken | Static GUID for service partner | | jsonString | JSON document string | | attachemtnName1 | Binary file | | …. | Binary file | | attachemtnNameN | Binary file |

Usage notes

There is an identifier for the task being sent to service partner (uniqueId attribute of serviceTask element). The same identifier must be included in JSON document.

ServiceTask element contains three elements:

  • serviceLines element is mandatory. It contains service lines received from Scalepoint. Lines that are not changed must be included in the feedback without changes. If line is not included it is considered to be removed from task.

    Note: feedback service lines are mapped to ClaimShop service lines by claimLineId attribute:

    • if feedback line includes claimLineId and it corresponds to the existing line in ClaimShop then this is treated as update operation;
    • if feedback line does not include claimLineId attribute, then it is treated as a new line (i.e. insert operation);
    • if in the feedback there is no corresponding line then it is treated as line removal (i.e. delete operation).

  • invoice element is the invoice for payment. It is not mandatory. It is used only when invoice is issued

    • InvoiceNumber is invoice identification. It is mandatory and should be unique

    • invoiceDate is a date when invoice/credit note is issued

    • paymentDueDate is a due date when invoice/credit note should be payed

    • invoiceType can have two options:

      • "INVOICE" - Invoice is used to pay money to service partner
      • "CREDIT_NOTE" - credit note is used to pay (return) money to Scalepoint

    • Credit note usage:

      • invoiceNumber is mandatory and should be equal to invoice number that is credited
      • creditNoteNumber is mandatory and should be unique

  • servicePartner element is not mandatory. It contains bank information and other details. It is mandatory in case when there is an invoice in the feedback

Requirements:

The JSON document is validated according to the JSON schema (see Appendix A2). But there are other restrictions:

  • repairPrice valuation is required when serviceLine.taskType is "REPAIR"
  • ServicePartner element is mandatory when invoice is present in feedback
Request
Request form parameter jsonString Example

The request form parameter jsonString takes JSON form. You can see JSON example in Appendix A1.

Request form parameter JSON schema

The JSON schema for the document is in Appendix A2, description of elements is in Appendix A3.

Response

| Response Headers | | --- |--- | | Content-Type | application/JSON |

Successful responses
  1. Example of a successful response JOSN

Response code is 201 (Created)

{
   "status":"SUCCESS"
}
  1. There can be internal logic validation of the invoice. In this case, line feedback is successfully saved but invoice is not.

Response code is 201 (Created)

{
   "status":"SUCCESS",
   "message":"Validation failed",
   "validationErrors":{
      "errorList":[
         "You already submitted invoice with the same Invoice number and Invoice type, but with another Total invoice amount. Please send new invoice with new Invoice number and Credit Note related to the previously sent invoice. Thank you."
      ]
   }
}
Failure response

Here are some examples of the failure response JSON

  1. JSON structure is not valid

Response code is 400 (Bad request)

{
   "status":"FAILURE",
   "message":"JSON structure is not valid"
}
  1. Access denied in case security token of the service partner is not valid or absent

Response code is 403 (Forbidden)

{
   "status":"FAILURE",
   "message":"JSON structure is not valid",
   "validationErrors":{
      "errorList":[
         "#/servicePartner: required key [bank] not found"
      ]
   }
}
  1. Task GUID is empty or not valid

Response code is 400 (Bad request)

{
   "status":"FAILURE",
   "message":"Wrong task GUID"
}
Response JSON schema for Posting task feedback to Scalepoint
{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "type":"object",
   "required":[
      "status"
   ],
   "properties":{
      "status":{
         "type":"string",
         "enum":[
            "SUCCESS",
            "FAILURE"
         ]
      },
      "message":{
         "type":"string"
      },
      "validationErrors":{
         "type":"object",
         "required":[
            "errorList"
         ],
         "properties":{
            "errorList":{
               "type":"array",
               "items":{
                  "type":"string"
               }
            }
         }
      }
   }
}

Posting task status to Scalepoint

Scalepoint provides optional service for posting task status

| Request details | | --- |--- | | Url | https://hostname/repairValuation/country/ws/v3/task_status.action | | Hostname | The hostname part will vary depending on environment. Scalepoint will supply specific hostname for production and test environments. | | Country | The country part will vary depending on country of operation. Scalepoint will supply the correct country value. | | Method | POST |

| Request Headers | | --- |--- | | Content-Type | application/x-www-form-urlencoded |

| Request form parameters | | --- |--- | | securityToken | Static GUID for service partner | | uniqueId | The uniqueId of the received task | | created (optional parameter) | Optional parameter with the Date of status update (mask "yyyy-MM-dd HH:mm:ss"). If mask is different than we create bad response. If parameter is empty than we use for it date of response receiving. | | status | Text description of task status. If size 100 characters than we create bad response. |

Response

Success response has HTTP status code 201 or 200. All others are considered to be failed.

Posting free text messages to Scalepoint

Service partner can send a message to Scalepoint system. This message is connected to specific RV task.

| Request details | | --- |--- | | Url | https://hostname/repairValuation/country/ws/v3/message.action | | Hostname | The hostname part will vary depending on environment. Scalepoint will supply specific hostname for production and test environments. | | Country | The country part will vary depending on country of operation. Scalepoint will supply the correct country value. | | Method | POST |

| Request Headers | | --- |--- | | Content-Type | multipart/form-data | | Accept | application/JSON |

| Request form data | | --- |--- | | securityToken | Static GUID for service partner | | taskGuid | Unique identifier of the task (GUID) | | textMessage | Text message | | file1 | Binary file | | …. | Binary file | | fileN | Binary file |

Usage notes

There is an identifier for the task – taskGuid being sent to service partner (uniqueId attribute of serviceTask element – see Fetching Repair or Valuation task or Posting repair or valuation task to service partner ).

Response

Success response has HTTP status code 201 or 200. All others are considered to be failed.

| Response Headers | | --- |--- | | Content-Type | application/JSON |

Successful response
  1. Example of a successful response JSON

Response code is 201 (Created)

{
   "status":"SUCCESS"
}

Integration from Scalepoint to Service Partner

When a new task is created for a Service Partner, a task document is created and pushed to the provided service partners web service. This document can then come into the Service Partners possession in one of two ways:

Service Partner Webservice

Service Partner should provide a webservice so scalepoint can push the document to this webservice. For this webservice, a return code needs to be agreed, which indicates a successful transfer of the task document. If the webservice is unavailable or returns an error, Scalepoint will try to send the task document again for a number of times.

Posting repair or valuation task to service partner

Service partner provides REST web service with the following parameters

Method: POST

| Request Headers | | --- |--- | | Content-Type | application/x-www-form-urlencoded |

| Request form parameters | | --- |--- | | securityToken | Static GUID for service partner | | jsonString | JSON document string |

Request

The request form parameter jsonString takes JSON form. You can see JSON example in Appendix B1.

The JSON schema for the document is in Appendix B2, description of elements is in Appendix B3.

Response

Success response has HTTP status code 201 or 200. All others are considered to be failed.

Posting status messages to Service Partner

If the Service Partner is able to provide a different webservice, Scalepoint can push various kind of service messages to this webservice. Service partner provides REST web service with the following parameters

Method: POST

| Request Headers | | --- |--- | | Content-Type | application/x-www-form-urlencoded |

| Request form parameters | | --- |--- | | securityToken | Static GUID for service partner | | jsonString | JSON document string |

Request

The request form parameter jsonString takes JSON form. You can see JSON example in Appendix C1.

The JSON schema for the document is in Appendix C2.

Response

Success response has HTTP status code 201 or 200. All others are considered to be failed.

Usage notes

This service is used to transfer only service messages about the various events of the repair&valuation task lifecycle. Each message contains:

  • code that describes event
  • task details
  • invoice summary

List of available message codes

Code Description
RVInvoiceWasReceivedMail Invoice was received
RVInvoiceWasRejectedMail Invoice was rejected
RVInvoiceWasUnrejectedMail Invoice rejection was undone
RVAutoApprovalSuccessNotificationToClaimant Notification about successful auto approval process completion
RVAutoApprovalSuccessNotificationToServicePartner Notification about successful auto approval process completion
RVReminderEmailNotificationToClaimant Reminder about not completed task
RVDeductibleNegativeAmountNotificationToCustomer Notification about repaired line with negative total claim amount
RVAutoApprovalInvoicePayToServicePartnerNotificationToClaimant Notification aboutpayment
RVTaskCancelNotificationToSP Task was cancelled by claim handler
RVTaskApprovedNotificationToServicePartner Task Approved
RVTaskRejectedNotificationToServicePartner Task Rejected
NotificationToClaimant Note to claimant sent

Task details

Parameter Description
taskGuid Unique identifier of the task
insuranceCompanyName Name of Insurance Company
claimNumber Claim number
policyNumber Policy number
claimantName Claimant name
servicePartnerName Service partner name

Invoice summary data

Parameter Description
count Total count of invoices
amount Sum of amounts of all invoices
paymentDate Payment date

Posting free text messages to Service partner

Service partner provides REST web service with the following parameters

Method: POST

| Request Headers | | --- |--- | | Content-Type | application/x-www-form-urlencoded |

| Request form parameters | | --- |--- | | securityToken | Static GUID for service partner | | jsonString | JSON document string |

Request

The request form parameter jsonString takes JSON form. You can see JSON example in Appendix D1.

The JSON schema for the document is in Appendix Appendix D2.

Response

Success response has HTTP status code 201 or 200. All others are considered to be failed.

Appendix A1 – Feedback example JSON

{
  "uniqueId": "dc100952-2005-4fbf-bbdf-badd1ec5a912",
  "servicePartner": {
    "name": "Service partner 1",
    "address1": "Fisketorvet Shopping Center, 201 Kalvebod Brygge",
    "address2": "some address",
    "phone": "88 81 80 01",
    "email": "shop@servicepartner1.com",
    "postalCode": "1560",
    "cvrNumber": "10166896",
    "city": "København V",
    "bank": {
      "bankName": "big bank",
      "regNumber": "1233",
      "accountNumber": "1222222342321112",
      "iban": "CH93 0076 2011 6238 5295 7",
      "giro": "123eee3333",
      "fikType": "123456",
      "fikCreditorCode": "CODE1",
      "fikNumber": "fik12345d"
    }
  },
  "serviceLines": [
    {
      "claimLineId": 10882352,
      "uniqueId": "75f7f1f6-719c-424a-ae17-21eff191c202",
      "taskType": "REPAIR",
      "category": {
        "name": "Handy",
        "parentCategory": "Telefon",
        "uniqueId": "8E22CEE8-0C44-4F33-A6A9-694EED215672"
      },
      "item": {
        "age": 24,
        "quantity": 1,
        "customerDescription": "APPLE iPhone 7 128GB Jetsort",
        "productMatchDescription": "APPLE iPhone 7 128GB Jetsort",
        "totalDamage": false,
        "servicePartnerNote": "Some text from service partner to scalepoint",
        "rejectReasonId": 1,
        "rejectReasonExplanation": "repair is rejected"
      },
      "valuations": {
        "purchasePrice": 5200.0,
        "newPrice": 5000.0,
        "customerDemand": 3200.0,
        "discretionaryValuation": 3700.0,
        "usedPrice": 3500.0,
        "repairEstimate": 1500.0,
        "repairPrice": 400.0
      }
    }
  ],
  "invoice":{
    "invoiceType":"INVOICE",
    "invoiceNumber":"Invoice_12345678",
    "creditNoteNumber":"CreditNote_12345678", //used only for credit notes
    "invoiceDate":"2020-02-21T16:00:00Z",
    "paymentDueDate":"2020-02-21T16:00:00Z",
    "nameOfValuationResponsible": "John Doe",
    "dateOfValuation": "2020-02-21T16:00:00Z",
    "netAmount":400.00,
    "vat":100.00,
    "totalAmount":500.00,
    "invoiceLines":[
      {
        "description":"invoice for iphone",
        "units": "item",
        "quantity":1,
        "unitNetAmount":400.00,
        "unitVatAmount":100.00,
        "unitPrice":500.00,
        "lineTotal":500.00
      },
      {
        "description":"invoice for iphone",
        "units": "item",
        "quantity":1,
        "unitNetAmount":200.00,
        "unitVatAmount":50.00,
        "unitPrice":250.00,
        "lineTotal":250.00
      }
    ]
  }
}

Appendix A2 – Feedback JSON schema

{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "definitions":{
      "uniqueId":{
         "type":"string",
         "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      },
      "bank":{
         "type":"object",
         "title":"The Bank details",
         "required":[

         ],
         "properties":{
            "bankName":{
               "type":"string"
            },
            "regNumber":{
               "type":"string"
            },
            "accountNumber":{
               "type":"string"
            },
            "iban":{
               "type":"string"
            },
            "giro":{
               "type":"string"
            },
            "fikNumber":{
               "type":"string"
            },
            "fikType":{
               "type":"string"
            },
            "fikCreditorCode":{
               "type":"string"
            }
         }
      },
      "servicePartner":{
         "type":"object",
         "title":"The Service partner details",
         "required":[
            "name",
            "bank"
         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "address1":{
               "type":"string"
            },
            "address2":{
               "type":"string"
            },
            "phone":{
               "type":"string"
            },
            "email":{
               "type":"string"
            },
            "postalCode":{
               "type":"string"
            },
            "cvrNumber":{
               "type":"string"
            },
            "city":{
               "type":"string"
            },
            "bank":{
               "$ref":"#/definitions/bank"
            }
         }
      },
      "item":{
         "type":"object",
         "title":"The Item Schema",
         "required":[
            "productMatchDescription",
            "quantity"
         ],
         "properties":{
            "customerDescription":{
               "type":"string"
            },
            "productMatchDescription":{
               "type":"string"
            },
            "quantity":{
               "type":"integer"
            },
            "age":{
               "type":"integer"
            },
            "servicePartnerNote":{
               "type":"string"
            },
            "totalDamage":{
               "type":"boolean"
            },
			"rejectReasonId": {
			  "type": "integer"
			},
			"rejectReasonExplanation": {
			  "type": "string"
			}
         }
      },
      "valuations":{
         "type":"object",
         "required":[

         ],
         "properties":{
            "purchasePrice":{
               "type":"number"
            },
            "newPrice":{
               "type":"number"
            },
            "customerDemand":{
               "type":"number"
            },
            "discretionaryValuation":{
               "type":"number"
            },
            "usedPrice":{
               "type":"number"
            },
            "repairEstimate":{
               "type":"number"
            },
            "repairPrice":{
               "type":"number"
            }
         }
      },
      "category":{
         "type":"object",
         "required":[
            "name",
            "uniqueId",
            "parentCategory"
         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "uniqueId":{
               "$ref":"#/definitions/uniqueId"
            },
            "parentCategory":{
               "type":"string"
            }
         }
      },
      "serviceLine":{
         "type":"object",
         "required":[
            "taskType",
            "item",
            "valuations",
            "claimLineId",
            "category"
         ],
         "properties":{
            "claimLineId":{
               "type":"number"
            },
            "uniqueId":{
               "$ref":"#/definitions/uniqueId"
            },
            "taskType":{
               "type":"string",
               "enum":[
                  "REPAIR",
                  "REPAIR_ESTIMATE",
                  "VALUATION",
                  "MATCH_SERVICE"
               ]
            },
            "item":{
               "$ref":"#/definitions/item"
            },
            "valuations":{
               "$ref":"#/definitions/valuations"
            },
            "category":{
               "$ref":"#/definitions/category"
            }
         }
      },
      "invoiceLine":{
         "type":"object",
         "required":[
            "description",
            "quantity",
            "unitNetAmount",
            "unitVatAmount",
            "unitPrice",
            "lineTotal"
         ],
         "properties":{
            "description":{
               "type":"string"
            },
            "units":{
               "type":"string"
            },
            "unitNetAmount":{
               "type":"number"
            },
            "unitVatAmount":{
               "type":"number"
            },
            "unitPrice":{
               "type":"number"
            },
            "quantity":{
               "type":"number"
            },
            "lineTotal":{
               "type":"number"
            }
         }
      },
      "invoice":{
         "type":"object",
         "required":[
            "invoiceType",
            "invoiceNumber",
            "invoiceDate",
            "paymentDueDate",
            "netAmount",
            "vat",
            "totalAmount",
            "invoiceLines"
         ],
         "properties":{
            "invoiceType":{
               "type":"string",
               "enum":[
                  "INVOICE",
                  "CREDIT_NOTE"
               ]
            },
            "invoiceNumber":{
               "type":"string"
            },
            "invoiceDate":{
               "type":"string"
            },
            "paymentDueDate":{
               "type":"string"
            },
            "creditNoteNumber":{
               "type":"string"
            },
            "nameOfValuationResponsible":{
               "type":"string"
            },
            "dateOfValuation":{
               "type":"string"
            },
            "netAmount":{
               "type":"number"
            },
            "vat":{
               "type":"number"
            },
            "totalAmount":{
               "type":"number"
            },
            "invoiceLines":{
               "type":"array",
               "items":{
                  "$ref":"#/definitions/invoiceLine"
               }
            }
         }
      }
   },
   "type":"object",
   "title":"RV Task feedback",
   "required":[
      "uniqueId",
      "serviceLines",
      "servicePartner"
   ],
   "properties":{
      "uniqueId":{
         "$ref":"#/definitions/uniqueId"
      },
      "createdDate":{
         "type":"string"
      },
      "takenSelfRisk":{
         "type":"number"
      },
      "updateClaimSelfRisk":{
         "type":"number"
      },
      "updateClaimSelfRiskReason":{
         "type":"string"
      },
      "invoice":{
         "$ref":"#/definitions/invoice"
      },
      "serviceLines":{
         "type":"array",
         "title":"The task lines details",
         "items":{
            "$ref":"#/definitions/serviceLine"
         }
      },
      "servicePartner":{
         "$ref":"#/definitions/servicePartner"
      }
   }
}

Appendix A3 – Description of feedback json elements

Element Parent Element Attribute Pattern Use Description Feedback specific*
serviceTask Required Container for the whole feedback -
serviceTask uniqueId Required The unique identifier of the task. It is contained in the received JSON document by service partner. -
serviceTask createdDate Required Date and time of JSON creation -
serviceTask takenSelfRisk Optional Selfrisk taken by service partner +
serviceTask updateClaimSelfRisk Optional The value of the Selfrisk that will be set in claim after the accept this feedback +
serviceTask updateClaimSelfRiskReason Optional Description with reason why Selfrisk for claim should be updated +
invoice serviceTask Optional Container of payment invoice +
invoice invoiceType Required Type of the invoice. Possible values: "INVOICE", "CREDIT_NOTE" +
Invoice invoiceNumber Required Unique invoice identification +
Invoice invoiceDate yyyy-MM-dd Required Invoice date +
invoice paymentDueDate yyyy-MM-dd Required Invoice payment due date +
Invoice creditNoteNumber Optional Unique credit note identification +
Invoice nameOfValuationResponsible Optional Name of the person in charge of current task +
invoice dateOfValuation yyyy-MM-dd Optional Date of valuation +
Invoice netAmount #0.00 Required Net amount of the invoice +
Invoice vat #0.00 Required VAT amount of the invoice +
invoice totalAmount #0.00 Required Total amount of the invoice +
invoiceLines invoice Required Container for invoice lines +
invoiceLine invoiceLines Required Invoice line details +
invoiceLine description Required Invoice line description +
invoiceLine quantity #0.00 Required Quantity of invoice line units +
invoiceLine units Optional Units +
invoiceLine unitPrice #0.00 Required Price per 1 invoice line unit +
invoiceLine unitVatAmount #0.00 Required VAT * unitPrice * quantity +
invoiceLine unitNetAmount #0.00 Required unitPrice * quantity +
invoiceLine lineTotal #0.00 Required unitVatAmount + unitNetAmount +
serviceLines serviceTask Required Container for service lines -
serviceLine serviceLines Required Service line details -
serviceLine claimLineId Optional Id of the ClaimShop service line, required for posting existing line in feedback and must be empty if line is new -
serviceLine uniqueId Optional GUID of the ClaimShop service line, required for posting existing line in feedback and must be empty if line is new -
serviceLine taskType Required Type of the R&V task. Possible values: REPAIR, REPAIR_ESTIMATE, VALUATION, MATCH_SERVICE -
category serviceLine Required Category of the service line -
category Name Required Name of the category -
category uniqueId Required GUID of the category (received from Scalepoint) -
category parentCategory Required Name of the parent category -
item serviceLine Required Service line details -
item customerDescription Optional Item description by claimant -
item productMatchDescription Required Item description -
item quantity Required Quantity -
item age Optional Age in months -
item servicePartnerNote Optional Service partner note +
item totalDamage Optional Total damage +
item rejectReasonId Optional Id of the reject reason (please ask product manager for the predefined list of reject reasons) +
item rejectReasonExplanation Optional Note about reject reason +
valuations serviceLine Required Service line valuations -
valuations purchasePrice #0.00 Optional Purchase price -
valuations newPrice #0.00 Optional price of the new item -
valuations customerDemand #0.00 Optional Customer demand price -
valuations discretionaryValuation #0.00 Optional Discretionary valuation -
valuations usedPrice #0.00 Optional Used item price -
valuations repairEstimate #0.00 Optional Repair estimate -
valuations repairPrice #0.00 Optional Repair price -
servicePartner serviceTask Required Service partner details -
servicePartner name Required Service partner name -
servicePartner address1 Optional Service partner address -
servicePartner address2 Optional Service partner second address -
servicePartner phone Optional Service partner phone -
servicePartner email Optional Service partner email -
servicePartner postalCode Optional Service partner postal code -
servicePartner cvrNumber Optional Service partner company number (CVR for DK) -
servicePartner city Optional Service partner city -
bank servicePartner Required Bank details -
bank bankName Optional Bank name +
bank regNumber Optional Bank registration number -
bank accountNumber Optional Bank account number -
bank fikType Optional Bank FIK type -
bank fikNumber Optional Bank FIK number +
bank fikCreditorCode Optional Bank FIK creditor code -
bank IBAN Optional Bank IBAN -
bank GIRO Optional Bank GIRO -

* feedback specific - the field specific only to a feedback, meaning that it is not presented in a task sent to service partner (see Appendix B)

Appendix B1 – Task example JSON

{
  "serviceTasks": [
    {
      "uniqueId": "dc100952-2005-4fbf-bbdf-badd1ec5a912",
      "noteToServicePartner": "Hello, here is a broken iphone",
      "replyAddress": "http+185562+dk+LT-ATU.spcph.local@sandbox65938.mailgun.org",
      "invoicePaidBy": "Scalepoint",
      "damageType": "type1",
      "damageCauseDescription": "Damage cause description 1",
      "allowedToCollectSelfRisk": false,
      "allowedToUpdateSelfRisk": false,
      "createdDate": "2020-10-20T13:14:46Z",
      "claimant": {
        "name": "Dorthey Tieman",
        "mobilePhone": "44444444",
        "phone": "+45 81-53-44-28",
        "address1": "Random Street",
        "address2": "3/14",
        "postalCode": "2300",
        "city": "København S",
        "email": "johndoe@mail.com"
      },
      "claim": {
        "insuranceCompanyId": 7,
        "insuranceCompanyName": "Zurich",
        "claimHandlerName": "johndoe",
        "claimHandlerFullName": "John Doe",
        "claimHandlerEmail": "johndoe@mail.com",
        "claimReferenceNumber": 2897103,
        "claimNumber": "claimnumber1234",
        "selfRisk": 200.0,
        "claimDate": "2020-10-19T22:00:00Z",
        "customerNoteToClaim": "some notes",
        "policyNumber": "12345678",
        "policyType": "type1"
      },
      "servicePartner": {
        "name": "Service partner 1",
        "address1": "Fisketorvet Shopping Center, 201 Kalvebod Brygge",
        "address2": "some address",
        "phone": "88 81 80 01",
        "email": "shop@servicepartner1.com",
        "postalCode": "1560",
        "cvrNumber": "10166896",
        "city": "København V",
        "serviceAgreementName": "Service partner 1 sa",
        "bank": {
          "regNumber": "1233",
          "accountNumber": "1222222342321112",
          "iban": "CH93 0076 2011 6238 5295 7",
          "giro": "123eee3333",
          "fikType": "123456",
          "fikCreditorCode": "CODE1"
        },
        "location": {
          "name": "Bahne - Aalborg",
          "address1": "Nørregade 20",
          "address2": "some address",
          "postalCode": "9000",
          "city": "Aalborg",
          "phone": "38 40 50 16",
          "email": "johndoe@mail.com"
        }
      },
      "serviceLines": [
        {
          "claimLineId": 10882352,
          "uniqueId": "75f7f1f6-719c-424a-ae17-21eff191c202",
          "category": {
            "name": "Mobiltelefoner",
            "parentCategory": "Telefoni",
            "uniqueId": "09F7146D-26B6-4F6D-AE3C-2118F833B4FD"
          },
          "taskType": "REPAIR",
          "item": {
            "age": 24,
            "quantity": 1,
            "manufacturer": "APPLE",
            "serialNumber": "2567915",
            "damageDescription": "broken glass",
            "damageType": "type1",
            "repairLimit": 2000,
            "depreciation": 20,
            "model": "7 128GB",
            "customerNotesToClaimLine": "I broke the phone",
            "customerDescription": "APPLE iPhone 7 128GB Jetsort",
            "productMatchDescription": "APPLE iPhone 7 128GB Jetsort",
            "ean": "0190198069702"
          },
          "valuations": {
            "purchasePrice": 5200.0,
            "newPrice": 5000.0,
            "customerDemand": 3200.0,
            "discretionaryValuation": 3700.0,
            "usedPrice": 3500.0,
            "repairEstimate": 1500.0,
            "productPrice": 4213.02,
            "retailPrice": 4299.0
          },
          "attachments": [
            {
              "name": "photo.png",
              "link": "https://www.scalepoint.com/webapp/ScalePoint/dk/rest/file/56EFF336-2A1D-42C3-A074-1E4377D4916B"
            }
          ],
          "rejectReasons": [
            {
              "id": 1,
              "text": "The item cannot be repaired",
              "locale": "da-DK"
            },
            {
              "id": 2,
              "text": "The item has not been received",
              "locale": "da-DK"
            }
          ]
        }
      ]
    }
  ]
}

Appendix B2 – Task JSON schema

{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "definitions":{
      "uniqueId":{
         "type":"string",
         "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      },
      "claimant":{
         "type":"object",
         "title":"The Claimant details",
         "required":[
            "name"
         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "mobilePhone":{
               "type":"string"
            },
            "phone":{
               "type":"string"
            },
            "address1":{
               "type":"string"
            },
            "address2":{
               "type":"string"
            },
            "postalCode":{
               "type":"string"
            },
            "city":{
               "type":"string"
            },
            "email":{
               "type":"string"
            }
         }
      },
      "claim":{
         "type":"object",
         "title":"The Claim details",
         "required":[
            "claimNumber"
         ],
         "properties":{
            "insuranceCompanyId":{
               "type":"integer"
            },
            "insuranceCompanyName":{
               "type":"string"
            },
            "claimHandlerName":{
               "type":"string"
            },
            "claimHandlerFullName":{
               "type":"string"
            },
            "claimHandlerEmail":{
               "type":"string"
            },
            "claimReferenceNumber":{
               "type":"number"
            },
            "claimNumber":{
               "type":"string"
            },
            "selfRisk":{
               "type":"number"
            },
            "takenSelfRisk": {
               "type": "number"
            },
            "updateClaimSelfRisk": {
               "type": "number"
            },
            "updateSelfRiskReason": {
               "type": "string"
            },
            "claimDate":{
               "type":"string"
            },
            "customerNoteToClaim":{
               "type":"string"
            },
            "policyType":{
               "type":"string"
            },
            "policyNumber":{
               "type":"string"
            }
         }
      },
      "bank":{
         "type":"object",
         "title":"The Bank details",
         "required":[

         ],
         "properties":{
            "regNumber":{
               "type":"string"
            },
            "accountNumber":{
               "type":"string"
            },
            "iban":{
               "type":"string"
            },
            "giro":{
               "type":"string"
            },
            "fikType":{
               "type":"string"
            },
            "fikCreditorCode":{
               "type":"string"
            }
         }
      },
      "location":{
         "type":"object",
         "title":"The Location details",
         "required":[

         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "address1":{
               "type":"string"
            },
            "address2":{
               "type":"string"
            },
            "postalCode":{
               "type":"string"
            },
            "city":{
               "type":"string"
            },
            "phone":{
               "type":"string"
            },
            "email":{
               "type":"string"
            }
         }
      },
      "servicePartner":{
         "type":"object",
         "title":"The Servicepartner details",
         "required":[
            "name",
            "serviceAgreementName"
         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "address1":{
               "type":"string"
            },
            "address2":{
               "type":"string"
            },
            "phone":{
               "type":"string"
            },
            "email":{
               "type":"string"
            },
            "postalCode":{
               "type":"string"
            },
            "cvrNumber":{
               "type":"string"
            },
            "city":{
               "type":"string"
            },
            "serviceAgreementName":{
               "type":"string"
            },
            "bank":{
               "$ref":"#/definitions/bank"
            },
            "location":{
               "$ref":"#/definitions/location"
            }
         }
      },
      "item":{
         "type":"object",
         "title":"The Item Schema",
         "required":[
            "productMatchDescription",
            "quantity"
         ],
         "properties":{
            "customerDescription":{
               "type":"string"
            },
            "productMatchDescription":{
               "type":"string"
            },
            "manufacturer":{
               "type":"string"
            },
            "model":{
               "type":"string"
            },
            "serialNumber":{
               "type":"string"
            },
            "quantity":{
               "type":"integer"
            },
            "age":{
               "type":"integer"
            },
            "depreciation":{
               "type":"number"
            },
            "damageDescription":{
               "type":"string"
            },
            "damageType":{
               "type":"string"
            },
            "repairLimit":{
               "type":"number"
            },
            "customerNotesToClaimLine":{
               "type":"string"
            },
            "ean":{
               "type":"string",
               "title":"EAN - European Article Number"
            }
         }
      },
      "valuations":{
         "type":"object",
         "required":[

         ],
         "properties":{
            "purchasePrice":{
               "type":"number"
            },
            "newPrice":{
               "type":"number"
            },
            "customerDemand":{
               "type":"number"
            },
            "discretionaryValuation":{
               "type":"number"
            },
            "usedPrice":{
               "type":"number"
            },
            "repairEstimate":{
               "type":"number"
            },
            "repairPrice":{
               "type":"number"
            },
            "productPrice":{
               "type":"number"
            },
            "retailPrice":{
               "type":"number"
            }
         }
      },
      "category":{
         "type":"object",
         "required":[
            "name",
            "uniqueId",
            "parentCategory"
         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "uniqueId":{
               "$ref":"#/definitions/uniqueId"
            },
            "parentCategory":{
               "type":"string"
            }
         }
      },
      "serviceLine":{
         "type":"object",
         "required":[
            "item",
            "valuations",
            "claimLineId",
            "uniqueId",
            "category",
            "taskType"
         ],
         "properties":{
            "claimLineId":{
               "type":"number"
            },
            "uniqueId":{
               "$ref":"#/definitions/uniqueId"
            },
            "taskType":{
               "type":"string",
               "enum":[
                  "REPAIR",
                  "REPAIR_ESTIMATE",
                  "VALUATION",
                  "MATCH_SERVICE"
               ]
            },
            "item":{
               "$ref":"#/definitions/item"
            },
            "valuations":{
               "$ref":"#/definitions/valuations"
            },
            "category":{
               "$ref":"#/definitions/category"
            },
            "rejectReasons": {
              "type": "array",
              "title": "The list of reject reasons",
              "items": {
                "$ref": "#/definitions/rejectReason"
              }
            }
         }
      },
      "attachment":{
         "type":"object",
         "required":[
            "name",
            "link"
         ],
         "properties":{
            "name":{
               "type":"string"
            },
            "link":{
               "type":"string"
            }
         }
      },
      "serviceTask":{
         "type":"object",
         "title":"RV Task",
         "required":[
            "uniqueId",
            "createdDate",
            "replyAddress",
            "claimant",
            "claim",
            "serviceLines",
            "noteToServicePartner"
         ],
         "properties":{
            "uniqueId":{
               "$ref":"#/definitions/uniqueId"
            },
            "createdDate":{
               "type":"string"
            },
            "replyAddress":{
               "type":"string"
            },
            "invoicePaidBy":{
               "type":"string"
            },
            "allowedToCollectSelfRisk":{
               "type":"boolean"
            },
            "allowedToUpdateSelfRisk":{
               "type":"boolean"
            },
            "noteToServicePartner":{
               "type":"string"
            },
            "damageType":{
               "type":"string"
            },
            "damageCauseDescription":{
               "type":"string"
            },
            "claimant":{
               "$ref":"#/definitions/claimant"
            },
            "claim":{
               "$ref":"#/definitions/claim"
            },
            "servicePartner":{
               "$ref":"#/definitions/servicePartner"
            },
            "serviceLines":{
               "type":"array",
               "title":"The task lines details",
               "items":{
                  "$ref":"#/definitions/serviceLine"
               }
            },
            "attachments":{
               "type":"array",
               "title":"The attached files array",
               "items":{
                  "$ref":"#/definitions/attachment"
               }
            }
         }
      },
      "rejectReason": {
        "type": "object",
        "required": [
          "id",
          "text"
        ],
        "properties": {
          "id": {
            "type": "number"
          },
          "text": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          }
        }
      }
   },
   "type":"object",
   "required":[
      "serviceTasks"
   ],
   "properties":{
      "serviceTasks":{
         "type":"array",
         "title":"Container for RV tasks",
         "items":{
            "$ref":"#/definitions/serviceTask"
         }
      }
   }
}

Appendix B3 – Description of task JSON elements

Element Parent Element Attribute Use Description
serviceTasks Required Container for R&V tasks
serviceTask serviceTasks Required Container for a single R&V task
serviceTask uniqueId Required The unique identifier of the task.
serviceTask createdDate Required Date and time of json creation
serviceTask replyAddress Required Email address to which service partner can send any attachments
serviceTask damageType Optional Damage type
serviceTask damageCauseDescription Optional Damage cause description
serviceTask invoicePaidBy Optional
serviceTask allowedToCollectSelfRisk Optional Represent if service partner can collect some amount from self-risk
serviceTask allowedToUpdateSelfRisk Optional Represent if service partner can update claim self risk
claim serviceTask Required Claim details
claim claimNumber Optional Claim number
claim claimReferenceNumber Optional Claim identification
claim claimDate Optional Date of the claim creation
claim claimHandlerFullName Optional Full name of the claim handler
claim claimHandlerEmail Optional Claim handler email
claim claimHandlerName Optional Claim handler login name
claim customerNoteToClaim Optional Claimant note to claim
claim insuranceCompanyId Optional Insurance company identification
claim insuranceCompanyName Optional Insurance company name
claim policyNumber Optional Policy number
claim policyType Optional Policy type
claim selfRisk Optional Self risk amount
claim language Optional language of the claim (only for multi-language countries)
claimant serviceTask Required Claimant details
claimant name Optional Claimant name
claimant address1 Optional Claimant address
claimant address2 Optional Claimant second address
claimant city Optional Claimant city
claimant email Optional Claimant email
claimant mobilePhone Optional Claimant mobile phone
claimant phone Optional Claimant phone
claimant postalCode Optional Claimant postal code
serviceLines serviceTask Required Container for service lines
serviceLine serviceLines Required Service line details
serviceLine claimLineId Required Id of the ClaimShop service line
serviceLine uniqueId Required GUID of the ClaimShop service line
serviceLine taskType Required Type of the R&V task. Possible values: REPAIR, REPAIR_ESTIMATE, VALUATION, MATCH_SERVICE
category serviceLine Required Category of the service line
category name Required Name of the category
category uniqueId Required GUID of the category (received from Scalepoint)
category parentCategory Required Name of the parent category
item serviceLine Required Service line data
item customerDescription Optional Item description by customer
item productMatchDescription Required Item description
item manufacturer Optional Item manufacturer
item model Optional Item model
item serialNumber Optional Item serial number
item quantity Required Quantity
item age Optional Age in months
item depreciation Optional depreciation
item damageDescription Optional Damage description
item repairLimit Optional Repair limit amount
item customerNotesToClaimLine Optional Claimant note to the item
Item EAN Optional Product EAN
item damageType Optional Damage type for line chosen from pseudo category
valuations serviceLine Required Service line details
valuations purchasePrice Optional Purchase price
valuations newPrice Optional price of the new item
valuations customerDemand Optional Customer demand price
valuations productPrice Optional Product price
valuations retailPrice Optional Retail price
valuations discretionaryValuation Optional Discretionary valuation
valuations usedPrice Optional Used item price
valuations repairEstimate Optional Repair estimate
valuations repairPrice Optional Repair price
rejectReasons serviceLine Required Item reject reasons
rejectReasons id Required Reject reason id
rejectReasons text Required Reject reason text
rejectReasons locale Optional Reject reason text locale
servicePartner serviceTask Optional Service partner details
servicePartner name Required Service partner name
servicePartner address1 Optional Service partner address
servicePartner address2 Optional Service partner second address
servicePartner phone Optional Service partner phone
servicePartner email Optional Service partner email
servicePartner postalCode Optional Service partner postal code
servicePartner cvrNumber Optional Service partner company number (CVR for DK)
servicePartner city Optional Service partner city
servicePartner serviceAgreementName Required Name of the service agreement
bank servicePartner Optional Bank details
bank regNumber Optional Bank registration number
bank accountNumber Optional Bank account number
bank fikType Optional Bank FIK type
bank fikCreditorCode Optional Bank FIK creditor code
bank IBAN Optional Bank IBAN
bank GIRO Optional Bank GIRO
location servicePartner Required Service partner location details
location name Optional Service partner location name
location address1 Optional Service partner location address
location address2 Optional Service partner location second address
location city Optional Service partner location city
location email Optional Service partner location email
location phone Optional Service partner location phone
location postalCode Optional Service partner location postal code
noteToServicePartner serviceTask Required Note to service partner
attachments serviceTask Optional Files attached to service task
attachments serviceLine Optional Files attached to service line
attachment attachments Optional Attached file
attachment name Required File name
attachment link Required Link to the file

Appendix C1 – Sample message JSON

{
   "type":"RVInvoiceWasReceivedMail",
   "details":{
      "taskGuid":"0829a953-5f85-4d41-a30c-a582101812f4",
      "insuranceCompanyName":"InsCompany1",
      "claimNumber":"number123",
      "policyNumber":"",
      "claimantName":"Larry Henry",
      "servicePartnerName":"ServPart1"
   },
   "invoice":{
      "count":2,
      "amount":1000.00
   },
   "selfRisk":{
      "claimSelfRisk":0.00,
      "updatedClaimSelfRisk":0,
      "claimSelfRiskUpdateReason":""
   }
}

Appendix C2 – Sample message schema


{
   "$schema":"http://json-schema.org/draft-07/schema#",
   "type":"object",
   "required":[
      "type",
      "details",
      "invoice",
      "selfRisk"
   ],
   "properties":{
      "type":{
         "type":"string"
      },
      "text":{
         "type":"string"
      },
      "details":{
         "type":"object",
         "required":[
            "taskGuid",
            "insuranceCompanyName",
            "claimNumber",
            "claimantName",
            "servicePartnerName"
         ],
         "properties":{
            "taskGuid":{
               "type":"string"
            },
            "insuranceCompanyName":{
               "type":"string"
            },
            "claimNumber":{
               "type":"string"
            },
            "policyNumber":{
               "type":"string"
            },
            "claimantName":{
               "type":"string"
            },
            "servicePartnerName":{
               "type":"string"
            }
         }
      },
      "invoice":{
         "type":"object",
         "required":[
            "count",
            "amount"
         ],
         "properties":{
            "count":{
               "type":"integer"
            },
            "amount":{
               "type":"number"
            },
            "paymentDate":{
               "type":"string"
            }
         },
         "selfRisk":{
            "type":"object",
            "required":[

            ],
            "properties":{
               "claimSelfRisk":{
                  "type":"number"
               },
               "updatedClaimSelfRisk":{
                  "type":"number"
               },
               "claimSelfRiskUpdateReason":{
                  "type":"string"
               }
            }
         }
      }
   }
}

Appendix D1 – Sample free text message JSON

{
  "taskGuid":"9a4da5d2-ec13-4d10-9949-0461c7ad15c6",
  "textMessage":"Chat message text",
  "attachments":[
    {
      "name":"Test.pdf",
      "link":"https://www.scalepoint.com/webapp/ScalePoint/dk/rest/file/00000001-3E87-474C-BCE5-E15657DF736E"
    },
    {
      "name":"13_22.png",
      "link":"https://www.scalepoint.com/webapp/ScalePoint/dk/rest/file/00000002-9AA4-4B87-B419-6B70726CF5F6"
    }
  ]
}

Appendix D2 – Sample free text message schema

{
  "$schema":"http://json-schema.org/draft-07/schema#",
  "definitions":{
    "attachment":{
      "type":"object",
      "required":[
        "name",
        "link"
      ],
      "properties":{
        "name":{
          "type":"string"
        },
        "link":{
          "type":"string"
        }
      }
    }
  },
  "type":"object",
  "required":[
    "taskGuid",
    "textMessage"
  ],
  "properties":{
    "taskGuid": {
      "type": "string",
      "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
    },
    "textMessage": {
      "type": "string"
    },
    "attachments":{
      "type":"array",
      "title":"The attached files array",
      "items":{
        "$ref":"#/definitions/attachment"
      }
    }
  }
}

Service Partners Integration Testing Before Go Live