Service Providers Search API

Introduction

This document describes the Scalepoint Service Providers Search API. This API can be used to search service providers from Scalepoint solutions (HUB Motor, HUB Property, ClaimShop, HUB Health, etc), for example, as a part of FNOL flow implemented by insurance company.

Main consumer of this API is insurance company.

Overview

The process of searching service providers can be divided into two steps:

  • Authentication
  • Search request

Websequence diagram of Search Service Providers Request

Authentication

You need an access_token in order to send data to the Service Providers Endpoint. This access token can be obtained from the Authentication Endpoint. Please refer to the documentation about details of authentication process.

API caller should request platform-service-provider:read scope from Authentication Endpoint.

Endpoints

Service Providers Search API endpoint

The endpoint which allows to search service providers is in the following format:

https://www.scalepoint.com/api/integration/data/<version>/<country>/<tenant>/service-providers?<query string parameters>

Service providers search request data presented as query string parameters.

The actual format of this will depend on the insurance company, the country in which it operates and the version of the API.

Assuming the following:

  • Country: Denmark
  • Tenant: ABC Insurance
  • Other brands: Budget Insurance

The endpoint could look something like this:

https://www.scalepoint.com/api/integration/data/v1/dk/abcinsurance/service-providers?company=abcinsurance&serviceType=vehicleRepair&vehicle.licensePlateNo=CW42822&address.postalCode=6200&policy.serviceLevel=Basic&propertyCode=1102

For testing purposes, you will be given access to a project server and the hostname-part of the endpoint would change accordingly:

https://<hostname>/api/integration/data/v1/dk/abcinsurance/service-providers?company=abcinsurance&serviceType=vehicleRepair&vehicle.licensePlateNo=CW42822&address.postalCode=6200&policy.serviceLevel=Basic&propertyCode=1102

Please discuss with your account manager, which project server you have been assigned in order to determine the actual endpoint.

Service Providers Search Request

Search Service Providers GET request contains query string parameters and authorization header. Fields are described in Appendix A and C.

Authorization header has name 'Authorization'. It has value built from access_token in following format:

Bearer access_token

Note the important space character between Bearer and access_token value.

Service Providers Search Response - V1

Response contains basic service providers info in JSON format in case of success (HTTP status code 200). Fields are described in Appendix B - V1 and C.

Simplest successful response example for vehicle repair:

{
  "serviceType": "vehicleRepair",
  "serviceProviders": [
  {
        "externalId": "a.06317562-7f4a-4c7e-9ee4-eae06e590c37",
        "name": "Serviceprovider name",
        "country": "dk",
        "postalCode": "1964",
        "distance": 0,
        "address": "Ingemannsvej 9",
        "city": "Frederiksberg C",
        "email": "abc@repairshopbrand.dk",
        "phone": "12 34 56 78",
        "status": "Red",
        "statusDescription": "Serviceprovider is very busy at the moment",
        "isExternal": false
  },
  {
        "externalId": "a.12345678-7f4a-4c7e-9ee4-eae06e590c37",
        "name": "Another serviceprovider name",
        "country": "dk",
        "postalCode": "1964",
        "distance": 3,
        "address": "Ingemannsvej 3",
        "city": "Frederiksberg C",
        "email": "cba@anotherrepairshop.dk",
        "phone": "87 65 43 21",
        "status": "Green",
        "statusDescription": "Serviceprovider is not loaded.",
        "isExternal": true,
        "supplierAccountNo": "L45850505"
  }
  ],
  "vehicle" : {
    "brand": "Mercedes",
    "model": "CLS 350"
  }
}

Simplest successful response example for property:

{
  "success": true,
  "payload": {
    "serviceType": "property",
    "serviceProviders": [
      {
        "externalId": "5505715f-d80b-46bb-9463-bbf1ba3de4e1",
        "name": "SP 1",
        "phone": "+4512345678",
        "email": "craftsman_company_email@example.com",
        "commercialTaxId": "43726223",
        "distance": 1,
        "contacts": [
          {
            "name": "craftsman_name Last"
          }
        ],
        "address": {
          "country": "DK",
          "city": "Frederiksberg C",
          "postalCode": "1964",
          "street1": "Ingemannsvej 9",
          "street2": ""
        },
        "isExternal": false
      }
    ],
    "total": 8
  }
}

