Best Matching Technician API

1.1 Overview

The Best Matching Technician API enables customers to automatically find the best matching technician for an activity/service call. The process is plugin based and creates additional value for the customer through the possibility of customized plugins that fit specific business needs.

1.1.1 Swagger

You can find a swagger ui for api definitions and tests here:


1.1.2 Request Methods

The following methods are supported by the BMT API:

  Note Section POST one activity/service call and options to bmt api 1.3

1.2 Access

The BMT API uses Oauth 2.0 for authentication. This token is then used in the Authorization header as the bearer.

Attention: In order to receive an access token, you must have ADMINISTRATOR or SUPERUSER privileges.

1.2.1 Get Access Token

The following example shows how to get the access token for a Cloud Account or a Company User:

Cloud Account

The following example is an example of authentication for a Coresystems Cloud account with access to all companies within the account:


Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded


Company User

The following example of authentication for a company user, with access to companies controlled by existing subscription and permission settings:


Authorization Basic dGVzdDpzZWNyZXQ=
Content-Type application/x-www-form-urlencoded


1.2.2 Response

The following is an example of a typical response:

  "access_token": "77cf4834-a347-4849-839b-4518823a739e",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "general",
  "cluster_url": "",
  "account": "testaccount",
  "account_id" : 284,
  "user": "manager",
  "user_email": "",
  "companies": [
      "id": 957,
      "name": "SBODemoCH",
      "description": "OEC Computers (Schweiz)"

1.2.3 Error Response

  "error": "invalid_grant",
  "error_description": "Bad credentials"

1.2.4 Supported Clusters

Depending on the location of the account, requests will be made to one of the following server clusters:

  • EU
  • DE
  • US

Attention: please note that the CN (China) cluster is currently NOT supported.

1.3 POST best-match

Accept activity by technician.

1.3.1 Request

Method URL
POST https://{cluster}

1.3.2 Headers

Header Description Required
x-client-id The alphanumerical ID associated with the client. Required
x-account-id The integer ID of the account. Required
x-company-id The integer ID of the company. Required
x-company-name The string based name of the company Required
x-account-name The string based name of the account Required
x-request-id The request id for traceability through systems Required

1.3.3 Body

Value Description Type Required
objectId The ID of the activity/service call to be matched String Required
objectType The type of object to be matched, can either be ‘ACTIVITY’ or ‘SERVICECALL’ String Required
optimizationPlugin Name of plugin to be used. If no custom plugins are present, defaults to choose are: ‘Best’, ‘Nearest’ and ‘Quickest’ String Required
companyNames Array of companies of which resources are considered by matching Array/string Optional

Scheduling options:

Value Description Type Required
spanJobs Jobs will be spanned over non-working time. Default true Boolean Optional
computeDrivingTime Determines if driving times will be considered. Default true Boolean Optional
defaultDrivingTimeMinutes Default is 30 minutes Integer Optional
overlapBookings Determines if technicians with overlapping bookings will be considered. Default true Boolean Optional
maxResults Number of returned result. Default 10 Integer Optional
timezoneId Default time zone to be considered, if no location is present in activity. Must be of format ‘Europe/Berlin’. Default null String Optional


Value Description Type Required
includeInternalPersons Default true Boolean Optional
includeCrowdPersons Default false Boolean Optional
personIds Only consider technicians from this array Array/string Optional

The following is an example of a posted Best-Match request sent to the BMT API:

  "objectType": "ACTIVITY",
  "objectId": "string",
  "optimizationPlugin": "string",
  "companyNames": [
  "schedulingOptions": {
    "spanJobs": true,
    "computeDrivingTime": true,
    "defaultDrivingTimeMinutes": 30,
    "overlapBookings": true,
    "maxResults": 10,
    "timezoneId": "string"
  "resources": {
    "includeInternalPersons": true,
    "includeCrowdPersons": true,
    "personIds": [

1.3.4 Response

Status Response
200 OK
400 Bad Request
500 Internal Server Error

1.3.5 Example Response

  "results": [
      "job": {
        "id": "string",
        "startDateTime": "string",
        "endDateTime": "string",
        "trip": {
          "durationInMinutes": 0,
          "distanceInMeters": 0
      "resource": "string",
      "matchingScore": 0,
      "matchingSkills": [
      "missingSkills": [
      "availability": "string",
      "resourceType": "PERSON"