Simplest successful response example for health:

{
  "success": true,
  "payload": {
    "serviceType": "health",
    "serviceProviders": [
      {
        "externalId": "4d61f95f-011b-e711-8105-005056bb6611",
        "name": "Autotest company",
        "phone": "+45 12 23 32 24",
        "email": "jr.company.auto_company_email@example.com",
        "description": "",
        "commercialTaxId": "19283740",
        "distance": 1,
        "address": {
          "country": "dk",
          "city": "Frederiksberg C",
          "postalCode": "1964",
          "street1": "Ingemansvej 9",
          "street2": ""
        },
        "isExternal": true,
        "organization": "Autotest company"
      }
    ],
    "total": 7
  }
}

In case of error response JSON can be ignored - instead HTTP status code should be used to determine error type.

From business point of view, most of the data are intended to be present for end-user, and service provider identifier should be sent within following Create Case endpoint call (during FNOL flow) to assign selected service provider to a case.

Service Providers Search Response - V2

Main difference comparing to the previous version is more extended information, also some data restructuring (ex. new 'address' property grouping related address fields).

Response contains basic service providers info in JSON format in case of success (HTTP status code 200). Fields are described in Appendix B - V2 and C.

Simplest successful response example:

{
  "serviceType": "vehicleRepair",
  "serviceProviders": [
    {
      "externalId": "a.80288d4a-322f-48bc-9051-d546460eca07",
      "name": "Repairshop Name",
      "phone": "12 34 56 78",
      "fax": "87 65 43 21",
      "email": "abc@mail.dk",
      "description": "Peugeot",
      "competences": "",
      "commercialTaxId": "11112222",
      "distance": 0,
      "externalSystemId": "32343",
      "isExternal": true,
      "organization": "Organization name",
      "lastModificationDate": "2018-07-18T15:58:43Z",
      "workSchedule": {
        "monday": "08:00 - 16:00",
        "tuesday": "08:00 - 16:00",
        "wednesday": "08:00 - 16:00",
        "thursday": "08:00 - 16:00",
        "friday": "08:00 - 15:00",
        "saturday": "Lukket",
        "sunday": "Lukket"
      },
      "contacts": [
        {
          "name": "Peter Hansen"
        },
        {
          "name": ""
        }
      ],
      "closedCasesStatistics": {
        "totalCases": 100,
        "totalCasesLastYear": 0
      },
      "availability": {
        "status": "G",
        "vacation": false,
        "description": "Short waiting time"
      },
      "address": {
        "street1": "Vestvejen 99",
        "street2": "",
        "postalCode": "9999",
        "city": "Aabenraa",
        "country": "dk"
      },
      "paymentMethods": [
        {
          "type": "bankAccount",
          "branchNumber": "9999",
          "accountNumber": "9999999"
        }
      ],
      "specialties": {
        "carBrands": [
          {
            "name": "Peugeot",
            "authorized": false
          },
          {
            "name": "Audi",
            "authorized": true
          },
          {
            "name": "VW",
            "authorized": false
          }
        ]
      }
    },
    {
      "externalId": "a.8bec2f08-7482-4312-adf5-5635c6540c8f",
      "name": "Another repairshop name",
      "phone": "11 22 33 44",
      "fax": "",
      "email": "cba@mail.com",
      "description": "Eurogarant godkendt",
      "competences": "",
      "commercialTaxId": "98765432",
      "distance": 0,
      "externalSystemId": null,
      "isExternal": false,
      "organization": "Organization name",
      "lastModificationDate": "2018-07-18T15:58:43Z",
      "bankBranchNumber": "9999",
      "accountNumber": "9999999",
      "supplierAccountNo":"L45850505",
      "workSchedule": {
        "monday": "08:00 - 16:30",
        "tuesday": "08:00 - 16:30",
        "wednesday": "08:00 - 16:30",
        "thursday": "08:00 - 16:30",
        "friday": "08:00 - 16:30",
        "saturday": "Lukket",
        "sunday": "Lukket"
      },
      "contacts": [
        {
          "name": "Bo Hansen"
        },
        {
          "name": ""
        }
      ],
      "closedCasesStatistics": {
        "totalCases": 250,
        "totalCasesLastYear": 0
      },
      "availability": {
        "status": "R",
        "vacation": false,
        "description": "Repairshop is very busy at the moment"
      },
      "address": {
        "street1": "Kathale 99",
        "street2": "",
        "postalCode": "9999",
        "city": "Aabenraa",
        "country": "dk"
      },
      "paymentMethods": [
        {
          "type": "bankAccount",
          "branchNumber": "9999",
          "accountNumber": "9999999"
        }
      ],
      "specialties": {
        "carBrands": [
          {
            "name": "All",
            "authorized": false
          }
        ]
      }
    }
  ],
  "vehicleInfo": {
    "brand": "Mercedes",
    "model": "CLS 350",
    "year": 2014
  },
  "total" : 20,
  "serviceLevelMatch": true
}

In case of error response JSON can be ignored - instead, HTTP status code should be used to determine error type.

From the business point of view, most of the data are intended to be present for end-user, and service provider identifier should be sent within following Create Case endpoint call (during FNOL flow) to assign selected service provider to a case.

Appendix A-v1 – Request data description

Query parameter Description Support
company Specific company or brand
  • all: required

serviceType

The serviceType determines the kind of service providers you are searching for. Supported values are: "vehicleRepair", "property", "health".

  • all: required
vehicle.licensePlateNo

The licenseplate of the vehicle. Should be specified without any punctuation.

Used to identify car brand, model and other car properties, then it could be used, for example, to filter out repairshops that do not provide repair certain cars.

  • motor: required
address.postalCode Postal / zip code to look for the nearest service providers.
  • motor: required
policy.serviceLevel

Service level is used to determine what kind of service a customer has purchased. Examples: "Basic", "Silver", "Gold"

  • motor: optional
propertyCodeA property code is an extra code that is linked to the vehicle type and which can be used in HUB Motor to select certain repairshops over others. 
The property codes have to be defined in HUB Motor beforehand.
  • motor: optional
includeExternal Indicates whether to return external service providers in addition to internal ones (which are part of IC company network). By default, only internal service providers are returned.
  • motor: optional
maxResultsCount
Maximum results count is self explayning property name used to set maximum number of results to return. The property's maxResultsCount value is used specifically for the case when search for service providers without postalCode and number of results potentially can be big. When address.postalCode parameter is present in request, this paramter is omitted. When making a request without address.postalCode and maxResutlsCount is also unspecified, then all service providers should be returned (depends on includeExternal).

postalCode

Postal / zipcode to look for the nearest service providers.
  • property: mandatory
  • health: mandatory
profession Name of the searched profession. Examples: None, Plumber, Sewer, Carpenter, Electrician, Glazier, Bricklayer, DamageService, WhiteGoodsTechnician, Painter, Roofing, TotalEnterprise, GateMaintenence, DryRotAnalysis, PestControl, FloorFitter, PipelineDredging, MainContractor, Gardener, RefrigerationEngineer, Consultancy, MoistureTechnique, LeakDetection.
  • property: optional
claimSector Name of the searched sector. Examples: Private, Public.
  • property: optional
treatmentType Type of treatment. List of allowed values depends on customer and on what has been set in external system. Examples: HospitalTreatment, Examination, MentalTreatment, PhysicalTreatment, OtherHealthcareServices, AbuseTreatment.
  • health: optional
organizationName Name of the organization that service partner belongs in.
  • health: optional
treatmentTypeText Service provider treatment type as text.
  • health: optional
specialitiesText Type of speciality. List of allowed values depends on customer and on what has been set in external system.
  • health: optional
search Service provider name or part of it that we want to find.
  • health: optional

Appendix A-v2 – Request data description

Query parameter Description Support
company Specific company or brand
  • all: required

serviceType

The serviceType determines the kind of service providers you are searching for. Supported values are: "vehicleRepair", "property", "health".

  • all: required
vehicle.licensePlateNo

The license plate of a vehicle. Should be specified without any punctuation.

Used to identify car brand,modeland other car properties, then it could be used, for example, to filter outrepairshopsthat do not provide repair certain cars.

  • motor: optional
vehicle.brandName Brand name. Used to filter out service providers and return just the ones who provide services for the specified brand.
* The API will not try to recognize the car brand from its license plate if barndName parameter is specified.
  • motor: optional
vehicle.year Car model year. Used in the search logic to select repair shops that have limitation for repaired car age.
  • motor: optional
vehicle.serviceProviderName Service provider name filter option is used to filter out service providers by the name
address.postalCode Postal / zipcode to look for the nearest service providers.
  • motor: optional
address.city City name to look for the service providers in the selected city
policy.serviceLevel

Service level is used to determine what kind of service a customer has purchased. Examples: "Basic", "Silver", "Gold"

  • motor: optional
propertyCode A property code is an extra code that is linked to the vehicle type and which can be used in HUB Motor to select certain repairshopsover others. 
The property codes have to be defined in HUB Motor beforehand.
  • motor: optional
modifiedSince Modified since date indicates the date and time in ISO-8601 format and instructs a service to return service providers which were updated after the specified date.
  • all: optional
dynamicProperty.PropertyId Dynamic properties are evaluated in HUB & CORE business rules. If the dynamic property evaluation failed in business rules for some service provider, the one is excluded from the result list.

Dynamic property parameter could be passed as a collection of GUIDs to the endpoint.

E.g. &dynamicProperty.PropertyId=15E5F951-0035-4DDE-B638-66F95FDBD7E7&dynamicProperty.PropertyId=15E5F951-0035-4DDE-B638-66F95FDBD7E2&dynamicProperty.PropertyId=15E5F951-0035-4DDE-B638-66F95FDBD7E3

  • all: optional
includeExternal Indicates whether to return external service providers in addition to internal ones (which are part of IC company network). By default, only internal service providers are returned.
  • motor: optional
authorizedOnly

Specifies whether to search for authorized service partners only. When using authorizedOnly is true and vehicle.brandName are specified, only authorized service partners for a specified brand will be returned. When the brand is not defined, all the authorized service partnetrs which meet other criteria will be returned.

When authorizedOnly is not specified or is equal to false, both authorized and non-authorized service partners will be returned.

  • motor: optional
start This offsets the starting point of the collection returned from the server in the response.
  • motor: optional
limit This limits the number of results in a response collection returned from the server to a specific number.
  • motor: optional
maxResultsCount

Maximum results count is self explayning property name used to set maximum number of results to return. The property's maxResultsCount value is used to limit calculated result set which then can be additionaly controlled by start and limit to make possible efficient data pagination in search with parameter address.postalCode specified. When search is without address.postalCode specified then start and limit has precedence before maxResultsCount.

  • motor: optional

Appendix B-V1 – Response data description

Root

JSON Path Description
serviceType The serviceType determines the kind of service you are searching for. Supported values are: "vehicleRepair", "property", "health"

Service Providers

An array of found service providers satisfying search criteria.

JSON Path Description Presence

serviceProviders[].externalId

Service provider identifier. Used to refer to it later during case creation request - to assign a case to selected service provider.

See details about format below.

serviceProviders[].name

Name of the service provider. This can be the name of a person or the name of a company.

optional

serviceProviders[].country For example, to specify Denmark, one would use "dk"./div> optional

serviceProviders[].postalCode

Postal / zip code of the service provider address.

optional

serviceProviders[].distance Distance to the repairshop in km optional

serviceProviders[].address

Address of service provider location.

optional

serviceProviders[].city

City of service provider location.

optional

serviceProviders[].email

Contact email of service provider.

optional

serviceProviders[].phone

Contact phone number of service provider.

optional

serviceProviders[].status

Status of service provider. It is quite specific to each product type. For example, it can be a "Red", "Yellow" or "Green" for Motor service providers.

optional

serviceProviders[].statusDescription  

Descriptive explanation of serviceProviders[].status.

optional

serviceProviders[].isExternal Defines if it is ServiceProvider which is not included into the requested network optional
serviceProviders[].description Additional information about service provider optional
serviceProviders[].commercialTaxId Commercial tax number of a service provider optional
serviceProviders[].distance Distance to the repairshop in km optional
serviceProviders[].organization Service provider organization name. optional
serviceProviders[].supplierAccountNo Internal Supplier ID optional

Service provider identifier format

<product_type_prefix>.<local_identifier>
Example: a.06317562-7f4a-4c7e-9ee4-eae06e590c37

All lowercase is recommended for consistency. Guids should be serialized without curly braces for the same reason.

Vehicle

It is needed for Motor because some clients of this API might use this information. They pass vehicle.licensePlateNo in request, Scalepoint identifies brand/model using 3rd party service and can provide that as extra data in response.

JSON Path Description Presence

brand

The brand of the vehicle (e.g. "BMW", "Volvo" or "Ford")

  • motor: optional
model Model description of the vehicle (e.g. "320 Touring", "V70" or "Mondeo")
  • motor: optional
year Model year of the vehicle. Zero if not defined.
  • motor: optional

Appendix B-V2 – Response data description

Root

JSON Path Description

serviceType

The serviceType determines the kind of service you are searching for. Supported values are: "vehicleRepair", "property", "health".

Service Providers

An array of found service providers satisfying search criteria.

JSON Path Description Presence

serviceProviders[].externalId

Service provider identifier. Used to refer to it later during case creation request - to assign a case to selected service provider.

See details about format below.

serviceProviders[].name

Name of the service provider. This can be the name of a person or the name of a company.

optional

serviceProviders[].phone Contact phone number of a service provider.
serviceProviders[].fax Fax number of a service provider optional

serviceProviders[].email

Contact email of a service provider.

serviceProviders[].description

Description of a service provider

optional

serviceProviders[].competences Competences of a service provider optional
serviceProviders[].commercialTaxId Commercial tax number of a service provider optional
serviceProviders[].distance Distance to the repairshop in km optional
serviceProviders[].externalSystemId Identifier of service provider in context of external system optional
serviceProviders[].workSchedule.monday Service provider working hours (e.g. "07:30 - 17:00") optional
serviceProviders[].workSchedule.tuesday Service provider working hours (e.g. "07:30 - 17:00") optional
serviceProviders[].workSchedule.wednesday Service provider working hours (e.g. "07:30 - 17:00") optional
serviceProviders[].workSchedule.thursday Service provider working hours (e.g. "07:30 - 17:00") optional
serviceProviders[].workSchedule.friday Service provider working hours (e.g. "07:30 - 17:00") optional
serviceProviders[].workSchedule.saturday Service provider working hours (e.g. "Lukket") optional
serviceProviders[].workSchedule.sunday Service provider working hours (e.g. "Lukket") optional
serviceProviders[].contacts[].name Service provider contact person name optional
serviceProviders[].closedCasesStatistics.totalCases Count of all closed cases optional
serviceProviders[].closedCasesStatistics.totalCasesLastYear Count of closed cases for the last year optional
serviceProviders[].availability.status

Status of a service provider. It is quite specific to each product type. For example, it can be an "R" (red), "Y" (yellow) or "G" (green) for Motor service providers. Meaning: red (R) - service provider doesn't work (vacation). Yellow (Y) - long waiting time. A service provider is loaded. Green (G) - service provider works and is opened to get new clients.

optional

serviceProviders[].availability.description A short description of current service provider state. optional

serviceProviders[].availability.vacation

Boolean indicator if a service provider is on vacation

optional

serviceProviders[].address.country For country codes, Scalepoint uses values as defined by ISO 3166-1 alpha-2, albeit in lowercase. 
For example, to specify Denmark, one would use "dk".

serviceProviders[].address.city

City of service provider location.

serviceProviders[].address.postalCode

Postal/zip code of the service provider address.

optional

serviceProviders[].address.street1

Address of service provider location.


serviceProviders[].address.street2 Second address of a service provider location optional
serviceProviders[].paymentMethods[].type Payment method type. By default: 'bankAccount' optional
serviceProviders[].paymentMethods[].branchNumber Bank branch number optional
serviceProviders[].paymentMethods[].accountNumber Bank account number optional
serviceProviders[].specialties.carBrands[].name The brand of the vehicle that service provider specializes (e.g. "BMW", "Volvo" or "Ford"). The "All" in brand name is used to indicate that service provider is specialized in any type of brand optional
serviceProviders[].specialties.carBrands[].authorized Indicates if service provider is authorized for the brand optional
serviceProviders[].isExternal Defines if it is ServiceProvider which is not included into the requested network

serviceProviders[].organization Service provider organization name. optional
serviceProviders[].supplierAccountNo Internal Supplier ID optional
serviceProviders[].lastModificationDate Service provider last modification date.
total The total property in the response states the actual number of entities returned by the search (including the ones that are brought by the specific page).
serviceLevelMatch The serviceLevelMatch property returns "false" when the passed serviceLevel/DynamicProperty has not matched any repair shops, and the "Standard" repair shops were returned as a result. By default when serviceLevel/dynamicProperty is not provided the serviceLevelMatch property also returns "false".

Service provider identifier format

<product_type_prefix>.<local_identifier>
Example: a.06317562-7f4a-4c7e-9ee4-eae06e590c37

All lowercase is recommended for consistency. Guids should be serialized without curly braces for the same reason.

Vehicle

It is needed for Motor because some clients of this API might use this information. They pass vehicle.licensePlateNo in request, Scalepoint identifies brand/model using 3rd party service and can provide that as extra data in response.

JSON Path Description Presence

brand

The brand of the vehicle (e.g. "BMW", "Volvo" or "Ford")

  • motor: optional
model Model description of the vehicle (e.g. "320 Touring", "V70" or "Mondeo")
  • motor: optional

Appendix C - Swagger description for endpoint request

This is more relevant for documenting request data, because it doesn't have JSON schema. But just for sake of completeness - it also describes response.

swagger: '2.0'
info:
  title: Search Service Providers API
  description: Allows to search service providers based on specified criterias
  version: "1.0.0"
host: www.scalepoint.com
schemes:
  - https
basePath: /api/integration
produces:
  - application/json
paths:
  /data/<version>/<country>/<tenant>/service-providers:
    get:
      summary: Service Providers
      description: |
        The Search Service Providers endpoint returns information about the searched service providers.
        The response includes the display name, unique identifier and other details about each service provider, and lists them all in the proper display order.
      parameters:
        - name: company
          in: query
          description: One or more company values will be assigned by Scalepoint to support your company/brands.
          required: true
          type: string
        - name: serviceType
          in: query
          description: The serviceType determines the kind of service providers you are searching for.
          required: true
          type: string
        - name: vehicle.licensePlateNo
          in: query
          description: The licenseplate of the vehicle. Should be specified without any punctuation.
          required: false
          type: string
        - name: vehicle.serviceProviderName
          in: query
          description: Service provider name filter option is used to filter out service providers by the name.
          required: false
          type: string
        - name: address.postalCode
          in: query
          description: Postal / zip code to look for the nearest service providers.
          required: false
          type: string
        - name: address.city
          in: query
          description: City name to look for the service providers in the selected city.
          required: false
          type: string
        - name: policy.serviceLevel
          in: query
          description: Service level is used to determine what kind of service a customer has purchased.
          required: false
          type: string
        - name: propertyCode
          in: query
          description: A property code is an extra code that is linked to the vehicle type and which can be used in HUB Motor to select certain repairshops over others.
          required: false
          type: string
        - name: modifiedSince
          in: query
          description: A date which specifies to return service providers which were modified after the specified date.
          required: false
          type: string
        - name: dynamicProperty.PropertyId
          in: query
          description: Dynamic property is used to determine which property (option) a service provider should support. Should be GUID.
          required: false
          type: string
      tags:
        - Service Providers

Appendix D – External references

Country codes

https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2